واجهة برمجة تطبيقات iOS Live Activities

توثيق Apple:

• حول الأنشطة الحية (Live Activities)
• تحديث وإنهاء الأنشطة الحية باستخدام إشعارات ActivityKit push

startLiveActivity

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

يسمح بإنشاء أنشطة iOS الحية (Live Activities).

نص الطلب

المعلمة	النوع	مطلوب/اختياري	الوصف
application	String	مطلوب	رمز تطبيق Pushwoosh
auth	String	مطلوب	رمز وصول API من لوحة تحكم Pushwoosh.
notifications	Array	مطلوب	مصفوفة JSON من معلمات الرسالة. انظر التفاصيل في جدول الإشعارات أدناه.

الإشعارات

المعلمات المستخدمة في مصفوفة notifications:

المعلمة	النوع	مطلوب/اختياري	الوصف
content	String	مطلوب	محتوى احتياطي للأجهزة التي تعمل بإصدارات iOS أقل من 16.1 والتي لا تدعم الأنشطة الحية. في iOS 16.1+ (مع دعم الأنشطة الحية)، يتم الحصول على المحتوى من حقل live_activity.
title	String	اختياري	عنوان رسالة الإشعار.
live_activity	Object	مطلوب	بيانات النشاط الحي لإنشاء نشاط حي في iOS.
live_activity.content-state	Object	مطلوب	محتوى إشعار النشاط الحي.
live_activity.attributes-type	String	مطلوب	نوع السمات المستخدمة في النشاط الحي.
live_activity.attributes	Object	مطلوب	سمات النشاط الحي.
live_activity_id	String	مطلوب	معرف فريد للنشاط الحي. يستخدم لاستهداف هذا النشاط عند استدعاء updateLiveActivity. يجب أن يكون فريدًا لكل جلسة نشاط.
filter	String	اختياري	اسم فلتر (segment) في Pushwoosh. انظر اسم الفلتر / الشريحة. سيتم بدء النشاط الحي على جميع الأجهزة التي تطابق هذا الفلتر.
devices	Array of Strings	اختياري	قائمة بـ رموز الأجهزة. سيتم بدء النشاط الحي فقط على الأجهزة المحددة.
send_date	String	اختياري	يجدول الإشعار الذي يبدأ النشاط الحي لتاريخ ووقت محددين - يعمل مع استهداف filter أو devices. استخدم التنسيق YYYY-MM-DD HH:mm، أو now للبدء فورًا (وهذا هو الإعداد الافتراضي أيضًا عند حذف المعلمة). يجب ألا يكون أكثر من يوم واحد في الماضي أو 30 يومًا في المستقبل، وإلا سيتم رفض الطلب بخطأ في التحقق.
timezone	String	اختياري	المنطقة الزمنية المستخدمة لتفسير send_date. إذا تم حذفه، يتم تفسير send_date بتوقيت UTC.
apns_priority	Integer	اختياري	يتحكم في أولوية تسليم APNs لهذا الإشعار الخاص بالنشاط الحي. يقبل 10 (أولوية عالية، يتم تسليمها مع رأس apns-priority: 10 للعرض الفوري على شاشة مقفلة) أو 5 (أولوية منخفضة، يتم تسليمها مع apns-priority: 5 للحفاظ على بطارية الجهاز). أي قيمة أخرى تُعامل على أنها 5، بدون خطأ في التحقق. كل إشعار نشاط حي يكون افتراضيًا بأولوية 5 بغض النظر عما إذا كان يحمل محتوى تنبيه (content/title) - قم بتعيين apns_priority: 10 صراحة لطلب تسليم بأولوية عالية. انظر إشعارات الدفع الحساسة للوقت وأولوية التسليم أدناه.

تنبيه

يتطلب البدء عن بعد لنشاط حي عبر startLiveActivity إصدار iOS 17.2+ على الجهاز - الإصدارات السابقة لا تدعم واجهة برمجة تطبيقات pushToStartTokenUpdates التي يعتمد عليها هذا الـ endpoint. انظر بدء نشاط حي بإشعار دفع عن بعد.

عند استهداف filter (segment)، فإن وقت الإرسال المجدول هو عندما يبدأ Pushwoosh في إرسال الإشعار، وليس لحظة تسليم مضمونة - بالنسبة للجماهير الكبيرة، يمكن أن يتأخر التسليم إلى الأجهزة الفردية عن send_date ببضع دقائق، حيث لا يمكن تخصيص معدل الإرسال لإشعارات الأنشطة الحية باستخدام 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"
    ]
  }
}

ملاحظة:

اقرأ هذا المقال لمعرفة المزيد حول العمل مع الأنشطة الحية باستخدام Pushwoosh iOS SDK.

updateLiveActivity

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

يسمح بتحديث وإنهاء أنشطة iOS الحية (Live Activities)

نص الطلب

المعلمة	النوع	مطلوب/اختياري	الوصف
auth	String	مطلوب	رمز وصول API من لوحة تحكم Pushwoosh.
application	String	مطلوب	رمز تطبيق Pushwoosh
notifications	Array	مطلوب	مصفوفة JSON من معلمات الرسالة. انظر التفاصيل في جدول الإشعارات أدناه.

الإشعارات

المعلمات المستخدمة في مصفوفة notifications:

