تكامل حالة الرحلة

أخبر الركاب بالتغييرات في رحلتهم فور حدوثها: بوابة جديدة، تأخير، صعود إلى الطائرة، وصول، أو إلغاء. يربط تكامل حالة الرحلة Pushwoosh بـ AeroDataBox، وهو مزود بيانات رحلات، بحيث يمكن لـ customer journey مراقبة رحلة راكب معين والتفاعل في اللحظة التي تتغير فيها حالتها.

مطلوب مساعدة من المطورين

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

نظرة عامة على التكامل

نوع التكامل

المصدر: يمكنك اشتراك حجز في رحلته من داخل رحلة. يرسل Pushwoosh تغييرات الحالة مرة أخرى كحدث تستخدمه لاحقًا في نفس الرحلة.

المتطلبات الأساسية

قبل ربط حالة الرحلة، تأكد من أن لديك:

• حساب Pushwoosh نشط مع تطبيق في مركز بيانات NUE الخاص بـ Pushwoosh. حالة الرحلة غير متاحة في مراكز البيانات الأخرى حتى الآن.
• حساب AeroDataBox ومفتاح API. تتم فوترة التغذية على حساب AeroDataBox الخاص بك.
• حدث حجز يحمل شركة الطيران ورقمها وتاريخها ومطار المغادرة (انظر بناء رحلة حالة الرحلة).
• API Access token مخصص للمصادقة في الرحلة.

كيف يعمل التكامل؟

ربط التكامل ومراقبة رحلة واحدة هما خطوتان منفصلتان، تتمان في أوقات مختلفة:

1. اربط مفتاح AeroDataBox الخاص بك في الإعدادات ← تكاملات الطرف الثالث.
2. يدخل حدث حجز راكبًا في رحلتك.
3. تشترك خطوة Webhook في الرحلة في هذا الحجز في رحلته من خلال واجهة برمجة التطبيقات العامة لـ Pushwoosh.
4. يراقب Pushwoosh الرحلة مع AeroDataBox ويكتشف التغييرات: البوابة، التأخير، الصعود إلى الطائرة، الوصول، الإلغاء، أو تخصيص حزام الأمتعة.
5. يتم تسليم كل تغيير إلى التطبيق كحدث PW_FlightStatusChanged، والذي يوجهه Wait for Trigger و Condition split في الرحلة إلى الرسالة الصحيحة.

ينتهي كل اشتراك في رحلة تلقائيًا بعد 36 ساعة من تاريخ المغادرة المحلي. وقد ينتهي قبل ذلك: بمجرد هبوط الرحلة أو إلغائها، أو بمجرد ألا يعود هناك ما يراقبها. يلغي Pushwoosh بعد ذلك اشتراك AeroDataBox المطابق، حتى لا تستمر الفوترة في الخلفية.

تُحدَّد هذه الفترة عند الاشتراك، بدءًا من تاريخ المغادرة المحجوز، ولا تتغير إذا أبلغ AeroDataBox لاحقًا عن تأخير. قد يؤدي التأخير الذي ينقل الرحلة إلى اليوم التالي إلى انتهاء الاشتراك قبل موعد المغادرة الفعلي المتأخر.

حالات الاستخدام

تغطي حالة الرحلة أربعة أنواع من التحديثات، يمكن استخدام كل منها بمفرده أو دمجها في رحلة واحدة:

• تنبيهات تغيير البوابة: أخطر الركاب في اللحظة التي تتغير فيها بوابة مغادرتهم.
• إشعارات التأخير: نبه الركاب بمجرد أن يتجاوز تأخير الرحلة بضع دقائق، حتى يتمكنوا من تعديل خططهم.
• تحديثات الصعود والوصول: أخبر الركاب عند فتح الصعود إلى الطائرة أو عند هبوط رحلتهم.
• استلام الأمتعة: أرسل رقم حزام الأمتعة بمجرد تخصيصه.

إعداد التكامل

ربط حالة الرحلة بـ Pushwoosh

اربط مفتاح AeroDataBox الخاص بك مرة واحدة لكل تطبيق:

1. افتح تطبيقك وانتقل إلى الإعدادات ← تكاملات الطرف الثالث.

2. تحت الخدمات المتاحة، ابحث عن بطاقة حالة الرحلة وانقر على تكوين.

   

3. الصق مفتاح AeroDataBox الخاص بك في مفتاح API وانقر على ربط.

   

