iOS Live Activities API

เอกสารของ Apple:

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

startLiveActivity

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

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

Request body

Parameter	Type	Required/Optional	Description
application	String	จำเป็น	รหัสแอปพลิเคชัน Pushwoosh
auth	String	จำเป็น	โทเค็นการเข้าถึง API จาก Pushwoosh Control Panel
notifications	Array	จำเป็น	อาร์เรย์ JSON ของพารามิเตอร์ข้อความ ดูรายละเอียดในตาราง Notifications ด้านล่าง

Notifications

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

Parameter	Type	Required/Optional	Description
content	String	จำเป็น	เนื้อหาสำรองสำหรับอุปกรณ์ที่ใช้ iOS เวอร์ชันต่ำกว่า 16.1 ที่ไม่รองรับ Live Activity บน iOS 16.1+ (ที่รองรับ Live Activity) เนื้อหาจะมาจากฟิลด์ live_activity
title	String	ทางเลือก	ชื่อเรื่องของข้อความแจ้งเตือน
live_activity	Object	จำเป็น	ข้อมูล Live Activity เพื่อสร้าง Live Activity ใน iOS
live_activity.content-state	Object	จำเป็น	เนื้อหาสำหรับการแจ้งเตือน Live Activity
live_activity.attributes-type	String	จำเป็น	ประเภทของแอตทริบิวต์ที่ใช้ใน Live Activity
live_activity.attributes	Object	จำเป็น	แอตทริบิวต์สำหรับ Live Activity
live_activity_id	String	จำเป็น	ตัวระบุที่ไม่ซ้ำกันสำหรับ Live Activity ใช้เพื่อกำหนดเป้าหมายกิจกรรมนี้เมื่อเรียกใช้ updateLiveActivity ต้องไม่ซ้ำกันในแต่ละเซสชันของกิจกรรม
filter	String	ทางเลือก	ชื่อของฟิลเตอร์ Pushwoosh (segment) ดู ชื่อ Segment / Filter Live Activity จะเริ่มต้นบนอุปกรณ์ทั้งหมดที่ตรงกับฟิลเตอร์นี้
devices	Array of Strings	ทางเลือก	รายการของ โทเค็นอุปกรณ์ Live Activity จะเริ่มต้นเฉพาะบนอุปกรณ์ที่ระบุเท่านั้น
send_date	String	ทางเลือก	กำหนดเวลาพุชที่เริ่มต้น Live Activity สำหรับวันและเวลาที่ระบุ — ทำงานร่วมกับการกำหนดเป้าหมายด้วย filter หรือ devices ใช้รูปแบบ YYYY-MM-DD HH:mm หรือ now เพื่อเริ่มต้นทันที (นี่เป็นค่าเริ่มต้นเมื่อพารามิเตอร์ถูกละไว้) ต้องไม่เก่ากว่า 1 วันในอดีตหรือไม่เกิน 30 วันในอนาคต มิฉะนั้นคำขอจะถูกปฏิเสธด้วยข้อผิดพลาดในการตรวจสอบความถูกต้อง
timezone	String	ทางเลือก	เขตเวลาที่ใช้ในการตีความ send_date หากละไว้ send_date จะถูกตีความในรูปแบบ UTC
apns_priority	Integer	ทางเลือก	ควบคุมลำดับความสำคัญในการจัดส่งของ APNs สำหรับพุช Live Activity นี้ รับค่า 10 (ลำดับความสำคัญสูง จัดส่งพร้อมเฮดเดอร์ apns-priority: 10 เพื่อการแสดงผลทันทีบนหน้าจอที่ล็อก) หรือ 5 (ลำดับความสำคัญต่ำ จัดส่งพร้อมเฮดเดอร์ apns-priority: 5 เพื่อประหยัดแบตเตอรี่ของอุปกรณ์) ค่าอื่น ๆ จะถูกถือว่าเป็น 5 โดยไม่มีข้อผิดพลาดในการตรวจสอบความถูกต้อง พุช Live Activity ทุกรายการมีค่าเริ่มต้นเป็นลำดับความสำคัญ 5 โดยไม่คำนึงว่าจะมีเนื้อหาการแจ้งเตือน (content/title) หรือไม่ — ตั้งค่า apns_priority: 10 อย่างชัดเจนเพื่อขอการจัดส่งที่มีลำดับความสำคัญสูง ดู Time Sensitive Push และลำดับความสำคัญในการจัดส่ง ด้านล่าง

ข้อควรระวัง

