ข้ามไปยังเนื้อหา

API แท็กอ็อบเจกต์ (เบต้า)

แท็กอ็อบเจกต์เก็บข้อมูลแบบมีโครงสร้างเกี่ยวกับผู้ใช้ไว้ในแท็กเดียว แท็กประเภท Object เก็บอ็อบเจกต์หนึ่งรายการที่มีฟิลด์ตั้งชื่อไว้ เช่น order ล่าสุดพร้อม amount และ status แท็กประเภท ObjectList เก็บอาร์เรย์ของอ็อบเจกต์ดังกล่าว เช่น orders ทั้งหมด ฟิลด์เองก็เป็นอ็อบเจกต์หรือรายการอ็อบเจกต์ได้ เช่น address ของ profile คุณกำหนดฟิลด์เพียงครั้งเดียว จากนั้นเขียนและอ่านค่าผ่าน API ของแท็ก สร้างเซกเมนต์ตามค่าของฟิลด์ และแทรกค่าลงในข้อความด้วย Liquid ได้

วิธีการทำงานของแท็กอ็อบเจกต์

Anchor link to

แท็กอ็อบเจกต์มีสคีมาและค่า สคีมาคือชื่อแท็กและรายการฟิลด์ โดยแต่ละฟิลด์มีประเภทของตัวเอง ค่าจะถูกเก็บไว้ในฟิลด์ แยกกันสำหรับผู้ใช้แต่ละคน

  • ฟิลด์ แต่ละฟิลด์คือแท็กชื่อ <object>.<field> เช่น order.amount คุณสร้างเซกเมนต์ตามฟิลด์ และเขียนฟิลด์ของแท็ก Object ด้วยชื่อนี้ได้
  • ค่า Object อ็อบเจกต์หนึ่งรายการต่อผู้ใช้ เช่น "order": {"amount": 120, "status": "paid"}
  • ค่า ObjectList อาร์เรย์ของอ็อบเจกต์ที่มีฟิลด์เดียวกัน เช่น "orders": [{"amount": 120, "status": "paid"}, {"amount": 50}]
  • อ็อบเจกต์ซ้อน ฟิลด์ประเภท OBJECT ที่มีฟิลด์ของตัวเอง เช่น profile.address ที่มีฟิลด์ profile.address.city
  • รายการซ้อน ฟิลด์ประเภท OBJECT_LIST ซึ่งเป็นอาร์เรย์ของอ็อบเจกต์ภายในแท็กอ็อบเจกต์ เช่น profile.visits ดู อ็อบเจกต์ซ้อนและรายการซ้อน

ใน API ประเภทของแท็กและฟิลด์คือ OBJECT และ OBJECT_LIST ใน Control Panel คือ ออบเจ็กต์ และ รายการออบเจ็กต์ ในหน้านี้ รายการอ็อบเจกต์หมายถึงแท็ก ObjectList หรือรายการซ้อน

แท็กอ็อบเจกต์เป็นแท็ก User-specific เสมอ หมายความว่าค่าเป็นของผู้ใช้ ไม่ใช่ของอุปกรณ์เครื่องใดเครื่องหนึ่ง และจะถูกคัดลอกไปยังอุปกรณ์ทั้งหมดของผู้ใช้ ดู Tags API สำหรับแท็กทั่วไป

อ็อบเจกต์ซ้อนและรายการซ้อน

Anchor link to

ฟิลด์ของแท็กอ็อบเจกต์เก็บฟิลด์ของตัวเองแทนค่าเดี่ยวได้ อ็อบเจกต์ซ้อนคือฟิลด์ประเภท OBJECT ที่เก็บอ็อบเจกต์หนึ่งรายการ รายการซ้อนคือฟิลด์ประเภท OBJECT_LIST ที่เก็บรายการอ็อบเจกต์ องค์ประกอบของรายการก็มีอ็อบเจกต์ซ้อนและรายการซ้อนได้เช่นกัน แต่ละฟิลด์ใช้ชื่อเต็มแบบมีจุด เช่น profile.address.city และคุณสร้างเซกเมนต์ตามชื่อเหล่านี้

ตัวอย่างเช่น แท็ก profile ประเภท OBJECT และแท็ก orders ประเภท OBJECT_LIST อาจมีโครงสร้างดังนี้:

profile OBJECT
├── address OBJECT
│ ├── city STRING
│ └── geo OBJECT
│ └── lat STRING
└── visits OBJECT_LIST
└── code STRING
orders OBJECT_LIST
├── sku STRING
├── meta OBJECT
│ └── color STRING
└── lines OBJECT_LIST
└── qty INTEGER

ฟิลด์ที่ค้นหาได้และฟิลด์ที่จัดเก็บเท่านั้น

Anchor link to

สิ่งที่คุณทำกับฟิลด์ได้ขึ้นอยู่กับจำนวนรายการอ็อบเจกต์ที่อยู่เหนือฟิลด์นั้น:

  • ไม่มีรายการอยู่เหนือฟิลด์ คุณสร้างเซกเมนต์ตามฟิลด์ เช่น profile.address.city เขียนฟิลด์นั้นแยกด้วยชื่อเต็ม และใช้ในข้อความได้
  • มีรายการหนึ่งรายการอยู่เหนือฟิลด์ คุณสร้างเซกเมนต์ตามฟิลด์ เช่น profile.visits.code หรือ orders.meta.color และใช้ในข้อความได้ เขียนฟิลด์นั้นได้เฉพาะเป็นส่วนหนึ่งของทั้งรายการ
  • มีสองรายการอยู่เหนือฟิลด์ ฟิลด์ เช่น orders.lines.qty เป็นแบบจัดเก็บเท่านั้น ใช้ใน ข้อความ ได้ แต่ใช้ในเซกเมนต์ไม่ได้

