واجهة برمجة تطبيقات مخططات Live Activity

مخطط Live Activity هو مخطط JSON لنوع ActivityAttributes واحد في تطبيقك (على سبيل المثال FlightAttributes)، يغطي نصفي البطاقة: حقول ContentState التي تتغير أثناء تشغيل النشاط، والحقول الثابتة طوال عمره. قم بنشر مخطط حتى يتمكن عنصر Live Activity في Journey من بناء حقول مسماة لكلا النصفين منه، بدلاً من محرر JSON خام وقائمة حقول حرة الشكل. لا يزال بناء البطاقة وتخطيطها يتم في كود تطبيقك. يصف المخطط فقط البيانات التي تملأها Journey.

واجهة برمجة التطبيقات هذه مخصصة للمطورين الذين يدمجون Live Activities. راجع واجهة برمجة تطبيقات iOS Live Activities لبدء وتحديث الأنشطة نفسها.

كتابة مخطط

attributesType هو اسم نوع Swift الذي يتوافق مع ActivityAttributes في تطبيقك. لا يقرأ Pushwoosh الكود الخاص بك أو يتحقق من صحة الاسم مقابله — إنه مجرد السلسلة النصية التي تخزنها واجهة برمجة التطبيقات والسلسلة التي تمررها إلى حقل attributes-type في startLiveActivity.

يغطي jsonSchema نصفي هذا النوع، في موضعين منفصلين:

• حقول ContentState، وهي الحقول التي تتغير أثناء تشغيل النشاط، مثل بوابة الرحلة أو حالتها أو وقت الوصول المتوقع، توضع في properties الجذرية للمخطط.
• حقول ActivityAttributes، الثابتة طوال عمر النشاط والتي يتم تعيينها مرة واحدة عند بدئه، مثل رقم الرحلة، توضع في قسم attributes منفصل، له properties خاصة به وقائمة required اختيارية.

قسم attributes اختياري. بدونه، تبقى حقول ActivityAttributes قائمة حقول حرة الاسم/القيمة على عنصر Live Activity بدلاً من حقول مسماة. تمرر دائمًا قيم السمات الفعلية عبر live_activity.attributes في startLiveActivity — يعلن المخطط فقط عن أسمائها وأنواعها وأيها مطلوب.

مثال

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

يوجد flightNumber في ActivityAttributes. توجد gate وstatus وestimatedTime في ContentState. انشر كلا النصفين كمخطط لـ attributesType: "FlightAttributes":

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

يجعل required داخل attributes الحقل flightNumber إلزاميًا في خطوة Start الخاصة بعنصر Live Activity: تركه فارغًا هناك مرفوض. لا تحتوي properties الجذرية لحقول ContentState على قائمة مماثلة. لا تكون Journey مطالبة أبدًا بملء gate أو status أو estimatedTime.

بمجرد النشر، يقرأ عنصر Live Activity في Journey هذا الشكل لتقديم حقول مسماة لـ gate وstatus وestimatedTime في Card content، بدلاً من محرر content-state خام. ويحدث الأمر نفسه لـ flightNumber في Card attributes، بدلاً من قائمة حقول حرة الاسم/القيمة.

راجع الأعراف أدناه لمعرفة التنسيق وقواعد عدم القابلية للتغيير التي تنطبق على jsonSchema، و إدارة المخططات في لوحة التحكم في نهاية هذه الصفحة لنفس الإجراءات دون استدعاء واجهة برمجة التطبيقات مباشرة.

عنوان URL الأساسي

https://rpc-api.svc-nue.pushwoosh.com

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز Server API token الخاص بك:

Authorization: Api YOUR_API_TOKEN

الأعراف

• تسمية الحقول غير متماثلة. تقبل الطلبات كلاً من lowerCamelCase واسم البروتوكول. تعود الاستجابات دائمًا بأسماء حقول البروتوكول، في snake_case (attributes_type، json_schema) — تستخدم الأمثلة أدناه هذه الحالة.
• الإصدارات غير قابلة للتغيير. لا يمكن تحرير إصدار منشور — لا توجد طريقة Update. يفشل النشر مرة أخرى بنفس attributesType و version مع AlreadyExists. تغيير عنصر واجهة المستخدم هو دائمًا إصدار جديد. احذف version عند Create لنشر الإصدار التالي المتاح لهذا attributesType.
• تنسيق jsonSchema: يجب أن يكون كائن JSON مع "type": "object"، بحجم يصل إلى 64 كيلوبايت. يتم رفض null، أو رقم، أو سلسلة نصية مجردة، أو كائن يفتقد "type": "object"، لأن النموذج الذي يبنيه Pushwoosh يحتاج إلى حقول مسماة، والتي لا يمتلكها إلا مخطط كائن. قسم attributes الاختياري، عند وجوده، يجب أن يكون بحد ذاته كائنًا له properties خاصة به، واختياريًا مصفوفة required تسمي فقط الحقول المعلنة في attributes.properties. لا يمكن أن يظهر اسم حقل في كل من properties وattributes.properties معًا.