المعلمة	النوع	مطلوب/اختياري	الوصف
live_activity	Object	مطلوب	بيانات النشاط الحي لتحديث النشاط الحي في iOS.
live_activity.event	String	مطلوب	يحدد نوع الحدث. استخدم "update" لتحديث النشاط الحي أو "end" لإغلاقه.
live_activity.content-state	Object	مطلوب	كائن يحتوي على أزواج مفتاح-قيمة يستخدم لتمرير البيانات إلى النشاط الحي لتحديث محتواه.
live_activity.dismissal-date	Integer	اختياري	الوقت (بالثواني) الذي يجب أن ينتهي فيه النشاط الحي.
live_activity_id	String	مطلوب	المعرف الفريد للنشاط الحي المراد تحديثه. يجب أن يتطابق مع live_activity_id المستخدم في startLiveActivity. سيتم تسليم التحديث إلى جميع الأجهزة التي بدأ عليها هذا النشاط.
live_activity.relevance-score	Integer	اختياري	يخبر نظام iOS أي نشاط حي له أولوية أعلى من غيره. يقبل قيمًا من 1 إلى ما لا نهاية (يوصى بقيم تصل إلى 100).
live_activity.stale-date	Integer	اختياري	الوقت (بالثواني) الذي يمثل التاريخ الذي يصبح فيه النشاط الحي قديمًا أو غير محدث.
apns_priority	Integer	اختياري	يتحكم في أولوية تسليم APNs لهذا الإشعار الخاص بالنشاط الحي. يقبل 10 (أولوية عالية، يتم تسليمها مع رأس apns-priority: 10 للعرض الفوري على شاشة مقفلة) أو 5 (أولوية منخفضة، يتم تسليمها مع apns-priority: 5 للحفاظ على بطارية الجهاز). أي قيمة أخرى تُعامل على أنها 5، بدون خطأ في التحقق. كل إشعار نشاط حي يكون افتراضيًا بأولوية 5 بغض النظر عما إذا كان يحمل محتوى تنبيه (content/title) - قم بتعيين apns_priority: 10 صراحة لطلب تسليم بأولوية عالية. انظر إشعارات الدفع الحساسة للوقت وأولوية التسليم أدناه.

ملاحظة: يؤثر relevance-score فقط على ترتيب العرض بين عدة أنشطة حية نشطة على نفس الجهاز - لا يؤثر على سرعة التسليم. استخدم 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"
    ]
  }
}

اقرأ هذا المقال لمعرفة المزيد حول العمل مع الأنشطة الحية باستخدام Pushwoosh iOS SDK.

إشعارات الدفع الحساسة للوقت وأولوية التسليم

بشكل افتراضي، تقوم Apple بتسليم تحديثات الأنشطة الحية بأولوية منخفضة (apns-priority: 5) للحفاظ على البطارية. عندما يكون الجهاز مقفلاً، تتم معالجة التحديث ذي الأولوية المنخفضة في الخلفية ويصبح مرئيًا فقط على شاشة القفل بمجرد أن يقوم المستخدم بفتح الجهاز. على جهاز مفتوح بالفعل، لا يزال يتم عرضه على الفور. استخدم معلمة apns_priority الموضحة أعلاه لطلب تسليم بأولوية عالية (apns-priority: 10) بحيث يتم عرض التحديث على شاشة القفل على الفور، دون الحاجة إلى فتح الجهاز.

لا علاقة له بمفتاح Time Sensitive Push

يقوم مفتاح Time Sensitive Push في لوحة تحكم Pushwoosh بتعيين interruption-level لإشعارات الدفع القياسية فقط. ليس له أي تأثير على أولوية تسليم الأنشطة الحية المرسلة عبر هذه الواجهة البرمجية (API) - تستخدم الأنشطة الحية مسار تسليم منفصل، يتم التحكم فيه حصريًا بواسطة معلمة الطلب apns_priority.

حتى مع توفر apns_priority: 10، تضع Apple حدًا لعدد المرات التي يمكن استخدامها فيها.

ميزانية الأولوية العالية لـ APNs

تحد Apple من عدد إشعارات الدفع ذات الأولوية العالية (apns-priority: 10) التي يمكن للتطبيق إرسالها في الساعة. بالنسبة للأنشطة التي يتم تحديثها بشكل متكرر (مثل النتائج المباشرة)، احتفظ بـ apns_priority: 10 للأحداث الهامة واستخدم apns_priority: 5 أو تحديثات أقل للتغييرات الروتينية. يؤدي تمكين NSSupportsLiveActivitiesFrequentUpdates في ملف Info.plist الخاص بتطبيقك (انظر دليل iOS SDK) إلى زيادة هذه الميزانية لحالات الاستخدام عالية التردد.

أنشطة متعددة لكل جهاز

يمكنك بدء أنشطة حية متعددة على نفس الجهاز عن طريق استدعاء startLiveActivity عدة مرات بقيم live_activity_id مختلفة.

على سبيل المثال، إذا بدأت نشاطين: FIRST_LIVE_ACTIVITY مع filter: FILTER_NAME_1 و SECOND_LIVE_ACTIVITY مع filter: FILTER_NAME_2، فإن الجهاز الذي يطابق كلا الفلترين سيكون لديه كلا النشاطين يعملان في وقت واحد.

لتحديث أحدهما، مرر live_activity_id الخاص به إلى updateLiveActivity. يتم تسليم التحديث إلى جميع الأجهزة التي تم إنشاء هذا النشاط عليها. لا يتأثر النشاط الآخر.

تتحكم معلمة relevance-score في أولوية العرض عندما تكون هناك أنشطة حية متعددة نشطة على نفس الجهاز. إذا كانت مساحة الشاشة محدودة أو تم تجميع الأنشطة، يتم عرض النشاط ذي القيمة الأعلى بأولوية أعلى.