ข้อจำกัด

Anchor link to

Pushwoosh ใช้ข้อจำกัดเหล่านี้กับแท็กอ็อบเจกต์ รวมถึงอ็อบเจกต์ซ้อนและรายการซ้อน:

ข้อจำกัดค่าเมื่อเกินข้อจำกัด
ความลึกของการซ้อนอ็อบเจกต์และรายการ 3 ระดับ ตัวแท็กเองคือระดับแรก ดังนั้น profile.address.geo จึงเป็นอ็อบเจกต์ที่ลึกที่สุดที่อนุญาตเมธอดสคีมาส่งคืน HTTP 400 ดู ข้อผิดพลาด
จำนวนฟิลด์ในอ็อบเจกต์หนึ่ง1 ถึง 20 สำหรับตัวแท็กและสำหรับอ็อบเจกต์ซ้อนหรือรายการซ้อนแต่ละรายการเมธอดสคีมาส่งคืน HTTP 400 ดู ข้อผิดพลาด
จำนวนฟิลด์ที่มีค่าในแท็กอ็อบเจกต์หนึ่ง50 รวมฟิลด์ที่ซ้อนอยู่ ไม่นับฟิลด์ประเภท OBJECT และ OBJECT_LISTเมธอดสคีมาส่งคืน HTTP 400 ดู ข้อผิดพลาด
ชื่อฟิลด์แบบเต็ม64 อักขระ เช่น profile.address.cityเมธอดสคีมาส่งคืน HTTP 400 ดู ข้อผิดพลาด
จำนวนองค์ประกอบในรายการอ็อบเจกต์หนึ่ง100 สำหรับตัวแท็กและสำหรับรายการซ้อนแต่ละรายการค่าที่เขียนทั้งหมดถูกปฏิเสธ
ขนาดของค่าที่เขียนหนึ่งครั้งJSON 64 KBค่าที่เขียนทั้งหมดถูกปฏิเสธ

ค่าที่ถูกปฏิเสธจะได้รับการจัดการแบบเดียวกับค่าที่มีประเภทฟิลด์ไม่ถูกต้อง ดู การเขียนจะแทนที่ค่าทั้งหมด

กฎของสคีมา

Anchor link to

Pushwoosh ตรวจสอบกฎเหล่านี้เมื่อคุณสร้างแท็กอ็อบเจกต์หรือเพิ่มฟิลด์:

  • ชื่ออ็อบเจกต์และชื่อฟิลด์มีได้เฉพาะตัวอักษรละติน ตัวเลข และ _
  • ตัวแท็กและอ็อบเจกต์ซ้อนหรือรายการซ้อนแต่ละรายการมีฟิลด์ 1 ถึง 20 ฟิลด์ ข้อจำกัด อื่นๆ ก็มีผลเช่นกัน ชื่อฟิลด์ไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ ดังนั้น Amount และ amount จึงเป็นฟิลด์เดียวกัน
  • ฟิลด์มีประเภทใดประเภทหนึ่งต่อไปนี้: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT, OBJECT_LIST ฟิลด์ประเภท OBJECT หรือ OBJECT_LIST ต้องมี fields ของตัวเอง ไม่รองรับฟิลด์เขตเวลา
  • ฟิลด์ไม่สามารถใช้ชื่อที่แท็กอื่นใช้อยู่แล้ว หากมีแท็ก order.note อยู่ การเพิ่มฟิลด์ note ให้กับ order จะล้มเหลวพร้อม tag order.note already exists
  • อ็อบเจกต์ไม่สามารถลบฟิลด์สุดท้ายได้ ให้ลบอ็อบเจกต์แทน
  • ไม่สามารถลบฟิลด์หรือแท็กอ็อบเจกต์ที่กำลังใช้งานอยู่ได้ อ็อบเจกต์ซ้อนหรือรายการซ้อนนับว่ากำลังใช้งานเมื่อมีสิ่งใดภายในถูกใช้งานอยู่ ข้อผิดพลาดจะแสดงรายการตำแหน่งที่ใช้งาน เช่น field is in use: segment Big buyers, in-app Spring sale เซกเมนต์, in-app, แคมเปญ Customer Journey ที่กำลังทำงาน, พรีเซ็ต, เทมเพลตอีเมล และรายการอื่นๆ ที่อ้างอิงแท็กนั้นนับเป็นการใช้งาน

จัดการแท็กอ็อบเจกต์ใน Control Panel

Anchor link to

สร้างแท็กอ็อบเจกต์ที่ไม่มีอ็อบเจกต์ซ้อนและรายการซ้อนใน Control Panel:

  1. ในหน้า แท็ก ของ Control Panel ให้คลิก สร้างแท็ก
  2. ป้อน ชื่อแท็ก
  3. ใน ประเภทค่า ให้เลือก ออบเจ็กต์ หรือ รายการออบเจ็กต์
  4. ใต้ ฟิลด์ ให้ป้อนชื่อของฟิลด์แรก
  5. เลือกประเภทของฟิลด์
  6. หากต้องการเพิ่มฟิลด์อื่น ให้คลิก เพิ่มฟิลด์
  7. คลิก สร้าง

