API สกีมาของ Live Activity

สกีมาของ Live Activity คือ JSON Schema สำหรับประเภท ActivityAttributes หนึ่งประเภทในแอปของคุณ (ตัวอย่างเช่น FlightAttributes) ซึ่งครอบคลุมทั้งสองส่วนของการ์ด ได้แก่ ฟิลด์ ContentState ที่เปลี่ยนแปลงในขณะที่กิจกรรมทำงาน และฟิลด์ที่คงที่ตลอดอายุของกิจกรรม เผยแพร่สกีมาเพื่อให้ องค์ประกอบ Live Activity ของ Journey สามารถสร้างฟิลด์ที่มีชื่อสำหรับทั้งสองส่วนจากสกีมานี้ได้ แทนที่จะเป็นตัวแก้ไข JSON แบบดิบและรายการฟิลด์แบบอิสระ การ์ดและเลย์เอาต์ของมันยังคงถูกสร้างขึ้นในโค้ดของแอปคุณ สกีมาจะอธิบายเฉพาะข้อมูลที่ Journey จะกรอกเข้าไปเท่านั้น

API นี้สำหรับนักพัฒนาที่กำลังผสานการทำงานของ Live Activities ดู API ของ iOS Live Activities สำหรับการเริ่มต้นและอัปเดตกิจกรรมด้วยตนเอง

การเขียนสกีมา

attributesType คือชื่อของประเภท Swift ที่สอดคล้องกับ ActivityAttributes ในแอปของคุณ Pushwoosh ไม่ได้อ่านโค้ดของคุณหรือตรวจสอบชื่อกับโค้ด — มันเป็นเพียงสตริงที่ API จัดเก็บและสตริงที่คุณส่งไปยังฟิลด์ attributes-type ของ startLiveActivity

jsonSchema ครอบคลุมทั้งสองส่วนของประเภทนั้นในสองที่แยกกัน:

• ฟิลด์ ContentState ซึ่งเปลี่ยนแปลงในขณะที่กิจกรรมทำงาน เช่น ประตูขึ้นเครื่อง สถานะ หรือเวลาที่คาดว่าจะถึงของเที่ยวบิน จะอยู่ใน properties ที่ระดับรากของสกีมา
• ฟิลด์ ActivityAttributes ซึ่งคงที่ตลอดอายุของกิจกรรมและตั้งค่าเพียงครั้งเดียวเมื่อเริ่มต้น เช่น หมายเลขเที่ยวบิน จะอยู่ในส่วน attributes แยกต่างหาก ซึ่งมี properties ของตัวเองและรายการ required ที่เป็นทางเลือก

ส่วน attributes เป็นทางเลือก หากไม่มีส่วนนี้ ฟิลด์ ActivityAttributes จะยังคงเป็นรายการชื่อ/ค่าฟิลด์แบบอิสระในอิลิเมนต์ Live Activity แทนที่จะเป็นฟิลด์ที่มีชื่อกำกับ คุณยังคงส่งค่าแอตทริบิวต์จริงผ่าน live_activity.attributes ใน startLiveActivity — สกีมาเพียงระบุชื่อ ประเภท และฟิลด์ใดที่จำเป็นเท่านั้น

ตัวอย่าง

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

flightNumber อยู่ใน ActivityAttributes gate, status, และ estimatedTime อยู่ใน ContentState เผยแพร่ทั้งสองส่วนเป็นสกีมาสำหรับ attributesType: "FlightAttributes":

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

required ภายใน attributes ทำให้ flightNumber เป็นฟิลด์บังคับในขั้นตอน Start ขององค์ประกอบ Live Activity การเว้นว่างไว้ที่นั่นจะถูกปฏิเสธ ส่วน properties ที่ระดับรากสำหรับฟิลด์ ContentState ไม่มีรายการแบบนี้ Journey ไม่จำเป็นต้องกรอก gate, status, หรือ estimatedTime เลย

เมื่อเผยแพร่แล้ว องค์ประกอบ Live Activity ของ Journey จะอ่านรูปทรงนี้เพื่อเสนอฟิลด์ที่มีชื่อสำหรับ gate, status, และ estimatedTime ใน Card content แทนที่จะเป็นตัวแก้ไข content-state แบบดิบ และในทำนองเดียวกัน flightNumber จะปรากฏใน Card attributes แทนที่จะเป็นรายการชื่อ/ค่าฟิลด์แบบอิสระ

