API สำหรับ iOS Live Activities

เอกสารของ Apple:
เกี่ยวกับ Live Activities
การอัปเดตและสิ้นสุด Live Activities ด้วยการแจ้งเตือนพุชของ ActivityKit

startLiveActivity

ใช้วิธีการนี้เพื่อสร้าง iOS Live Activities

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

อนุญาตให้สร้าง iOS Live Activities

เนื้อหาของคำขอ (Request body)

พารามิเตอร์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
application	String	จำเป็น	รหัสแอปพลิเคชัน Pushwoosh
auth	String	จำเป็น	โทเค็นการเข้าถึง API จากแผงควบคุม Pushwoosh
notifications	Array	จำเป็น	อาร์เรย์ JSON ของพารามิเตอร์ข้อความ ดูรายละเอียดในตาราง Notifications ด้านล่าง

Notifications

พารามิเตอร์ที่ใช้ในอาร์เรย์ notifications:

พารามิเตอร์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
content	String	จำเป็น	เนื้อหาสำรองสำหรับอุปกรณ์ที่ใช้ iOS เวอร์ชันต่ำกว่า 16.1 ซึ่งไม่รองรับ Live Activity สำหรับ iOS 16.1+ (ที่รองรับ Live Activity) เนื้อหาจะมาจากฟิลด์ `live_activity`
title	String	ไม่จำเป็น	หัวข้อของข้อความแจ้งเตือน
live_activity	Object	จำเป็น	ข้อมูล Live Activity เพื่อสร้าง Live Activity ใน iOS
content-state	Object	จำเป็น	เนื้อหาสำหรับการแจ้งเตือน Live Activity
attributes-type	String	จำเป็น	ประเภทของคุณสมบัติ (attributes) ที่ใช้ใน Live Activity
attributes	Object	จำเป็น	คุณสมบัติ (Attributes) สำหรับ Live Activity
live_activity_id	String	จำเป็น	ID ที่ไม่ซ้ำกันสำหรับ Live Activity ซึ่งสร้างโดยผู้ใช้
filter_code	String	ไม่จำเป็น	รหัสตัวกรอง (เซกเมนต์) เพื่อกำหนดเป้าหมายไปยังกลุ่มเป้าหมายที่เฉพาะเจาะจง
devices	Array of strings	ไม่จำเป็น	โทเค็น หรือ HWIDs เพื่อส่งการแจ้งเตือนพุชแบบกำหนดเป้าหมาย โดยมีจำนวนสูงสุด 1000 รายการ หากตั้งค่าไว้ ข้อความจะถูกส่งไปยังอุปกรณ์ในรายการเท่านั้น หมายเหตุ: ไม่อนุญาตให้ใช้กลุ่มแอปพลิเคชัน (Application Group) สำหรับรายการอุปกรณ์ และโทเค็นพุชของ iOS ต้องเป็นตัวพิมพ์เล็ก
users	Array of strings	ไม่จำเป็น	หากตั้งค่าไว้ ข้อความจะถูกส่งไปยัง User ID ที่ระบุเท่านั้น (กำหนดผ่านการเรียก `/registerUser`) คุณสามารถใส่ User ID ได้สูงสุด 1000 รายการในอาร์เรย์ หมายเหตุ: หากใช้ร่วมกับพารามิเตอร์ `devices` พารามิเตอร์ `users` จะมีความสำคัญเหนือกว่า ไม่อนุญาตให้ใช้กลุ่มแอปพลิเคชัน (Application Group) สำหรับรายการผู้ใช้

การตอบกลับ (Response)

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "C3F8-C3863ED4-334AD4F1"
    ]
  }
}

ตัวอย่างคำขอ (Request example)

{
  "request": {
    "application": "XXXXX-XXXXX",        // จำเป็น รหัสแอปพลิเคชัน Pushwoosh
    "auth": "yxoPUlwqm…………pIyEX4H",      // จำเป็น โทเค็นการเข้าถึง API จากแผงควบคุม Pushwoosh
    "notifications": [{
      "live_activity": {                 // จำเป็น ข้อมูล Live Activity เพื่อสร้าง Live Activity ใน iOS
        "content-state": {
          "emoji": ":wink:"
        },
        "attributes-type": "LiveActivityAttributes",
        "attributes": {
          "name": "Apple"
        }
      },
      "live_activity_id": "unique UUID", // ไม่จำเป็น ตัวระบุที่ไม่ซ้ำกันของ Live Activity
      "filter_code": "FILTER_NAME",      // ไม่จำเป็น ระบุตัวกรอง
      "devices": [                       // ไม่จำเป็น ระบุโทเค็นหรือ hwid เพื่อส่งพุชที่กำหนดเป้าหมาย
          "hwid_XXXX"                    //           การแจ้งเตือน ไม่เกิน 1000 โทเค็น/hwids ใน
      ],                                 //           อาร์เรย์ หากตั้งค่า ข้อความจะถูกส่งไปยัง
                                         //           อุปกรณ์ในรายการเท่านั้น ไม่อนุญาตให้ใช้กลุ่มแอปพลิเคชัน (Application Group) สำหรับ
                                         //           รายการอุปกรณ์
                                         //           โทเค็นพุช iOS ต้องเป็นตัวพิมพ์เล็กเท่านั้น
      "users": [                         // ไม่จำเป็น หากตั้งค่า ข้อความจะถูกส่งไปยังที่ระบุเท่านั้น
        "user_XXXX"                      //           ID ผู้ใช้ (ตั้งค่าผ่านการเรียก /registerUser) หากระบุ
      ]                                  //           พร้อมกับพารามิเตอร์ devices พารามิเตอร์หลังจะถูก
                                         //           ละเว้น ไม่เกิน 1000 ID ผู้ใช้ในอาร์เรย์
                                         //           ไม่อนุญาตให้ใช้กลุ่มแอปพลิเคชันสำหรับรายการผู้ใช้
    }]
  }
}

