واجهة برمجة تطبيقات الأنشطة المباشرة لنظام iOS

وثائق Apple:

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

للسماح لنقطة بناء Live Activity في Customer Journey ببناء نموذج حالة المحتوى الخاص بها من أسماء الحقول بدلاً من محرر JSON الخام، قم بنشر مخطط لـ attributes-type الخاص بك — راجع واجهة برمجة تطبيقات مخططات الأنشطة المباشرة.

startLiveActivity

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

يسمح بإنشاء الأنشطة المباشرة لنظام iOS.

نص الطلب

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

الإشعارات

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

المعلمة	النوع	مطلوب/اختياري	الوصف
content	String	مطلوب*	نص التنبيه للدفع الذي يبدأ النشاط المباشر، والنص الاحتياطي الذي يظهر على الأجهزة التي تعمل بإصدارات iOS أقل من 16.1.
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	اختياري	اسم فلتر 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 بشكل صريح لطلب تسليم عالي الأولوية. انظر إشعارات الدفع الحساسة للوقت وأولوية التسليم أدناه.

ملاحظة: * يجب أن يكون أحد الحقلين content أو title على الأقل غير فارغ. يرفض Pushwoosh طلب البدء إذا كان كلاهما فارغًا.

تنبيه

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

عند استهداف filter (شريحة)، يكون وقت الإرسال المجدول هو الوقت الذي يبدأ فيه Pushwoosh إرسال الدفع، وليس لحظة تسليم مضمونة — بالنسبة للجماهير الكبيرة، يمكن أن يتأخر التسليم إلى الأجهزة الفردية عن send_date ببضع دقائق، حيث لا يمكن تخصيص معدل الإرسال لدفعات الأنشطة المباشرة باستخدام send_rate.

تستنفد استدعاءات الدفع للبدء المتكررة بصمت. بعد حوالي عشر بدايات متتالية، تتوقف Apple عن تسليم إشعار الدفع للبدء الأساسي دون أي خطأ، ولا يزال startLiveActivity يعيد 200. أثناء اختبار الحملة، يبدو هذا وكأن “واجهة برمجة التطبيقات تعمل ولكن لا شيء يحدث على الجهاز”. قم بتباعد بدايات الاختبار المتتالية.

مثال على الطلب

مع الفلتر

{
  "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

نص الطلب

المعلمة	النوع	مطلوب/اختياري	الوصف
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	اختياري	الوقت (بالثواني) الذي يجب أن ينتهي فيه النشاط المباشر. عند end، احذف هذا الحقل لتستمر البطاقة في عرض آخر content-state لها حتى يزيلها iOS من تلقاء نفسه — انظر الملاحظة أدناه. حدد تاريخًا في الماضي لإزالة البطاقة بمجرد وصول هذا التحديث بدلاً من ذلك.
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 بشكل صريح لطلب تسليم عالي الأولوية. انظر إشعارات الدفع الحساسة للوقت وأولوية التسليم أدناه.
content	String	اختياري	نص التنبيه لهذا التحديث. الحالة الشائعة هي تحديث حالة المحتوى فقط، والذي لا يعين أيًا من content أو title أو subtitle ولا يحمل أي تنبيه على الإطلاق.
title	String	اختياري	عنوان التنبيه لهذا التحديث. يؤدي تعيين content أو title أو subtitle إلى تشغيل تنبيه ويسمح بتشغيل ios_sound. مع عدم تعيين أي من الثلاثة، يظل التحديث صامتًا، وهو الإعداد الافتراضي لتحديثات حالة المحتوى فقط.
subtitle	String	اختياري	عنوان فرعي للتنبيه لهذا التحديث. له نفس دور تشغيل التنبيه مثل content/title أعلاه.
ios_sound	String	اختياري	اسم ملف الصوت في الحزمة الرئيسية للتطبيق. يركب داخل aps.alert إلى جانب content/title/subtitle، وليس aps.sound على المستوى الأعلى، والذي يتجاهله ActivityKit للأنشطة المباشرة، لذلك يتم تشغيله فقط عندما يقوم هذا التحديث أيضًا بتعيين واحد على الأقل من هؤلاء الثلاثة. يقوم iOS أيضًا بتحديد معدل تنبيهات الأنشطة المباشرة من تلقاء نفسه. لوحظ أن نفس الحمولة تصل مع صوت في تسليم واحد وبدونه في التسليم التالي، على كل من الجهاز والمحاكي.

ملاحظة: يؤثر relevance-score فقط على ترتيب العرض بين عدة أنشطة مباشرة نشطة على نفس الجهاز — لا يؤثر على إلحاح التسليم. استخدم apns_priority للتحكم في مدى إلحاح تسليم التحديث.

ملاحظة

لا يؤدي end بدون dismissal-date إلى إزالة البطاقة. تبقى على شاشة القفل معروضة بآخر content-state أرسله هذا التحديث، ويقوم نظام Live Activity الخاص بشركة Apple بإزالتها من تلقاء نفسه خلال ما يصل إلى 4 ساعات.

مثال على الطلب

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "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 لإشعارات الدفع القياسية فقط. ليس له أي تأثير على أولوية تسليم الأنشطة المباشرة المرسلة عبر واجهة برمجة التطبيقات هذه — تستخدم الأنشطة المباشرة مسار تسليم منفصل، يتم التحكم فيه حصريًا بواسطة معلمة الطلب 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 في أولوية العرض عندما تكون هناك أنشطة مباشرة متعددة نشطة على نفس الجهاز. إذا كانت مساحة الشاشة محدودة أو تم تجميع الأنشطة، يتم عرض النشاط ذي القيمة الأعلى بأولوية أعلى.