ในหน้าของแท็ก คุณเพิ่มฟิลด์ได้ หรือคลิก ลบ ข้างฟิลด์เพื่อลบฟิลด์นั้น Control Panel สร้างอ็อบเจกต์ซ้อนหรือรายการซ้อน หรือเปลี่ยนฟิลด์ของสิ่งเหล่านี้ไม่ได้ อ็อบเจกต์ซ้อนหรือรายการซ้อนที่สร้างผ่าน API จะแสดงเป็นฟิลด์เดียวประเภท ออบเจ็กต์ หรือ รายการออบเจ็กต์ การลบฟิลด์นั้นจะลบทุกอย่างที่อยู่ภายในด้วย

จัดการสคีมา

Anchor link to

สร้างและเปลี่ยนแท็กอ็อบเจกต์ด้วยเมธอด REST ด้านล่าง ใช้ /json/1.3/addTag เฉพาะกับแท็กทั่วไป เนื่องจากเมธอดนี้กำหนดฟิลด์ไม่ได้

https://rpc-api.svc-nue.pushwoosh.com

การรับรองความถูกต้อง

Anchor link to

ทุกคำขอต้องมี Authorization header พร้อมกับ Server API token ของคุณ หากใช้ Device API token จะได้รับ HTTP 403 a device API token cannot call this method, use an account API token

Authorization: Api YOUR_API_TOKEN

เมธอดเหล่านี้ใช้จัดการสคีมาของแท็กอ็อบเจกต์และอ่านค่าของฟิลด์:

เมธอดพาธคำอธิบาย
POST/api/tagsสร้างแท็กอ็อบเจกต์พร้อมฟิลด์
GET/api/tags/{name}ดึงแท็กอ็อบเจกต์พร้อมฟิลด์
GET/api/tagsแสดงรายการแท็ก แท็กอ็อบเจกต์จะมาพร้อม fields ทั้งหมด รวมถึงฟิลด์ที่ซ้อนอยู่ และฟิลด์จะไม่แสดงเป็นแท็กแยก
POST/api/tags/{name}/fieldsเพิ่มฟิลด์ให้กับแท็กอ็อบเจกต์ อ็อบเจกต์ซ้อน หรือรายการซ้อน
DELETE/api/tags/{name}/fields/{field}ลบฟิลด์ อ็อบเจกต์ซ้อน หรือรายการซ้อน
DELETE/api/tags/{name}ลบแท็กอ็อบเจกต์พร้อมฟิลด์ทั้งหมด
GET/api/tags:valuesแสดงรายการค่าที่จัดเก็บไว้ของฟิลด์ ดู ค่าที่จัดเก็บไว้ของฟิลด์

POST /api/tags ส่งคืนแท็กอ็อบเจกต์ และเมธอดของฟิลด์ทั้งสองส่งคืนอ็อบเจกต์ที่ระบุใน {name} หลังการเปลี่ยนแปลง โดยห่อไว้ใน {"tag": {...}} ส่วน DELETE /api/tags/{name} ส่งคืน {}

หากบัญชีของคุณไม่ได้เปิดใช้งานแท็กอ็อบเจกต์ POST /api/tags ที่ใช้ประเภทอ็อบเจกต์และเมธอดของฟิลด์ทั้งสองจะล้มเหลวพร้อม HTTP 403 object tags are not enabled for the account ส่วน GET /api/tags/{name} และ DELETE /api/tags/{name} จะส่งคืน HTTP 404 tag not found และ GET /api/tags จะไม่แสดงแท็กอ็อบเจกต์ เมื่อไม่ได้เปิดใช้งานแท็กอ็อบเจกต์ คุณจะสร้างแท็กอ็อบเจกต์ไม่ได้ จึงไม่มีอะไรให้เขียนค่า

สร้างแท็กอ็อบเจกต์

Anchor link to

POST /api/tags

เนื้อหาของคำขอ
Anchor link to
ชื่อประเภทคำอธิบาย
name*stringชื่อของแท็กอ็อบเจกต์
type*stringOBJECT สำหรับอ็อบเจกต์เดียว หรือ OBJECT_LIST สำหรับรายการอ็อบเจกต์
fields*arrayฟิลด์ของอ็อบเจกต์ 1 ถึง 20 ฟิลด์
fields[].name*stringชื่อฟิลด์ ฟิลด์จะกลายเป็นแท็ก <name>.<fields[].name>
fields[].type*stringประเภทฟิลด์: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT หรือ OBJECT_LIST
fields[].fieldsarrayฟิลด์ของอ็อบเจกต์ซ้อนหรือรายการซ้อน 1 ถึง 20 ฟิลด์ ในรูปแบบเดียวกัน จำเป็นสำหรับประเภท OBJECT และ OBJECT_LIST และจะถูกละเว้นสำหรับประเภทอื่น
ตัวอย่าง
{
"name": "orders",
"type": "OBJECT_LIST",
"fields": [
{ "name": "amount", "type": "INTEGER" },
{ "name": "status", "type": "STRING" }
]
}
การตอบกลับ
{
"tag": {
"name": "orders",
"type": "OBJECT_LIST",
"system": false,
"user_specific": true,
"has_right_ace_modify": true,
"fields": [
{ "name": "amount", "type": "INTEGER", "fields": [] },
{ "name": "status", "type": "STRING", "fields": [] }
]
}
}

แท็กจะถูกสร้างเป็น User-specific เสมอ ไม่ว่าค่า user_specific จะเป็นอะไร GET /api/tags/{name} ส่งคืนอ็อบเจกต์เดียวกันโดยไม่มีตัวห่อ tag ฟิลด์จะเรียงตามชื่อ และฟิลด์ที่ไม่มีฟิลด์ซ้อนจะมาพร้อมอาร์เรย์ fields ว่าง