نقاط النهاية

الطريقة	المسار	الوصف
GET	/api/live_activity_schemas	إدراج مخططات التطبيق
GET	/api/live_activity_schemas/{attributesType}/{version}	الحصول على إصدار مخطط واحد
POST	/api/live_activity_schemas	نشر إصدار مخطط جديد
DELETE	/api/live_activity_schemas/{attributesType}/{version}	حذف إصدار مخطط

إدراج

يدرج كل attributesType نشر له التطبيق مخططات، مع جميع إصداراتها، أحدث إصدار أولاً.

GET /api/live_activity_schemas

معلمات الاستعلام

المعلمة	النوع	مطلوب	الوصف
application	string	نعم	رمز التطبيق لإدراج المخططات له.
attributesType	string	لا	تقييد القائمة بنوع ActivityAttributes واحد.

مثال على الاستجابة

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

الحصول على

يعيد إصدار مخطط واحد.

GET /api/live_activity_schemas/{attributesType}/{version}

معلمات المسار

المعلمة	النوع	مطلوب	الوصف
attributesType	string	نعم	اسم نوع ActivityAttributes.
version	integer	نعم	إصدار المخطط.

معلمات الاستعلام

المعلمة	النوع	مطلوب	الوصف
application	string	نعم	رمز التطبيق الذي ينتمي إليه المخطط.

الاستجابة

يعيد { "schema": { ... } }، كائن المخطط الموضح في إدراج أعلاه.

إنشاء

ينشر إصدار مخطط جديد لـ attributesType. يعيد المخطط الذي تم إنشاؤه، بما في ذلك الإصدار الذي تم تعيينه له.

POST /api/live_activity_schemas

نص الطلب

المعلمة	النوع	مطلوب	الوصف
application	string	نعم	رمز التطبيق لنشر المخطط فيه.
attributesType	string	نعم	اسم نوع ActivityAttributes المعلن عنه في تطبيقك.
jsonSchema	string	نعم	مخطط JSON لكل من ContentState وattributes. راجع كتابة مخطط أعلاه.
version	integer	لا	الإصدار المراد نشره. احذفه للحصول على الإصدار التالي المتاح لهذا attributesType.

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

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

الاستجابة

يعيد { "schema": { ... } }، كائن المخطط الذي تم إنشاؤه.

تنبيه

يفشل نشر زوج attributesType/version موجود بالفعل مع AlreadyExists — الإصدارات غير قابلة للتغيير، لذلك لا توجد طريقة للكتابة فوق أحدها. انشر بدون version للحصول على الإصدار التالي بدلاً من ذلك.

حذف

يحذف بشكل دائم إصدار مخطط واحد.

DELETE /api/live_activity_schemas/{attributesType}/{version}

معلمات المسار

المعلمة	النوع	مطلوب	الوصف
attributesType	string	نعم	اسم نوع ActivityAttributes.
version	integer	نعم	إصدار المخطط المراد حذفه.

معلمات الاستعلام

المعلمة	النوع	مطلوب	الوصف
application	string	نعم	رمز التطبيق الذي ينتمي إليه المخطط.

الاستجابة

يعيد كائنًا فارغًا عند النجاح.

خطر

لا يمكن التراجع عن هذا الإجراء. يحتفظ عنصر Live Activity في Journey الذي تم بناؤه مقابل الإصدار المحذوف بقيم المحتوى والسمات المحفوظة بالفعل. يفقد فقط تلميحات النموذج لكليهما من ذلك الحين فصاعدًا: يعود المحتوى إلى محرر JSON خام، وتعود السمات إلى قائمة حقول حرة الاسم/القيمة.

استجابات الخطأ

حالة HTTP	المعنى
400 Bad Request	وسيطة غير صالحة: حقل مطلوب مفقود، أو jsonSchema يفشل في قاعدة التنسيق أعلاه (بما في ذلك قسم attributes غير صالح)، أو يتجاوز jsonSchema 64 كيلوبايت.
401 Unauthorized	ترويسة Authorization مفقودة أو غير صالحة.
403 Forbidden	التطبيق لا ينتمي إلى حساب المتصل.
404 Not Found	لم يتم العثور على التطبيق، أو زوج attributesType/version.
409 Conflict	تم استدعاء Create بزوج attributesType/version موجود بالفعل (AlreadyExists على الشبكة).
500 Internal Server Error	فشل غير متوقع من جانب الخادم.

إدارة المخططات في لوحة التحكم

تقدم لوحة التحكم نفس الإجراءات التي تقدمها واجهة برمجة التطبيقات دون استدعائها مباشرة: إدراج الإصدارات حسب النوع، ونشر إصدار جديد، وعرض JSON لإصدار، وحذف إصدار (مع تأكيد، لأن الحذف دائم). راجع تكوين مخططات iOS Live Activity لمسار النقر.