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 toPushwoosh ใช้ข้อจำกัดเหล่านี้กับแท็กอ็อบเจกต์ รวมถึงอ็อบเจกต์ซ้อนและรายการซ้อน:
| ข้อจำกัด | ค่า | เมื่อเกินข้อจำกัด |
|---|---|---|
| ความลึกของการซ้อน | อ็อบเจกต์และรายการ 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 toPushwoosh ตรวจสอบกฎเหล่านี้เมื่อคุณสร้างแท็กอ็อบเจกต์หรือเพิ่มฟิลด์:
- ชื่ออ็อบเจกต์และชื่อฟิลด์มีได้เฉพาะตัวอักษรละติน ตัวเลข และ
_ - ตัวแท็กและอ็อบเจกต์ซ้อนหรือรายการซ้อนแต่ละรายการมีฟิลด์ 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:
- ในหน้า แท็ก ของ Control Panel ให้คลิก สร้างแท็ก
- ป้อน ชื่อแท็ก
- ใน ประเภทค่า ให้เลือก ออบเจ็กต์ หรือ รายการออบเจ็กต์
- ใต้ ฟิลด์ ให้ป้อนชื่อของฟิลด์แรก
- เลือกประเภทของฟิลด์
- หากต้องการเพิ่มฟิลด์อื่น ให้คลิก เพิ่มฟิลด์
- คลิก สร้าง
ในหน้าของแท็ก คุณเพิ่มฟิลด์ได้ หรือคลิก ลบ ข้างฟิลด์เพื่อลบฟิลด์นั้น Control Panel สร้างอ็อบเจกต์ซ้อนหรือรายการซ้อน หรือเปลี่ยนฟิลด์ของสิ่งเหล่านี้ไม่ได้ อ็อบเจกต์ซ้อนหรือรายการซ้อนที่สร้างผ่าน API จะแสดงเป็นฟิลด์เดียวประเภท ออบเจ็กต์ หรือ รายการออบเจ็กต์ การลบฟิลด์นั้นจะลบทุกอย่างที่อยู่ภายในด้วย
จัดการสคีมา
Anchor link toสร้างและเปลี่ยนแท็กอ็อบเจกต์ด้วยเมธอด REST ด้านล่าง ใช้ /json/1.3/addTag เฉพาะกับแท็กทั่วไป เนื่องจากเมธอดนี้กำหนดฟิลด์ไม่ได้
Base URL
Anchor link tohttps://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_TOKENEndpoints
Anchor link toเมธอดเหล่านี้ใช้จัดการสคีมาของแท็กอ็อบเจกต์และอ่านค่าของฟิลด์:
| เมธอด | พาธ | คำอธิบาย |
|---|---|---|
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 toPOST /api/tags
เนื้อหาของคำขอ
Anchor link to| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| name* | string | ชื่อของแท็กอ็อบเจกต์ |
| type* | string | OBJECT สำหรับอ็อบเจกต์เดียว หรือ 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[].fields | array | ฟิลด์ของอ็อบเจกต์ซ้อนหรือรายการซ้อน 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 ของตัวเองให้กับฟิลด์ คำขอเดียวจะสร้างโครงสร้างทั้งหมด:
{ "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 toPOST /api/tags/{name}/fields
{ "field": { "name": "note", "type": "STRING" }}หากต้องการเพิ่มฟิลด์ให้กับอ็อบเจกต์ซ้อนหรือรายการซ้อน ให้ใส่ชื่อเต็มใน {name} เช่น POST /api/tags/profile.address/fields หรือ POST /api/tags/profile.visits/fields ฟิลด์ใหม่อาจเป็นอ็อบเจกต์ซ้อนหรือรายการซ้อนที่มี fields ของตัวเองได้:
{ "field": { "name": "company", "type": "OBJECT", "fields": [{ "name": "title", "type": "STRING" }] }}คุณเขียนฟิลด์ใหม่ได้ทันทีโดยเป็นส่วนหนึ่งของค่าแท็กทั้งหมด การเพิ่มฟิลด์จะล้มเหลวหากอ็อบเจกต์มี 20 ฟิลด์อยู่แล้ว หากฟิลด์ละเมิด ข้อจำกัด อื่น หรือมีแท็กที่ใช้ชื่อฟิลด์แบบเต็มนั้นอยู่แล้ว ดู ข้อผิดพลาด
ลบฟิลด์
Anchor link toDELETE /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 | ข้อความ | สาเหตุ |
|---|---|---|
| 400 | object tag and field names must contain only letters, digits and underscores | ชื่อมีอักขระอื่น |
| 400 | <object>: an object needs 1 to 20 fields | ตอนสร้าง ตัวแท็ก อ็อบเจกต์ซ้อน หรือรายการซ้อนไม่มีฟิลด์หรือมีฟิลด์มากกว่า 20 ฟิลด์ |
| 400 | an object has at most 20 fields | อ็อบเจกต์ที่คุณเพิ่มฟิลด์มี 20 ฟิลด์อยู่แล้ว |
| 400 | <object>.<field>: objects nest at most 3 levels deep | ฟิลด์ OBJECT หรือ OBJECT_LIST จะอยู่ในระดับที่สี่ |
| 400 | an object tag holds at most 50 fields with values, nested ones included | แท็กอ็อบเจกต์จะมีฟิลด์ที่มีค่ามากกว่า 50 ฟิลด์ |
| 400 | field <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 | ประเภทฟิลด์ที่ไม่รองรับ |
| 400 | an object needs at least one field; delete the object instead | คุณพยายามลบฟิลด์สุดท้ายของอ็อบเจกต์ |
| 400 | field is in use: ..., tag is in use: ... | ฟิลด์ สิ่งใดภายในอ็อบเจกต์ซ้อนหรือรายการซ้อน หรือแท็กอ็อบเจกต์ถูกใช้ในเซกเมนต์, in-app, แคมเปญ Customer Journey หรือรายการอื่นๆ |
| 403 | object tags are not enabled for the account | บัญชีไม่ได้เปิดใช้งานแท็กอ็อบเจกต์ |
| 403 | a device API token cannot call this method, use an account API token | คำขอใช้ Device API token |
| 404 | tag not found | GET หรือ DELETE /api/tags/{name}: ไม่มีแท็กนี้ ชื่อนั้นเป็นฟิลด์ หรือไม่ได้เปิดใช้งานแท็กอ็อบเจกต์ |
| 404 | object tag not found, field not found | เมธอดของฟิลด์: ไม่มีแท็กอ็อบเจกต์ อ็อบเจกต์ซ้อน รายการซ้อน หรือฟิลด์นี้ {name} ที่เป็นฟิลด์ที่มีค่าก็ส่งคืน object tag not found เช่นกัน |
| 409 | tag already exists | มีแท็กที่ใช้ชื่อเดียวกับแท็กอ็อบเจกต์อยู่แล้ว |
| 409 | tag <object>.<field> already exists | มีแท็กที่ใช้ชื่อเต็มของฟิลด์อยู่แล้ว |
เขียนค่า
Anchor link toเขียนค่าแท็กอ็อบเจกต์ด้วย /setTags และ /bulkSetTags เมธอดเหล่านี้ใช้การรับรองความถูกต้องแบบเดิมของตัวเอง: /setTags รับ Device API token ใน header Authorization: Token และ /bulkSetTags รับ API access token ใน auth ส่งค่า Object เป็นอ็อบเจกต์ JSON และส่งค่า ObjectList เป็นอาร์เรย์ของอ็อบเจกต์:
{ "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 และรายการซ้อนรับอาร์เรย์ของอ็อบเจกต์:
"tags": { "profile": { "address": { "city": "Berlin", "geo": { "lat": "52.5" } }, "visits": [{ "code": "v1" }] }, "orders": [ { "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] } ]}แต่ละฟิลด์รับค่าในรูปแบบตามประเภทของฟิลด์:
| ประเภทฟิลด์ | ตัวอย่างค่า |
|---|---|
INTEGER | 120 |
STRING | "paid" |
LIST | ["gift", "express"] |
DATE | "2026-10-02 22:11" (UTC), "2026-10-02" หรือ Unix timestamp เป็นวินาที |
BOOLEAN | true หรือ false |
PRICE | 19.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 object | Pushwoosh อ่านฟิลด์ของแท็กอ็อบเจกต์ไม่ได้ |
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 toGET /api/tags:values บน Base URL จะแสดงรายการค่าที่ไม่ซ้ำกันที่ฟิลด์เก็บไว้ พร้อมจำนวนผู้ติดตามของแต่ละค่า ส่งชื่อเต็มของฟิลด์ใน name เช่น profile.address.city หรือ orders.sku
พารามิเตอร์ของ Query
Anchor link to| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| application* | string | รหัสแอปพลิเคชัน XXXXX-XXXXX |
| name* | string | ชื่อเต็มของฟิลด์ |
| like | string | ส่งคืนเฉพาะค่าที่มีข้อความนี้ในตำแหน่งที่กำหนดโดย like_op |
| like_op | string | STARTS_WITH (ค่าเริ่มต้น), ENDS_WITH หรือ CONTAINS |
| order_by | string | VALUE (ค่าเริ่มต้น) หรือ COUNT |
| order_direction | string | ASC (ค่าเริ่มต้น) หรือ DESC |
| limit | integer | จำนวนค่าที่จะส่งคืน ค่าเริ่มต้นคือ 100 |
| offset | integer | จำนวนค่าที่จะข้าม |
| page | integer | หมายเลขหน้า เริ่มจาก 0 ใช้ร่วมกับ per_page แทน limit และ offset |
| per_page | integer | จำนวนค่าในหนึ่งหน้า |
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 ระบุแท็กอ็อบเจกต์ ฟิลด์ทั้งหมดของแท็กนั้นจะถูกส่งออก รวมถึงฟิลด์ที่ซ้อนอยู่