ดู ข้อตกลง ด้านล่างสำหรับกฎของรูปแบบและความไม่เปลี่ยนรูปที่ใช้กับ jsonSchema และ การจัดการสกีมาใน Control Panel ที่ท้ายหน้านี้สำหรับการดำเนินการเดียวกันโดยไม่ต้องเรียก API โดยตรง

URL พื้นฐาน

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

การยืนยันตัวตน

ทุกคำขอต้องมีเฮดเดอร์ Authorization พร้อมกับ โทเค็น Server API ของคุณ:

Authorization: Api YOUR_API_TOKEN

ข้อตกลง

• การตั้งชื่อฟิลด์ไม่สมมาตร คำขอยอมรับทั้ง lowerCamelCase และชื่อ proto การตอบกลับจะกลับมาพร้อมกับชื่อฟิลด์ proto เสมอ ในรูปแบบ snake_case (attributes_type, json_schema) — ตัวอย่างด้านล่างใช้รูปแบบตัวพิมพ์นี้
• เวอร์ชันไม่สามารถเปลี่ยนแปลงได้ เวอร์ชันที่เผยแพร่แล้วไม่สามารถแก้ไขได้ — ไม่มีเมธอด Update การเผยแพร่อีกครั้งด้วย attributesType และ version เดียวกันจะล้มเหลวพร้อมกับ AlreadyExists การเปลี่ยนแปลงวิดเจ็ตจะเป็นเวอร์ชันใหม่เสมอ ละเว้น version ใน Create เพื่อเผยแพร่เวอร์ชันถัดไปที่ว่างสำหรับ attributesType นั้น
• รูปแบบ jsonSchema: ต้องเป็นอ็อบเจกต์ JSON ที่มี "type": "object" ขนาดไม่เกิน 64 KB null, ตัวเลข, สตริงเปล่า, หรืออ็อบเจกต์ที่ไม่มี "type": "object" จะถูกปฏิเสธทั้งหมด เนื่องจากฟอร์มที่ Pushwoosh สร้างต้องการฟิลด์ที่มีชื่อ ซึ่งมีเฉพาะในสกีมาแบบอ็อบเจกต์เท่านั้น ส่วน attributes ซึ่งเป็นทางเลือก หากมีอยู่ จะต้องเป็นอ็อบเจกต์ที่มี properties ของตัวเอง และอาจมีอาร์เรย์ required ที่ระบุเฉพาะชื่อฟิลด์ที่ประกาศไว้ใน attributes.properties เท่านั้น ชื่อฟิลด์หนึ่งชื่อไม่สามารถปรากฏทั้งใน properties และ attributes.properties พร้อมกันได้

Endpoints

เมธอด	เส้นทาง	คำอธิบาย
GET	/api/live_activity_schemas	แสดงรายการสกีมาของแอปพลิเคชัน
GET	/api/live_activity_schemas/{attributesType}/{version}	รับสกีมาหนึ่งเวอร์ชัน
POST	/api/live_activity_schemas	เผยแพร่สกีมาเวอร์ชันใหม่
DELETE	/api/live_activity_schemas/{attributesType}/{version}	ลบสกีมาหนึ่งเวอร์ชัน

List

แสดงรายการ attributesType ทั้งหมดที่แอปพลิเคชันได้เผยแพร่สกีมาไว้ พร้อมกับทุกเวอร์ชัน โดยเรียงจากเวอร์ชันใหม่สุดก่อน

GET /api/live_activity_schemas

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
application	string	ใช่	รหัสแอปพลิเคชัน ที่จะแสดงรายการสกีมา
attributesType	string	ไม่	จำกัดรายการให้เหลือเพียงประเภท ActivityAttributes เดียว

ตัวอย่างการตอบกลับ

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

Get

ส่งคืนสกีมาหนึ่งเวอร์ชัน

GET /api/live_activity_schemas/{attributesType}/{version}

พารามิเตอร์ของ Path

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
attributesType	string	ใช่	ชื่อของประเภท ActivityAttributes
version	integer	ใช่	เวอร์ชันของสกีมา

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
application	string	ใช่	รหัสแอปพลิเคชันที่สกีมาเป็นของ

การตอบกลับ

ส่งคืน { "schema": { ... } } ซึ่งเป็นอ็อบเจกต์สกีมาที่แสดงใน List ด้านบน