بعد النقر على ربط، تنتقل البطاقة إلى الخدمات المتصلة.

إذا تم رفض المفتاح

يتحقق Pushwoosh من المفتاح في الخلفية. إذا كان هناك خطأ ما، تعرض البطاقة إحدى هذه الرسائل:

الرسالة	السبب
provider rejected the API key	المفتاح غير صالح أو تم إبطاله في AeroDataBox
provider account is out of credits	لقد نفد رصيد خطة AeroDataBox الخاصة بك
provider rate limit reached	يقوم AeroDataBox بتقييد الطلبات، وهذا يزول من تلقاء نفسه
provider is unavailable	تعذر الوصول إلى AeroDataBox، بسبب مشكلة في الشبكة أو انقطاع في أي من الجانبين
provider refused the request	أعاد AeroDataBox خطأ لا يتعرف عليه Pushwoosh بطريقة أخرى

استبدال المفتاح

أعد فتح بطاقة حالة الرحلة في الخدمات المتصلة، على سبيل المثال بعد رفض المفتاح:

• استبدال المفتاح: الصق مفتاحًا جديدًا في مفتاح API.
• الاحتفاظ بالمفتاح الحالي: اترك مفتاح API فارغًا. يعرض الحقل الأحرف القليلة الأخيرة فقط من المفتاح المحفوظ.

فصل التكامل

1. افتح بطاقة حالة الرحلة في الخدمات المتصلة.
2. أزل المفتاح.

بعد الفصل:

• لم تعد تُنشأ اشتراكات جديدة.
• تحتفظ الرحلات الجوية التي تراقبها رحلات العملاء بالفعل باشتراكاتها حتى تنتهي من تلقاء نفسها أو تحذفها من الرحلة.
• يتضمن عدد الاشتراكات النشطة على البطاقة هذه الاشتراكات حتى تنتهي.

بناء رحلة حالة الرحلة

قبل بناء الرحلة

تأكد من أن لديك:

• حدث حجز يحمل شركة الطيران، الرقم، التاريخ (YYYY-MM-DD)، ومطار المغادرة، بالإضافة إلى سمة واحدة تحمل مفتاح الرحلة بتنسيق <carrier><number>/<date>/<departure airport>، على سبيل المثال LH400/2026-09-20/MUC. هذا هو ما تستخدمه مطابقة الجلسة طوال الرحلة.
• API Access token مخصص. تقبل طريقة الاشتراك أي رمز مميز من حسابك، دون الحاجة إلى منح أذونات. أنشئ واحدًا خصيصًا لهذه الرحلة حتى تتمكن من إبطاله لاحقًا دون المساس بأي شيء آخر.
• مضيف واجهة برمجة التطبيقات العامة لمركز البيانات الخاص بك. بالنسبة لحسابات NUE، هذا هو rpc-api.svc-nue.pushwoosh.com.
• حد دخول الحملة للرحلة، معطل. يتتبع حد دخول الحملة الإدخالات لكل مستخدم فقط. لا يعرف عن معرف الجلسة الذي قمت بإعداده أدناه، لذلك سيمنع رحلة الراكب الثانية حتى تمر فترة الحد.

بدء الرحلة من حدث حجز

1. أضف Trigger-based entry واختر حدث الحجز الخاص بك، على سبيل المثال flight_booked.
2. تحت التحكم في عدد الجلسات التي يمكن للمستخدم أن يكون لديه في نفس الوقت، اختر جلسات نشطة متعددة لكل مستخدم.
3. اختر سمة مفتاح الرحلة كمعرف للجلسة. هذا يسمح لنفس الراكب بتتبع أكثر من رحلة واحدة في وقت واحد، كل منها في جلستها الخاصة.

اشتراك الحجز بخطوة Webhook

أضف خطوة Webhook مباشرة بعد الدخول. يسحب جسم الطلب الخاص به حقول الرحلة من حدث الدخول، لذلك يجب أن تكون الخطوة مباشرة بعد الدخول لاستخدامها.

1. اضبط REQUEST TYPE على POST.

2. اضبط URL على https://rpc-api.svc-nue.pushwoosh.com/api/integrations/flight-status/subscriptions.

3. في HEADERS، احتفظ بـ Content-Type: application/json.

