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

توثيق Apple:

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

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 والتي لا تدعم الأنشطة المباشرة. على 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	اختياري	اسم فلتر Pushwoosh (شريحة). انظر اسم الشريحة / الفلتر. سيتم بدء النشاط المباشر على جميع الأجهزة التي تطابق هذا الفلتر.
devices	Array of Strings	اختياري	قائمة من رموز الأجهزة. سيتم بدء النشاط المباشر فقط على الأجهزة المحددة.
send_date	String	اختياري	يجدول الدفعة التي تبدأ النشاط المباشر لتاريخ ووقت محددين — يعمل مع استهداف filter أو devices. استخدم التنسيق YYYY-MM-DD HH:mm، أو now للبدء فورًا (وهذا هو الإعداد الافتراضي أيضًا عند حذف المعلمة). يجب ألا يكون أقدم من يوم واحد في الماضي أو أكثر من 30 يومًا في المستقبل، وإلا فسيتم رفض الطلب بخطأ في التحقق.
timezone	String	اختياري	المنطقة الزمنية المستخدمة لتفسير send_date. إذا تم حذفها، يتم تفسير send_date بتوقيت UTC.

تنبيه

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

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

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

مع فلتر

{
  "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": "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",
        "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	اختياري	الوقت (بالثواني) الذي يجب أن ينتهي فيه النشاط المباشر.
live_activity_id	String	مطلوب	المعرف الفريد للنشاط المباشر المراد تحديثه. يجب أن يتطابق مع live_activity_id المستخدم في startLiveActivity. سيتم تسليم التحديث إلى جميع الأجهزة التي بدأ عليها هذا النشاط.
live_activity.relevance-score	Integer	اختياري	يخبر نظام iOS أي نشاط مباشر له أولوية أعلى من غيره. يقبل القيم من 1 إلى ما لا نهاية (يوصى بالقيم حتى 100).
live_activity.stale-date	Integer	اختياري	الوقت (بالثواني) الذي يمثل التاريخ الذي يصبح فيه النشاط المباشر قديمًا أو غير محدث.

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

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "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.

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

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

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

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

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