หากต้องการสร้างอ็อบเจกต์ซ้อนและรายการซ้อน ให้กำหนดประเภท OBJECT หรือ OBJECT_LIST และ fields ของตัวเองให้กับฟิลด์ คำขอเดียวจะสร้างโครงสร้างทั้งหมด:

ตัวอย่าง: แท็ก profile จากอ็อบเจกต์ซ้อนและรายการซ้อน
{
"name": "profile",
"type": "OBJECT",
"fields": [
{
"name": "address",
"type": "OBJECT",
"fields": [
{ "name": "city", "type": "STRING" },
{ "name": "geo", "type": "OBJECT", "fields": [{ "name": "lat", "type": "STRING" }] }
]
},
{
"name": "visits",
"type": "OBJECT_LIST",
"fields": [{ "name": "code", "type": "STRING" }]
}
]
}

ฟิลด์ที่ซ้อนอยู่จะส่งคืนพร้อมชื่อที่สัมพันธ์กับอ็อบเจกต์ของตัวเอง เช่น city ภายใน address GET /api/tags/{name} รับเฉพาะชื่อของตัวแท็กเอง ชื่อที่ซ้อน เช่น profile.address จะส่งคืน HTTP 404 tag not found

เพิ่มฟิลด์

Anchor link to

POST /api/tags/{name}/fields

ตัวอย่าง: POST /api/tags/orders/fields
{
"field": { "name": "note", "type": "STRING" }
}

หากต้องการเพิ่มฟิลด์ให้กับอ็อบเจกต์ซ้อนหรือรายการซ้อน ให้ใส่ชื่อเต็มใน {name} เช่น POST /api/tags/profile.address/fields หรือ POST /api/tags/profile.visits/fields ฟิลด์ใหม่อาจเป็นอ็อบเจกต์ซ้อนหรือรายการซ้อนที่มี fields ของตัวเองได้:

ตัวอย่าง: POST /api/tags/profile/fields
{
"field": {
"name": "company",
"type": "OBJECT",
"fields": [{ "name": "title", "type": "STRING" }]
}
}

คุณเขียนฟิลด์ใหม่ได้ทันทีโดยเป็นส่วนหนึ่งของค่าแท็กทั้งหมด การเพิ่มฟิลด์จะล้มเหลวหากอ็อบเจกต์มี 20 ฟิลด์อยู่แล้ว หากฟิลด์ละเมิด ข้อจำกัด อื่น หรือมีแท็กที่ใช้ชื่อฟิลด์แบบเต็มนั้นอยู่แล้ว ดู ข้อผิดพลาด

ลบฟิลด์

Anchor link to

DELETE /api/tags/{name}/fields/{field}

ตัวอย่างเช่น DELETE /api/tags/orders/fields/note จะลบฟิลด์ orders.note หากต้องการลบฟิลด์ของอ็อบเจกต์ซ้อนหรือรายการซ้อน ให้ใส่ชื่อเต็มใน {name}: DELETE /api/tags/profile.address/fields/city

การลบอ็อบเจกต์ซ้อนหรือรายการซ้อนจะลบทุกอย่างที่อยู่ภายใน: DELETE /api/tags/profile/fields/address จะลบ profile.address.city และ profile.address.geo ด้วย คุณไม่สามารถลบฟิลด์สุดท้ายของอ็อบเจกต์ หรือฟิลด์ อ็อบเจกต์ซ้อน หรือรายการซ้อนที่กำลังใช้งานอยู่ได้ ดู ข้อผิดพลาด

ข้อผิดพลาด

Anchor link to

ข้อผิดพลาดมีรูปแบบ {"code": <n>, "message": "...", "details": [...]} เมื่อคุณสร้างแท็กอ็อบเจกต์ ข้อความ 400 จะอยู่ในรูปแบบ validate: rpc error: code = InvalidArgument desc = <message> โดย <message> คือข้อความในตาราง ในข้อความเหล่านี้ <object> คือชื่อเต็มของอ็อบเจกต์ เช่น profile.address

สถานะ HTTPข้อความสาเหตุ
400object tag and field names must contain only letters, digits and underscoresชื่อมีอักขระอื่น
400<object>: an object needs 1 to 20 fieldsตอนสร้าง ตัวแท็ก อ็อบเจกต์ซ้อน หรือรายการซ้อนไม่มีฟิลด์หรือมีฟิลด์มากกว่า 20 ฟิลด์
400an object has at most 20 fieldsอ็อบเจกต์ที่คุณเพิ่มฟิลด์มี 20 ฟิลด์อยู่แล้ว
400<object>.<field>: objects nest at most 3 levels deepฟิลด์ OBJECT หรือ OBJECT_LIST จะอยู่ในระดับที่สี่
400an object tag holds at most 50 fields with values, nested ones includedแท็กอ็อบเจกต์จะมีฟิลด์ที่มีค่ามากกว่า 50 ฟิลด์
400field <name> is given twiceมีสองฟิลด์ที่ชื่อเหมือนกันเมื่อไม่คำนึงถึงตัวพิมพ์เล็กใหญ่
400<object>.<field>: object and field names together cannot be longer than 64 charactersชื่อฟิลด์แบบเต็มยาวเกินไป
400<object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LISTประเภทฟิลด์ที่ไม่รองรับ
400an object needs at least one field; delete the object insteadคุณพยายามลบฟิลด์สุดท้ายของอ็อบเจกต์
400field is in use: ..., tag is in use: ...ฟิลด์ สิ่งใดภายในอ็อบเจกต์ซ้อนหรือรายการซ้อน หรือแท็กอ็อบเจกต์ถูกใช้ในเซกเมนต์, in-app, แคมเปญ Customer Journey หรือรายการอื่นๆ
403object tags are not enabled for the accountบัญชีไม่ได้เปิดใช้งานแท็กอ็อบเจกต์
403a device API token cannot call this method, use an account API tokenคำขอใช้ Device API token
404tag not foundGET หรือ DELETE /api/tags/{name}: ไม่มีแท็กนี้ ชื่อนั้นเป็นฟิลด์ หรือไม่ได้เปิดใช้งานแท็กอ็อบเจกต์
404object tag not found, field not foundเมธอดของฟิลด์: ไม่มีแท็กอ็อบเจกต์ อ็อบเจกต์ซ้อน รายการซ้อน หรือฟิลด์นี้ {name} ที่เป็นฟิลด์ที่มีค่าก็ส่งคืน object tag not found เช่นกัน
409tag already existsมีแท็กที่ใช้ชื่อเดียวกับแท็กอ็อบเจกต์อยู่แล้ว
409tag <object>.<field> already existsมีแท็กที่ใช้ชื่อเต็มของฟิลด์อยู่แล้ว