4. أضف رأسًا Authorization: Token <your API token>. يخفي Pushwoosh هذه القيمة بعد الحفظ، لأن أي رأس يسمى Authorization يُعامل تلقائيًا كسر. انظر Mark a header value as secret لمعرفة ما يعنيه ذلك للتحرير وسجل الإصدارات.

5. في DATA، أدخل جسم الطلب أدناه، واكتب رمز التطبيق الخاص بك مباشرة:

   {
     "application": "<your application code>",
     "user_id": "{{device:user_id}}",
     "source": "journey",
     "flight": {
       "carrier": "",
       "flight_number": "",
       "flight_date": "",
       "departure_airport": ""
     }
   }

6. لكل من قيم flight الأربعة الفارغة، افتح DATA BUILDER.

7. اختر فئة Event.

8. اختر السمة المطابقة من حدث الحجز الخاص بك (شركة الطيران، رقم الرحلة، تاريخ الرحلة، مطار المغادرة).

9. انسخ الماكرو الذي ينشئه Pushwoosh والصقه كقيمة لذلك الحقل. كرر ذلك للقيم الثلاث المتبقية.

لا تحتاج إلى تعيين أي شيء من الاستجابة. فهي تعيد flight_key، الموجود بالفعل في حدث الحجز الخاص بك.

تنبيه

إذا فشل استدعاء الاشتراك، يغادر الراكب الرحلة في هذه الخطوة، تمامًا كما هو الحال مع أي خطوة Webhook. لن تتم مراقبة رحلته، ولن يتلقى أيًا من التنبيهات في أسفل الرحلة. انظر What happens when a request fails.

انتظار تحديث الحالة

أضف خطوة Wait for Trigger بعد خطوة Webhook.

1. أضف فرعًا واحدًا واضبط حدثه على PW_FlightStatusChanged.
2. تحت مطابقة سمة الجلسات المتعددة، اختر نفس سمة مفتاح الرحلة التي استخدمتها عند الدخول. هذا يضمن أن تحديث الحالة يوقظ فقط الراكب الذي يتعلق به بالفعل.
3. اضبط فترة الانتظار لتغطية الرحلة بشكل مريح. 48 ساعة كافية لمعظم مسارات الرحلات.
4. اترك فرع Not triggered بدون خطوة تالية، أو أضف رسالة احتياطية. يغادر الركاب الذين لا يصل تحديث لرحلتهم قبل انتهاء فترة الانتظار الرحلة هنا، وهذا متوقع.

التفرع حسب نوع الحدث

أضف Condition split بعد خطوة Wait for Trigger.

1. اختر Event كنوع للشرط.
2. في Event from Journey، اختر PW_FlightStatusChanged.
3. تحت Attribute، اختر event_type.
4. اضبط الشرط على is.
5. أضف فرعًا بالقيمة gate_change.
6. انقر على Save. هذا ينشئ فرعين: الفرع الذي سميته لتغيير البوابة، و All other users لكل أنواع الأحداث الأخرى.

كرر هذا العنصر، أو أضف المزيد من الفروع إليه، لقيم event_type الأخرى التي تريد التصرف بناءً عليها: delay، boarding، departed، arrived، cancelled، و baggage_ready تعمل جميعها بنفس الطريقة.

إخطار الراكب

أضف عنصر Push على فرع تغيير البوابة.

1. اختر أو أنشئ إعدادًا مسبقًا للدفع.
2. اضبط Message type على Transactional message، لأن تنبيه حالة الرحلة هو إشعار خدمة، وليس ترويجيًا. لا ينطبق تحديد التكرار، ولا يزال يصل إلى الركاب في control group.
3. قم بتمكين personalization with event attributes.
4. اختر PW_FlightStatusChanged كحدث مصدر.
5. املأ العناصر النائبة للإعداد المسبق الخاص بك من flight_number و gate_new.

عرض بطاقة Live Activity بدلاً من ذلك

أضف ثلاثة عناصر Live Activity، بدلاً من Push أو بالإضافة إليه:

• Start: مباشرة بعد خطوة Webhook، وليس مباشرة بعد الدخول. يتصل الدخول بخطوة تالية واحدة فقط، لذلك لا يمكن أن تأتي خطوتا Webhook و Start كلتاهما مباشرة بعده.
• Update: على فرع تغيير البوابة.
• End: بمجرد أن لا تعود الرحلة بحاجة إلى تتبع الطيران، على سبيل المثال بعد الوصول أو الإلغاء.