Create

เผยแพร่สกีมาเวอร์ชันใหม่สำหรับ attributesType ส่งคืนสกีมาที่สร้างขึ้น รวมถึงเวอร์ชันที่ถูกกำหนด

POST /api/live_activity_schemas

เนื้อหาของคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
application	string	ใช่	รหัสแอปพลิเคชันที่จะเผยแพร่สกีมา
attributesType	string	ใช่	ชื่อของประเภท ActivityAttributes ที่ประกาศในแอปของคุณ
jsonSchema	string	ใช่	JSON Schema ของทั้ง ContentState และ attributes ดู การเขียนสกีมา ด้านบน
version	integer	ไม่	เวอร์ชันที่จะเผยแพร่ ละเว้นเพื่อรับเวอร์ชันถัดไปที่ว่างสำหรับ attributesType นี้

ตัวอย่างคำขอ

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

การตอบกลับ

ส่งคืน { "schema": { ... } } ซึ่งเป็นอ็อบเจกต์สกีมาที่สร้างขึ้น

ข้อควรระวัง

การเผยแพร่คู่ attributesType/version ที่มีอยู่แล้วจะล้มเหลวพร้อมกับ AlreadyExists — เวอร์ชันไม่สามารถเปลี่ยนแปลงได้ ดังนั้นจึงไม่มีทางที่จะเขียนทับได้ ให้เผยแพร่โดยไม่มี version เพื่อรับเวอร์ชันถัดไปแทน

Delete

ลบสกีมาหนึ่งเวอร์ชันอย่างถาวร

DELETE /api/live_activity_schemas/{attributesType}/{version}

พารามิเตอร์ของ Path

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
attributesType	string	ใช่	ชื่อของประเภท ActivityAttributes
version	integer	ใช่	เวอร์ชันของสกีมาที่จะลบ

พารามิเตอร์ของ Query

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
application	string	ใช่	รหัสแอปพลิเคชันที่สกีมาเป็นของ

การตอบกลับ

ส่งคืนอ็อบเจกต์ว่างเมื่อสำเร็จ

อันตราย

การกระทำนี้ไม่สามารถยกเลิกได้ องค์ประกอบ Live Activity ของ Journey ที่สร้างขึ้นจากเวอร์ชันที่ถูกลบจะยังคงเก็บค่าเนื้อหาและแอตทริบิวต์ที่บันทึกไว้แล้ว เพียงแต่จะสูญเสียคำแนะนำในฟอร์มของทั้งสองส่วนตั้งแต่นั้นเป็นต้นไป โดยเนื้อหาจะกลับไปเป็นตัวแก้ไข JSON แบบดิบ และแอตทริบิวต์จะกลับไปเป็นรายการชื่อ/ค่าฟิลด์แบบอิสระ

การตอบกลับข้อผิดพลาด

สถานะ HTTP	ความหมาย
400 Bad Request	อาร์กิวเมนต์ไม่ถูกต้อง: ฟิลด์ที่จำเป็นหายไป, jsonSchema ไม่เป็นไปตามกฎของรูปแบบด้านบน (รวมถึงส่วน attributes ที่ไม่ถูกต้อง) หรือ jsonSchema เกิน 64 KB
401 Unauthorized	เฮดเดอร์ Authorization หายไปหรือไม่ถูกต้อง
403 Forbidden	แอปพลิเคชันไม่ได้เป็นของบัญชีของผู้เรียก
404 Not Found	ไม่พบแอปพลิเคชัน หรือคู่ attributesType/version
409 Conflict	Create ถูกเรียกด้วยคู่ attributesType/version ที่มีอยู่แล้ว (AlreadyExists บน wire)
500 Internal Server Error	ความล้มเหลวที่ไม่คาดคิดฝั่งเซิร์ฟเวอร์

การจัดการสกีมาใน Control Panel

Control Panel มีการดำเนินการเช่นเดียวกับ API โดยไม่ต้องเรียกใช้โดยตรง: แสดงรายการเวอร์ชันตามประเภท, เผยแพร่เวอร์ชันใหม่, ดู JSON ของเวอร์ชัน, และลบเวอร์ชัน (พร้อมการยืนยัน เนื่องจากการลบเป็นแบบถาวร) ดู การกำหนดค่าสกีมา iOS Live Activity สำหรับขั้นตอนการคลิก