การเริ่มต้น Live Activity จากระยะไกลผ่าน startLiveActivity ต้องใช้อุปกรณ์ iOS 17.2+ — เวอร์ชันก่อนหน้านี้ไม่รองรับ API pushToStartTokenUpdates ที่ endpoint นี้ต้องใช้ ดู Start Live Activity with a Remote push notification

เมื่อกำหนดเป้าหมายเป็น filter (segment) เวลาส่งที่กำหนดไว้คือเวลาที่ Pushwoosh เริ่มส่งพุช ไม่ใช่เวลารับประกันการจัดส่งทันที — สำหรับกลุ่มเป้าหมายขนาดใหญ่ การจัดส่งไปยังอุปกรณ์แต่ละเครื่องอาจล่าช้ากว่า send_date สองสามนาที เนื่องจากอัตราการส่งสำหรับพุช Live Activity ไม่สามารถปรับแต่งด้วย send_rate ได้

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

ด้วยฟิลเตอร์

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

ด้วยอุปกรณ์

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

การเริ่มต้นตามกำหนดเวลา

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

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

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

หมายเหตุ:

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

updateLiveActivity

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

อนุญาตให้อัปเดตและสิ้นสุด iOS Live Activities

Request body

Parameter	Type	Required/Optional	Description
auth	String	จำเป็น	โทเค็นการเข้าถึง API จาก Pushwoosh Control Panel
application	String	จำเป็น	รหัสแอปพลิเคชัน Pushwoosh
notifications	Array	จำเป็น	อาร์เรย์ JSON ของพารามิเตอร์ข้อความ ดูรายละเอียดในตาราง Notifications ด้านล่าง

Notifications

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

Parameter	Type	Required/Optional	Description
live_activity	Object	จำเป็น	ข้อมูล Live Activity เพื่ออัปเดต Live Activity ใน iOS
live_activity.event	String	จำเป็น	ระบุประเภทของเหตุการณ์ ใช้ "update" เพื่ออัปเดต Live Activity หรือ "end" เพื่อปิด
live_activity.content-state	Object	จำเป็น	อ็อบเจกต์ที่มีคู่คีย์-ค่าที่ใช้ในการส่งข้อมูลไปยัง Live Activity เพื่ออัปเดตเนื้อหา
live_activity.dismissal-date	Integer	ทางเลือก	เวลา (เป็นวินาที) ที่ Live Activity ควรจะสิ้นสุด
live_activity_id	String	จำเป็น	ตัวระบุที่ไม่ซ้ำกันของ Live Activity ที่จะอัปเดต ต้องตรงกับ live_activity_id ที่ใช้ใน startLiveActivity การอัปเดตจะถูกส่งไปยังอุปกรณ์ทั้งหมดที่กิจกรรมนี้ได้เริ่มต้นไว้
live_activity.relevance-score	Integer	ทางเลือก	บอกระบบ iOS ว่า Live Activity ใดมีความสำคัญสูงกว่ากิจกรรมอื่น ๆ รับค่าตั้งแต่ 1 ถึงอนันต์ (แนะนำให้ใช้ค่าไม่เกิน 100)
live_activity.stale-date	Integer	ทางเลือก	เวลา (เป็นวินาที) ที่แสดงถึงวันที่ Live Activity กลายเป็นข้อมูลเก่าหรือไม่ทันสมัย
apns_priority	Integer	ทางเลือก	ควบคุมลำดับความสำคัญในการจัดส่งของ APNs สำหรับพุช Live Activity นี้ รับค่า 10 (ลำดับความสำคัญสูง จัดส่งพร้อมเฮดเดอร์ apns-priority: 10 เพื่อการแสดงผลทันทีบนหน้าจอที่ล็อก) หรือ 5 (ลำดับความสำคัญต่ำ จัดส่งพร้อมเฮดเดอร์ apns-priority: 5 เพื่อประหยัดแบตเตอรี่ของอุปกรณ์) ค่าอื่น ๆ จะถูกถือว่าเป็น 5 โดยไม่มีข้อผิดพลาดในการตรวจสอบความถูกต้อง พุช Live Activity ทุกรายการมีค่าเริ่มต้นเป็นลำดับความสำคัญ 5 โดยไม่คำนึงว่าจะมีเนื้อหาการแจ้งเตือน (content/title) หรือไม่ — ตั้งค่า apns_priority: 10 อย่างชัดเจนเพื่อขอการจัดส่งที่มีลำดับความสำคัญสูง ดู Time Sensitive Push และลำดับความสำคัญในการจัดส่ง ด้านล่าง