في عنصر Start، تحت Card attributes، أضف جميع الحقول الستة التي يحتاجها نوع ActivityAttributes الخاص بالبطاقة. Card attributes هي قائمة حرة من الأسماء والقيم، ولا تتحقق الواجهة من الأسماء، لذا أدخل كل اسم تمامًا كما هو مدرج. خمسة منها موجودة بالفعل في حدث الحجز الخاص بك:

• carrier
• flight_number
• flight_date
• departure_airport
• flight_key
• arrival_airport: لا يحتاجه استدعاء الاشتراك، لذا أضفه إلى حدث الحجز الخاص بك فقط إذا كنت تستخدم Live Activity.

تنبيه

إذا كانت أي من Card attributes الستة مفقودة، فلن تعرض الواجهة أي خطأ، لكن البطاقة لن تظهر أبدًا على الجهاز. يفشل بعد ذلك كل Update أو End لاحق لهذا الراكب برمز التسليم 1031 (“push token not found for the specified Live Activity ID”).

فقط Start يعيّن Card attributes، وتبقى كما هي طوال عمر البطاقة. لا يعيّنها Update و End. الحقول التي تتغير، مثل الحالة والبوابة والتأخير، هي Card content، وتأتي من مخطط widget الذي تنشره لهذا التطبيق.

مرجع حدث PW_FlightStatusChanged

يتم تسليم كل تغيير يكتشفه التكامل كحدث PW_FlightStatusChanged واحد، مع وجود جميع السمات دائمًا: يتم إرسال السمات الفارغة كقيم فارغة، ولا يتم تركها أبدًا.

السمة	النوع	الوصف
event_type	String	ما الذي تغير (انظر القيم أدناه)
flight_key	String	نفس مفتاح الرحلة الذي قمت بتعيينه في حدث الحجز
flight_number	String	رقم الرحلة
departure_airport	String	رمز مطار المغادرة
arrival_airport	String	رمز مطار الوصول
status	String	حالة الرحلة الحالية (انظر القيم أدناه)
gate_old / gate_new	String	بوابة المغادرة قبل وبعد التغيير
terminal_old / terminal_new	String	صالة المغادرة قبل وبعد التغيير
baggage_claim	String	رقم حزام الأمتعة، بمجرد تخصيصه
provider	String	مزود البيانات الذي أبلغ عن التغيير (aerodatabox)
delay_minutes	Integer	دقائق التأخر عن الجدول الزمني، موجودة في كل حدث
scheduled_at / estimated_at / actual_at	String	أوقات المغادرة المجدولة والمقدرة حاليًا والفعلية، بتنسيق المزود الخاص
arrival_terminal	String	صالة الوصول، بمجرد تخصيصها
arrival_scheduled_at / arrival_estimated_at / arrival_actual_at	String	أوقات الوصول المجدولة والمقدرة حاليًا والفعلية، بتنسيق المزود الخاص
scheduled_at_local / estimated_at_local / actual_at_local	String	أوقات المغادرة الثلاثة أعلاه، بالتوقيت المحلي لمطار المغادرة
arrival_scheduled_at_local / arrival_estimated_at_local / arrival_actual_at_local	String	أوقات الوصول الثلاثة أعلاه، بالتوقيت المحلي لمطار الوصول
flight_date / event_time	Date	تاريخ الرحلة، ووقت حدوث التغيير

قيم السمات وتنسيقاتها

• قيم event_type: gate_change، delay، boarding، departed، arrived، cancelled، baggage_ready.
• قيم status: scheduled، check_in، boarding، departed، delayed، arrived، cancelled، diverted، unknown. يتم الإبلاغ عن حالة AeroDataBox التي لا يتعرف عليها Pushwoosh على أنها unknown.
• delay_minutes: موجودة في كل حدث، وليس فقط في أحداث delay. تعني القيمة 0 أن الرحلة في موعدها، وتعني القيمة السالبة أنها متقدمة عن موعدها. يُرسل حدث delay بمجرد أن يصل التأخير إلى 5 دقائق.
• سمات الوقت: جميعها، بما في ذلك سمات arrival_* و _local، من نوع String وليست Date. بهذه الطريقة لا يُسقط الوقت الفارغ من الحدث، ويحتفظ الوقت المحلي بفارق التوقيت عن UTC الخاص بالمطار. للتصفية حسب التاريخ، استخدم flight_date و event_time.