หมายเหตุ:
อ่านบทความนี้เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับการทำงานกับ Live Activities โดยใช้ Pushwoosh iOS SDK

updateLiveActivity

ใช้วิธีการนี้เพื่อจัดการ iOS Live Activities

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

อนุญาตให้สร้างและจัดการ iOS Live Activities

เนื้อหาของคำขอ (Request body)

พารามิเตอร์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
auth	String	จำเป็น	โทเค็นการเข้าถึง API จากแผงควบคุม Pushwoosh
application	String	จำเป็น	รหัสแอปพลิเคชัน Pushwoosh
notifications	Array	จำเป็น	อาร์เรย์ JSON ของพารามิเตอร์ข้อความ ดูรายละเอียดในตาราง Notifications ด้านล่าง

Notifications

พารามิเตอร์ที่ใช้ในอาร์เรย์ notifications:

พารามิเตอร์	ประเภท	จำเป็น/ไม่จำเป็น	คำอธิบาย
live_activity	Object	จำเป็น	ข้อมูล Live Activity เพื่ออัปเดต Live Activity ใน iOS
event	String	จำเป็น	ระบุประเภทของเหตุการณ์ ใช้ `"update"` เพื่ออัปเดต Live Activity หรือ `"end"` เพื่อปิด
content-state	Object	จำเป็น	อ็อบเจกต์ที่มีคู่คีย์-ค่าที่ใช้ในการส่งข้อมูลไปยัง Live Activity เพื่ออัปเดตเนื้อหา
dismissal-date	Integer	ไม่จำเป็น	เวลา (เป็นวินาที) ที่ Live Activity ควรจะสิ้นสุด
live_activity_id	String	จำเป็น	ตัวระบุที่ไม่ซ้ำกันสำหรับ Live Activity ที่กำลังอัปเดต
stale-date	Integer	ไม่จำเป็น	เวลา (เป็นวินาที) ที่แสดงวันที่ Live Activity กลายเป็นข้อมูลเก่าหรือไม่เป็นปัจจุบัน

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "C3F8-C3863ED4-334AD4F1"
    ]
  }
}

ตัวอย่างคำขอ (Request example)

{
  "request": {
    "application": "XXXXX-XXXXX",        // จำเป็น รหัสแอปพลิเคชัน Pushwoosh
    "auth": "yxoPUlwqm…………pIyEX4H",      // จำเป็น โทเค็นการเข้าถึง API จากแผงควบคุม Pushwoosh
    "notifications": [{
      "live_activity": {                 // จำเป็น ข้อมูล Live Activity เพื่ออัปเดต Live Activity ใน iOS
        "event": "update",               // จำเป็น ใช้ "update" เพื่ออัปเดต Live Activity หรือ
                                         //           "end" เพื่อปิด Live Activity
        "content-state": {               // จำเป็น อ็อบเจกต์ที่มีคู่คีย์-ค่าที่ใช้ในการส่งข้อมูล
          "courierName": "NUMBER: 15",   //           ไปยัง Live Activity เพื่ออัปเดตเนื้อหา
          "deliveryStatus": "Done"
        },
        "dismissal-date": 12345678,      // ไม่จำเป็น เวลาสิ้นสุด Live Activity เป็นวินาที
        "stale-date": 23456789           // ไม่จำเป็น เวลา (เป็นวินาที) ที่ Live Activity จะกลายเป็นข้อมูลเก่า
      },
      "live_activity_id": "unique UUID"  // ไม่จำเป็น ตัวระบุที่ไม่ซ้ำกันของ Live Activity
    }]
  }
}

อ่านบทความนี้เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับการทำงานกับ Live Activities โดยใช้ Pushwoosh iOS SDK