หมายเหตุ: relevance-score มีผลต่อลำดับการแสดงผลของ Live Activities ที่ทำงานอยู่หลายรายการบนอุปกรณ์เดียวกันเท่านั้น — ไม่มีผลต่อความเร่งด่วนในการจัดส่ง ใช้ apns_priority เพื่อควบคุมความเร่งด่วนในการส่งอัปเดต

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

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "live_activity": {
          "event": "update",
          "title": "Live Activity Update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

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

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

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

Time Sensitive Push และลำดับความสำคัญในการจัดส่ง

โดยค่าเริ่มต้น Apple จะส่งอัปเดต Live Activity ด้วยลำดับความสำคัญต่ำ (apns-priority: 5) เพื่อประหยัดแบตเตอรี่ เมื่ออุปกรณ์ถูกล็อก การอัปเดตที่มีลำดับความสำคัญต่ำจะถูกประมวลผลในเบื้องหลังและจะปรากฏบน Lock Screen ก็ต่อเมื่อผู้ใช้ปลดล็อกอุปกรณ์แล้วเท่านั้น บนอุปกรณ์ที่ปลดล็อกอยู่แล้ว การอัปเดตจะแสดงผลทันที ใช้พารามิเตอร์ apns_priority ที่อธิบายไว้ข้างต้นเพื่อขอการจัดส่งที่มีลำดับความสำคัญสูง (apns-priority: 10) เพื่อให้การอัปเดตแสดงผลบน Lock Screen ทันทีโดยไม่ต้องปลดล็อก

ไม่เกี่ยวข้องกับสวิตช์ Time Sensitive Push

สวิตช์ Time Sensitive Push ใน Pushwoosh Control Panel ตั้งค่า interruption-level สำหรับการแจ้งเตือนพุชมาตรฐานเท่านั้น ไม่มีผลต่อลำดับความสำคัญในการจัดส่ง Live Activity ที่ส่งผ่าน API นี้ — Live Activities ใช้เส้นทางการจัดส่งแยกต่างหาก ซึ่งควบคุมโดยพารามิเตอร์คำขอ apns_priority เท่านั้น

แม้ว่าจะมี apns_priority: 10 ให้ใช้ แต่ Apple ก็จำกัดความถี่ในการใช้งาน

งบประมาณลำดับความสำคัญสูงของ APNs

Apple จำกัดจำนวนพุชที่มีลำดับความสำคัญสูง (apns-priority: 10) ที่แอปสามารถส่งได้ต่อชั่วโมง สำหรับกิจกรรมที่มีการอัปเดตบ่อยครั้ง (เช่น ผลการแข่งขันสด) ให้สงวน apns_priority: 10 ไว้สำหรับเหตุการณ์สำคัญและใช้ apns_priority: 5 หรือการอัปเดตที่น้อยลงสำหรับการเปลี่ยนแปลงตามปกติ การเปิดใช้งาน NSSupportsLiveActivitiesFrequentUpdates ใน Info.plist ของแอป (ดู คู่มือ iOS SDK) จะเพิ่มงบประมาณนี้สำหรับกรณีการใช้งานที่มีความถี่สูง

กิจกรรมหลายรายการต่ออุปกรณ์

คุณสามารถเริ่มต้น Live Activities หลายรายการบนอุปกรณ์เดียวกันได้โดยการเรียก startLiveActivity หลายครั้งด้วยค่า live_activity_id ที่แตกต่างกัน

ตัวอย่างเช่น หากคุณเริ่มต้นสองกิจกรรม: FIRST_LIVE_ACTIVITY ด้วย filter: FILTER_NAME_1 และ SECOND_LIVE_ACTIVITY ด้วย filter: FILTER_NAME_2 อุปกรณ์ที่ตรงกับทั้งสองฟิลเตอร์จะมีทั้งสองกิจกรรมทำงานพร้อมกัน

หากต้องการอัปเดตหนึ่งในนั้น ให้ส่ง live_activity_id ของกิจกรรมนั้นไปยัง updateLiveActivity การอัปเดตจะถูกส่งไปยังอุปกรณ์ทั้งหมดที่กิจกรรมนั้นถูกสร้างขึ้น กิจกรรมอื่นจะไม่ได้รับผลกระทบ

พารามิเตอร์ relevance-score ควบคุมลำดับความสำคัญในการแสดงผลเมื่อมี Live Activities หลายรายการทำงานอยู่บนอุปกรณ์เดียวกัน หากพื้นที่หน้าจอมีจำกัดหรือกิจกรรมถูกจัดกลุ่ม กิจกรรมที่มีค่าสูงกว่าจะแสดงด้วยลำดับความสำคัญที่สูงกว่า