เขียนค่า

Anchor link to

เขียนค่าแท็กอ็อบเจกต์ด้วย /setTags และ /bulkSetTags เมธอดเหล่านี้ใช้การรับรองความถูกต้องแบบเดิมของตัวเอง: /setTags รับ Device API token ใน header Authorization: Token และ /bulkSetTags รับ API access token ใน auth ส่งค่า Object เป็นอ็อบเจกต์ JSON และส่งค่า ObjectList เป็นอาร์เรย์ของอ็อบเจกต์:

ตัวอย่าง: /json/1.3/setTags
{
"request": {
"application": "XXXXX-XXXXX",
"userId": "user_42",
"tags": {
"order": { "amount": 120, "status": "paid" },
"orders": [
{ "amount": 120, "status": "paid" },
{ "amount": 50 }
]
}
}
}

หากคุณตั้งค่าด้วย HWID ค่าจะถูกเก็บไว้ที่ผู้ใช้ของอุปกรณ์นั้น POST /api/devices:set_tags บน Base URL ของเมธอดสคีมาจะเขียนแท็กอ็อบเจกต์ตามกฎเดียวกัน การตอบกลับของเมธอดนี้จะแสดงฟิลด์ของอ็อบเจกต์เป็นชื่อแบบแบน เช่น "profile.address.city"

อ็อบเจกต์ซ้อนรับอ็อบเจกต์ JSON และรายการซ้อนรับอาร์เรย์ของอ็อบเจกต์:

ตัวอย่าง: ค่าที่ซ้อนใน /json/1.3/setTags
"tags": {
"profile": {
"address": { "city": "Berlin", "geo": { "lat": "52.5" } },
"visits": [{ "code": "v1" }]
},
"orders": [
{ "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] }
]
}

แต่ละฟิลด์รับค่าในรูปแบบตามประเภทของฟิลด์:

ประเภทฟิลด์ตัวอย่างค่า
INTEGER120
STRING"paid"
LIST["gift", "express"]
DATE"2026-10-02 22:11" (UTC), "2026-10-02" หรือ Unix timestamp เป็นวินาที
BOOLEANtrue หรือ false
PRICE19.95
VERSION"1.0.0"

การเขียนจะแทนที่ค่าทั้งหมด

Anchor link to

การเขียนแต่ละครั้งจะแทนที่ค่าที่เก็บไว้ของแท็กอ็อบเจกต์:

  • ฟิลด์ที่ไม่มีในค่าใหม่จะถูกลบ ฟิลด์ที่ส่งเป็น null ก็จะถูกลบเช่นกัน
  • null, [] หรือ "" จะลบค่าทั้งหมด
  • {} จะลบฟิลด์ทั้งหมดของแท็ก Object
  • คีย์ที่ไม่ใช่ฟิลด์ของอ็อบเจกต์จะถูกข้าม
  • หากค่าของฟิลด์ในระดับใดก็ตามไม่ตรงกับประเภทฟิลด์ ค่าทั้งหมดของแท็กจะถูกปฏิเสธ และค่าที่เก็บไว้จะยังคงเหมือนเดิม เช่นเดียวกันหากค่าละเมิด ข้อจำกัด: รายการที่มีองค์ประกอบมากกว่า 100 รายการ หรือ JSON ที่มีขนาดเกิน 64 KB

/setTags จะไม่แจ้งค่าที่ถูกปฏิเสธในการตอบกลับ และส่งคืน HTTP 200 ตรวจสอบผลลัพธ์ด้วย /getTags หรือใช้ /bulkSetTags ซึ่งจะแจ้งผลลัพธ์สำหรับแต่ละแท็ก

ฟิลด์ที่ซ่อน

Anchor link to

ฟิลด์ที่ซ่อนคือฟิลด์ที่ Pushwoosh ทำเครื่องหมายว่าซ่อนไว้เพื่อใช้งานเอง คุณไม่สามารถสร้างหรือซ่อนฟิลด์ด้วยเมธอดสคีมาในหน้านี้ /getTags ไม่ส่งคืนฟิลด์ที่ซ่อน ดังนั้นค่าที่คุณอ่านแล้วเขียนกลับจะไม่มีฟิลด์เหล่านี้ สิ่งที่เกิดขึ้นกับฟิลด์ที่ซ่อนเมื่อเขียนขึ้นอยู่กับประเภท:

  • Object ฟิลด์ที่ซ่อนซึ่งไม่มีในค่าใหม่จะยังคงอยู่ในทุกระดับความลึก อ็อบเจกต์ซ้อนที่มองเห็นได้ซึ่งไม่มีในค่าใหม่จะถูกลบพร้อมทุกอย่างภายใน รวมถึงฟิลด์ที่ซ่อน การลบค่าทั้งหมดจะลบฟิลด์ที่ซ่อนด้วย
  • ObjectList การเขียนรายการจะแทนที่องค์ประกอบทั้งหมด และฟิลด์ที่ซ่อนขององค์ประกอบเดิมจะหายไป องค์ประกอบไม่มีตัวระบุ จึงจับคู่องค์ประกอบใหม่กับองค์ประกอบเดิมไม่ได้ รายการซ้อนก็เป็นเช่นเดียวกัน

เขียนบางส่วนของ Object

Anchor link to

เขียนฟิลด์เดียว อ็อบเจกต์ซ้อน หรือรายการซ้อนของแท็ก Object ด้วยชื่อเต็ม แทนการเขียนค่าแท็กทั้งหมด increment และการดำเนินการอื่นๆ ของ /setTags ใช้กับฟิลด์ได้:

"tags": {
"order.status": "shipped",
"order.amount": { "operation": "increment", "value": 5 }
}

วิธีเดียวกันนี้ใช้ได้กับฟิลด์ของอ็อบเจกต์ซ้อนที่มีเพียงอ็อบเจกต์อยู่เหนือขึ้นไป เช่น "profile.address.city": "Paris"

อ็อบเจกต์ซ้อนหรือรายการซ้อนที่มีเพียงอ็อบเจกต์อยู่เหนือขึ้นไปสามารถเขียนแยกด้วยชื่อเต็มได้ เช่น profile.address หรือ profile.visits ค่าจะแทนที่เฉพาะส่วนนั้น และส่วนที่เหลือของ profile จะยังคงเหมือนเดิม ข้อจำกัด 100 องค์ประกอบและ 64 KB จะนับจากค่านี้:

"tags": {
"profile.address": { "city": "Paris" },
"profile.visits": [{ "code": "v2" }]
}

ไม่มีสิ่งใดภายในรายการอ็อบเจกต์ที่เขียนแยกได้ เนื่องจากไม่ชัดเจนว่าจะเปลี่ยนองค์ประกอบใด ซึ่งรวมถึงฟิลด์ของแท็ก ObjectList เช่น orders.sku และทุกอย่างภายในองค์ประกอบ เช่น orders.meta หรือ profile.visits.code /setTags จะข้ามค่าดังกล่าว ให้ส่งทั้งรายการแทน

แท็กอ็อบเจกต์ไม่ถูกสร้างโดยอัตโนมัติ

Anchor link to

ค่าที่เป็นอ็อบเจกต์หรืออาร์เรย์ของอ็อบเจกต์สำหรับแท็กที่ไม่มีอยู่จะถูกข้าม การสร้างแท็กอัตโนมัติจะไม่สร้างแท็กอ็อบเจกต์ ดังนั้นให้สร้างสคีมาก่อนด้วย POST /api/tags

ผลลัพธ์ของ bulkSetTags

Anchor link to

เมื่อใช้ detailed=true สถานะ /bulkSetTags จะส่งคืนผลลัพธ์อย่างใดอย่างหนึ่งต่อไปนี้สำหรับแท็กอ็อบเจกต์ นอกเหนือจาก ok, tag not found และ wrong value. expect :<type>:

ผลลัพธ์สาเหตุ
object tags are stored on the user onlyแท็กอ็อบเจกต์ไม่ใช่แท็ก User-specific
cannot load the fields of the objectPushwoosh อ่านฟิลด์ของแท็กอ็อบเจกต์ไม่ได้
wrong value. expect an object (a map) or, for a list of objects, an array of mapsค่าไม่ตรงกับแท็กอ็อบเจกต์ ค่าของฟิลด์ในระดับใดก็ตามไม่ตรงกับประเภทของฟิลด์ หรือค่าละเมิด ข้อจำกัด
a field of a list of objects cannot be set on its own, set the whole listมีการตั้งค่าให้กับสิ่งที่อยู่ภายในรายการอ็อบเจกต์ เช่น orders.sku หรือ orders.meta

อ่านค่า

Anchor link to

/getTags ส่งคืนค่า Object เป็นอ็อบเจกต์ JSON และค่า ObjectList เป็นอาร์เรย์ของอ็อบเจกต์:

การตอบกลับ
{
"status_code": 200,
"status_message": "OK",
"response": {
"result": {
"order": { "amount": 120, "status": "paid" },
"orders": [
{ "amount": 120, "status": "paid" },
{ "amount": 50 }
]
}
}
}

อ็อบเจกต์ซ้อนและรายการซ้อนจะส่งคืนในทุกระดับความลึกในรูปแบบเดียวกับที่คุณ เขียน เช่น "profile": {"address": {"city": "Berlin"}, "visits": [{"code": "v1"}]}

ค่าของฟิลด์จะถูกส่งคืนในลักษณะเดียวกับค่าแท็กทั่วไปใน /getTags: Date เป็น Unix timestamp เป็นวินาที, Price เป็นสตริง เช่น "120.00" และ Boolean เป็น 1 หรือ 0

ค่าที่จัดเก็บไว้ของฟิลด์

Anchor link to

GET /api/tags:values บน Base URL จะแสดงรายการค่าที่ไม่ซ้ำกันที่ฟิลด์เก็บไว้ พร้อมจำนวนผู้ติดตามของแต่ละค่า ส่งชื่อเต็มของฟิลด์ใน name เช่น profile.address.city หรือ orders.sku

พารามิเตอร์ของ Query
Anchor link to
ชื่อประเภทคำอธิบาย
application*stringรหัสแอปพลิเคชัน XXXXX-XXXXX
name*stringชื่อเต็มของฟิลด์
likestringส่งคืนเฉพาะค่าที่มีข้อความนี้ในตำแหน่งที่กำหนดโดย like_op
like_opstringSTARTS_WITH (ค่าเริ่มต้น), ENDS_WITH หรือ CONTAINS
order_bystringVALUE (ค่าเริ่มต้น) หรือ COUNT
order_directionstringASC (ค่าเริ่มต้น) หรือ DESC
limitintegerจำนวนค่าที่จะส่งคืน ค่าเริ่มต้นคือ 100
offsetintegerจำนวนค่าที่จะข้าม
pageintegerหมายเลขหน้า เริ่มจาก 0 ใช้ร่วมกับ per_page แทน limit และ offset
per_pageintegerจำนวนค่าในหนึ่งหน้า
ตัวอย่าง
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC
การตอบกลับ
{
"values": [
{ "value": "A-1", "count": 120 },
{ "value": "B-2", "count": 45 }
],
"total": 2,
"page": 0,
"per_page": 100
}

ฟิลด์ประเภท Integer และ Price จะไม่ส่งคืนค่า เช่นเดียวกับแท็กทั่วไปของประเภทเหล่านี้ ตัวแท็กอ็อบเจกต์ อ็อบเจกต์ซ้อน หรือรายการซ้อนเองไม่มีค่าของตัวเอง ดังนั้นชื่อของสิ่งเหล่านี้จะส่งคืน HTTP 404 tag not found

สร้างเซกเมนต์ตามฟิลด์

Anchor link to

ตั้งเงื่อนไขของเซกเมนต์บนฟิลด์ ไม่ใช่บนตัวแท็กอ็อบเจกต์เอง ใน ภาษาสำหรับการแบ่งส่วน ฟิลด์คือแท็กที่มีชื่อแบบมีจุด และใช้โอเปอเรเตอร์ตามประเภทของตัวเอง:

AT("XXXXX-XXXXX", "order.amount", gte, 100)

ฟิลด์ของอ็อบเจกต์ซ้อนหรือรายการซ้อนใช้ชื่อเต็ม เช่น profile.address.city, profile.visits.code หรือ orders.meta.color เงื่อนไขบนตัวแท็กอ็อบเจกต์เอง อ็อบเจกต์ซ้อน หรือรายการซ้อน เช่น profile.address จะล้มเหลวพร้อม object tag has no value of its own, use one of its fields

ฟิลด์ที่มีรายการอ็อบเจกต์สองรายการอยู่เหนือขึ้นไป เช่น orders.lines.qty เป็นแบบ จัดเก็บเท่านั้น เซกเมนต์ที่มีเงื่อนไขดังกล่าวจะบันทึกได้ แต่การนับจำนวนหรือการส่งไปยังเซกเมนต์นั้นจะล้มเหลวพร้อม a field inside a list nested in a list is stored only and cannot be searched

เงื่อนไขบน ObjectList

Anchor link to

เงื่อนไขบนฟิลด์ของแท็ก ObjectList จะตรงกับผู้ใช้เมื่อมีองค์ประกอบอย่างน้อยหนึ่งรายการในรายการที่ตรงตามเงื่อนไข เงื่อนไขบนฟิลด์ของรายการเดียวกันที่เชื่อมด้วย AND ต้องตรงกับองค์ประกอบเดียวกัน:

AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")

เซกเมนต์นี้ประกอบด้วยผู้ใช้ที่มีคำสั่งซื้ออย่างน้อยหนึ่งรายการที่มียอด 100 ขึ้นไปและชำระเงินแล้ว ผู้ใช้ที่มีคำสั่งซื้อยอดสูงที่ยังไม่ชำระหนึ่งรายการและคำสั่งซื้อยอดต่ำที่ชำระแล้วหนึ่งรายการจะไม่ตรงกับเงื่อนไข องค์ประกอบเดียวกันจะถูกตรวจสอบสำหรับฟิลด์ของอ็อบเจกต์ภายในองค์ประกอบด้วย: orders.sku เท่ากับ A-1 AND orders.meta.color เท่ากับ red จะตรงกับผู้ใช้ที่มีคำสั่งซื้อหนึ่งรายการที่มีทั้งสองค่า เงื่อนไขที่เชื่อมด้วย OR ไม่จำเป็นต้องตรงกับองค์ประกอบเดียวกัน เงื่อนไขบนสองรายการที่ต่างกันจะถูกตรวจสอบแยกกันในแต่ละรายการ

โอเปอเรเตอร์บางตัวทำงานต่างออกไปบนฟิลด์ของแท็ก ObjectList:

  • notset ไม่มีองค์ประกอบใดในรายการที่มีค่าในฟิลด์นี้ ผู้ใช้ที่ไม่มีรายการนี้ก็ตรงกับเงื่อนไขด้วย
  • noteq มีองค์ประกอบอย่างน้อยหนึ่งรายการที่มีค่าในฟิลด์นี้ และค่านั้นต่างจากค่าที่กำหนด องค์ประกอบที่ไม่มีฟิลด์นี้จะไม่นับรวม ผู้ใช้ที่มีคำสั่งซื้อในสถานะ paid และ new จะตรงกับ noteq "paid"
  • notin บนฟิลด์ List ไม่มีองค์ประกอบใดที่มีค่าใดๆ ในค่าที่กำหนด
  • notin บนฟิลด์ประเภทอื่น มีองค์ประกอบอย่างน้อยหนึ่งรายการที่มีค่าในฟิลด์นี้ซึ่งไม่อยู่ในค่าที่กำหนด

notset และ notin บนฟิลด์ List จะไม่ผูกกับองค์ประกอบเดียวกันกับเงื่อนไขอื่นที่เชื่อมด้วย AND กฎเหล่านี้ใช้กับรายการซ้อน เช่น profile.visits ด้วย

ใช้ค่าในข้อความ

Anchor link to

แทรกฟิลด์ของแท็กอ็อบเจกต์ลงใน push notification, อีเมล, SMS และข้อความในแอปส่งข้อความ เช่น WhatsApp ด้วย Liquid Templates Liquid ทำงานได้เฉพาะเมื่อบัญชีของคุณเปิดใช้งานเทมเพลตเนื้อหา เขียนฟิลด์ด้วยชื่อเต็มได้ในทุกระดับความลึก:

Your city is {{ profile.address.city }}.

ดึงองค์ประกอบของรายการอ็อบเจกต์ตามดัชนี โดยเริ่มจาก 0:

Your first order is {{ orders[0].sku }}, quantity {{ orders[0].lines[0].qty }}.

ดัชนีที่เกินท้ายรายการ หรือรายการที่ผู้ใช้ไม่มี จะแสดงผลเป็นสตริงว่าง ตรวจสอบองค์ประกอบก่อน หรือตั้งค่าสำรองด้วย default:

{% if orders[0] %}Your first order is {{ orders[0].sku }}.{% endif %}
Your first order is {{ orders[0].sku | default: "on its way" }}.

วนซ้ำรายการอ็อบเจกต์ รวมถึงรายการภายในองค์ประกอบ:

{% for o in orders %}{{ o.meta.color }}{% for l in o.lines %}{{ l.qty }}{% endfor %}{% endfor %}

ฟิลด์ที่จัดเก็บเท่านั้น เช่น orders.lines.qty ทำงานในเทมเพลตได้เหมือนฟิลด์อื่นๆ

ส่งออกเซกเมนต์ที่มีแท็กอ็อบเจกต์

Anchor link to

/exportSegment จะส่งออกฟิลด์ของแท็กอ็อบเจกต์:

  • CSV แต่ละฟิลด์ที่มีค่าเป็นคอลัมน์แยกที่ตั้งชื่อตามชื่อเต็ม เช่น order.amount หรือ profile.address.city ตัวแท็กอ็อบเจกต์ อ็อบเจกต์ซ้อน และรายการซ้อนเองไม่มีคอลัมน์ ฟิลด์ภายในรายการอ็อบเจกต์ในทุกระดับความลึกจะเก็บค่าที่ไม่ซ้ำกันจากทุกองค์ประกอบเป็นอาร์เรย์ JSON แบบเดียวกับแท็ก List: ["A-1","B-2"] อาร์เรย์จะถูกเรียงลำดับและไม่แสดงว่าค่ามาจากองค์ประกอบใด จึงไม่คงลำดับขององค์ประกอบไว้ด้วย หากต้องการองค์ประกอบทั้งก้อน ให้ส่งออกในรูปแบบ json หรือ json_each_line
  • json และ json_each_line แท็กอ็อบเจกต์จะมาแบบซ้อนในรูปแบบเดียวกับที่ /getTags ส่งคืน แท็ก Object เป็นรายการเดียวใน tags โดยมีฟิลด์อยู่ใต้ object.fields และอ็อบเจกต์ซ้อนภายในก็เก็บฟิลด์ของตัวเองไว้ใต้ object.fields เช่นกันในทุกระดับ แท็ก ObjectList เป็นรายการเดียวโดยมีองค์ประกอบอยู่ใน object_list.items และรายการซ้อนก็เช่นเดียวกัน ฟิลด์ใช้ชื่อสั้น เรียงตามชื่อ และเก็บค่าไว้ใต้คีย์ที่ตั้งชื่อตามประเภท: integer, string, list, date, boolean, price หรือ version:
{
"name": "profile",
"object": {
"fields": [
{ "name": "address", "object": { "fields": [{ "name": "city", "string": "Berlin" }] } },
{ "name": "visits", "object_list": { "items": [{ "fields": [{ "name": "code", "string": "v1" }] }] } }
]
}
}

แท็ก ObjectList มีลักษณะดังนี้ ค่าจำนวนเต็มจะมาเป็นสตริง:

{
"name": "orders",
"object_list": {
"items": [
{ "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] },
{ "fields": [{ "name": "amount", "integer": "50" }] }
]
}
}

องค์ประกอบที่มีอ็อบเจกต์ซ้อนและรายการซ้อนมีลักษณะดังนี้:

{
"fields": [
{ "name": "meta", "object": { "fields": [{ "name": "color", "string": "red" }] } },
{ "name": "lines", "object_list": { "items": [{ "fields": [{ "name": "qty", "integer": "2" }] }] } }
]
}

หาก tagsList ระบุแท็กอ็อบเจกต์ ฟิลด์ทั้งหมดของแท็กนั้นจะถูกส่งออก รวมถึงฟิลด์ที่ซ้อนอยู่