Live Activity

Live Activity هي بطاقة تُحدَّث في الوقت الفعلي حتى يرى المستخدم التقدم دون فتح التطبيق (حالة الرحلة الجوية، التوصيل، رحلة التنقل، وما شابه). في iOS، هي بطاقة صغيرة على شاشة القفل وDynamic Island. في Android 16 والإصدارات الأحدث، هي النوع نفسه من البطاقات معروضًا كإشعار مستمر مع شريط تقدم.

استخدم عنصر Live Activity في Journey لبدء تلك البطاقة أو تحديثها أو إنهائها، على iOS أو Android أو كليهما.

يقوم كل عنصر بإجراء واحد:

• Start: إنشاء البطاقة.
• Update: تغيير بطاقة موجودة.
• End: إغلاق البطاقة.

لتغيير أو إغلاق نفس البطاقة لاحقًا، أضف عنصر Live Activity آخر ووجّهه مرة أخرى إلى العنصر الذي أنشأ البطاقة باستخدام Card created by.

أمثلة على حالات الاستخدام

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

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

نصيحة

للاطلاع على Journey كاملة، راجع كيفية عرض حالة الرحلة الجوية على شاشة القفل وكيفية عرض تقدم التوصيل على شاشة القفل.

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

قبل إعداد هذا العنصر، تحقق مما تحتاجه كل منصة.

لبطاقة iOS:

• دعم iOS Live Activity: يجب أن يدعم تطبيقك Live Activities. راجع دليل Live Activities الخاص بـ iOS SDK.
• مخطط widget منشور: اطلب من فريق التطوير لديك نشر المخطط المطابق لنوع Live Activity في التطبيق ضمن Applications → Configure → Live Activity schemas. يمكنهم أيضًا النشر عبر API. لمعرفة ما ينتمي إلى المخطط، راجع كتابة مخطط.
• Widget في القائمة: بعد نشر المخطط، حدده ضمن Widget في هذا العنصر. إذا كانت قائمة Widget فارغة، فإن المخطط لم يُنشر بعد.

لإشعار Android:

• دعم Android Live Updates: يحتاج تطبيقك إلى SDK 6.11+ ووحدة pushwoosh-liveupdates. لا حاجة إلى مخطط لـ Android. اطلب من مطور Android لديك التأكد من أن الوحدة مضمنة في البناء.

إعداد العنصر

1. اسحب عنصر Live Activity إلى لوحة العمل (canvas).

   

2. انقر نقرًا مزدوجًا على العنصر لفتح إعداداته.

3. أدخل اسمًا في Step name.

4. في Action، اختر أحد الخيارات التالية:

   • Start: إنشاء بطاقة Live Activity.
   • Update: تغيير محتوى بطاقة موجودة.
   • End: إغلاق البطاقة.

5. ضمن Platforms، شغّل iOS Live Activity أو Android Live Updates أو كليهما. يجب أن تبقى منصة واحدة على الأقل مفعّلة، لذا لا يمكنك إيقاف آخر منصة. في Update وEnd، يعرض Platforms المنصات من عنصر Start المرتبط ويكون للقراءة فقط.

   

6. في Start فقط، اضبط مفتاح البطاقة حتى تتمكن خطوات Update وEnd اللاحقة من العثور على هذه البطاقة:

   • في Card key: event، حدد الحدث الذي يحدد البطاقة (مثل حدث دخول Journey).
   • في Card key: attribute، حدد السمة التي تجعل المفتاح فريدًا لكل مسافر. هذا مطلوب بمجرد ضبط Card key: event. تركه بدون ضبط يجعل اختيار الحدث بلا تأثير، تمامًا كترك كلا الحقلين فارغين: بطاقة واحدة لكل مسافر، يُشار إليها عبر معرف المستخدم الافتراضي.

   

ربط Update وEnd بالبطاقة الصحيحة

عندما يكون Action هو Update أو End، استخدم Card created by للإشارة إلى عنصر Start الدقيق الذي أنشأ هذه البطاقة. وإلا فلن يصل Update أو End إليها.

1. في Card created by، حدد Step name لعنصر Start ذاك (على سبيل المثال Order card start).

بعد اختيار Card created by، يعرض Card key (from the start element) قيم Card key: event وCard key: attribute من ذلك Start. وهو للقراءة فقط ويؤكد إلى أي بطاقة يشير هذا العنصر.

ملاحظة

مثال: Start يُسمى Order card start. في Update وEnd، اختر Order card start في Card created by. تقوم كلتا الخطوتين بعد ذلك بتغيير أو إغلاق نفس بطاقة الطلب.

اختيار لغة البطاقة

ينطبق Card language على كل من بطاقة iOS وإشعار Android.

اضبط Card language على default أو رمز لغة محدد. المحتوى ضمن default هو الاحتياطي لأي لغة لا تملأها بشكل منفصل.

إعداد بطاقة iOS

تخطَّ هذا القسم إذا كان Android Live Updates وحده مفعّلًا.

اختيار الـ widget وإصدار المخطط

1. في Widget، حدد نوع Live Activity المنشور لهذه البطاقة. تأتي حقول المحتوى أدناه من هذا الاختيار. في Update أو End، يكون Widget للقراءة فقط، موروثًا من عنصر Card created by.

2. في Schema version، حدد أي إصدار منشور من مخطط ذلك الـ widget سيُستخدم. تأتي حقول Card content من هذا الإصدار. في Update وEnd، يبقى Schema version قابلاً للاختيار: يمكنك اختيار إصدار منشور مختلف من نفس الـ widget الموروث عن الإصدار الذي استخدمه Start المرتبط.

   

تعيين السمات الثابتة للبطاقة (Start فقط)

في Start، ضمن Card attributes، أضف الحقول التي تظل ثابتة طوال عمر البطاقة، تُضبط مرة واحدة ولا تتغير مرة أخرى، مثل رقم رحلة جوية أو معرف طلب. تختلف هذه عن حقول Card content أدناه. يمكن أن تتغير تلك القيم عند Update.

اسأل مطور iOS لديك عن قائمة Field name الدقيقة. تظل هذه الأسماء ثابتة طوال عمر البطاقة (نوع ActivityAttributes الخاص بالتطبيق). لا تستخدم أسماء Card content المتغيرة (ContentState الخاص بالتطبيق).

1. انقر على Add attribute.
2. اضبط Field name وValue لكل سمة تحتاجها.

لا يضبط Update وEnd أي سمات. يبقى كل ما ضبطه Start لهذه البطاقة ثابتًا.

تنبيه

تُرسل سمات البطاقة تمامًا كما يتوقعها نوع ActivityAttributes الخاص بتطبيقك، حقلاً بحقل. أخطئ في اسم، أو اتركها فارغة، ويرفض مُفكك التشفير في الجهاز الحمولة بأكملها. في اختبار حقيقي واحد، فتح Start يحتوي على flightNumber البطاقة، بينما سلّم Start بدون سمات المغلف فقط، دون أي شيء لعرضه على شاشة القفل.

تعبئة محتوى البطاقة

ضمن Card content، اكتب قيمة حرفية أو عنصرًا نائبًا للتخصيص في كل حقل. يظهر حقل واحد لكل خاصية في إصدار المخطط المحدد.

التعبئة المسبقة في Update وEnd

في Update أو End، إذا كانت Card content لـ Card language الحالية فارغة (بما في ذلك لغة أضفتها للتو)، يملأ Pushwoosh الحقول مسبقًا من عنصر Start المرتبط عند فتح الإعدادات:

• نفس لغة Start، إذا كان لتلك اللغة محتوى.
• وإلا محتوى default الخاص بـ Start.
• إذا لم يكن لدى Start أي منهما، اترك الحقول فارغة واملأها بنفسك.

تظل القيم المعبأة مسبقًا قابلة للتحرير. انقر على Apply فقط عندما تريد الاحتفاظ بالتعديلات. فتح العنصر وحده لا يغيّر Journey قيد التشغيل.

الحقول التي تتركها فارغة في Update أو End لا تُرسل. ما تعرضه البطاقة بعد ذلك في تلك الحقول يعتمد على تطبيقك: قد يحتفظ بالقيمة السابقة، أو يمسحها، أو يفعل شيئًا آخر. اسأل فريق التطوير لديك عن كيفية تعامل تطبيقك مع ذلك.

في End، Card content اختياري. يصبح الحقل الذي تملؤه آخر قيمة تُعرض قبل إغلاق البطاقة.

ضبط أولوية التسليم والتوقيت

1. في Delivery priority، اختر متى يجب على iOS تسليم هذا التحديث:

   • Immediate: يُسلّم iOS فورًا ويمكن أن يوقظ الهاتف (ويشغّل الصوت، إذا حددت واحدًا).
   • Quiet: قد يُسلّم iOS لاحقًا مع تحديثات أخرى ولا يوقظ الهاتف فورًا.
   • Default (batched): يستخدم iOS تسليمه المجمّع الافتراضي الخاص به ولا يوقظ الهاتف فورًا.

2. في Sound، حدد صوتًا من القائمة. يضيف فريق التطوير لديك ملفات صوت إلى حزمة تطبيق iOS. راجع صوت push مخصص. يُشغَّل الصوت فقط مع Alert title أو Alert text، مثل الشعار تمامًا.

3. اعتمادًا على Action الذي حددته لهذا العنصر (Start أو Update أو End)، املأ أحد التالي:

   • Start أو Update: اضبط Stale after, min على عدد الدقائق التي يجب أن تبدو فيها البيانات على البطاقة حديثة. عند انتهاء ذلك الوقت، يعتّم iOS الأرقام باعتبارها قديمة. تبقى البطاقة على شاشة القفل. لإبقاء الأرقام تبدو حالية، أرسل Update آخر قبل انتهاء الوقت.
   • End: اضبط Dismiss after, min على المدة التي تبقى فيها البطاقة المغلقة على شاشة القفل قبل أن يزيلها iOS. اتركها عند 0 وستستمر البطاقة في عرض Card content الأخير حتى يزيلها iOS من تلقاء نفسه، خلال ما يصل إلى 4 ساعات.

4. اضبط اختياريًا Relevance score على رقم من 1 إلى 100. عندما يكون لدى شخص أكثر من Live Activity نشط واحد من تطبيقك في نفس الوقت، يعرض iOS صاحب التقييم الأعلى أولاً. اتركها عند 0 لعدم ضبط أفضلية. لا يرسل Pushwoosh تقييم 0 إلى Apple على الإطلاق. راجع أنشطة متعددة لكل جهاز للحصول على الصورة الكاملة.

تعبئة إشعار Android

املأ عنوان إشعار Android ونصه وشريط التقدم ووقت الترويسة. يظهر هذا القسم فقط عندما يكون Android Live Updates مفعّلًا. ويستخدم نفس Card language المستخدمة لبطاقة iOS.

1. اضبط Notification title لكل لغة تملؤها لـ Android. في Start وUpdate، لا يمكن تشغيل Journey حتى يكون لكل لغة من تلك اللغات عنوان. تُظهر اللغة التي ليس لها عنوان تذكيرًا في النموذج.

2. اضبط Notification text.

   

3. قم بإعداد شريط التقدم:

   • Progress: اكتب رقمًا أو عنصرًا نائبًا بالصيغة {name} (اختياريًا {name|format} أو {name|format|default}) للموضع الذي يجب أن يكون فيه الشريط، بنفس وحدات أطوال المقاطع.
   • Segments: انقر على Add segment لكل جزء ملون من الشريط، واضبط Color بصيغة hex (#RRGGBB أو #AARRGGBB) وLength لكل منها. مجموع أطوال المقاطع يساوي الشريط الكامل.
   • Animate the bar without a known end: شغّله لعرض شريط متحرك بدلاً من قيمة Progress.
   • Hide the progress bar: شغّله لعرض البطاقة بدون شريط.

   

4. اضبط وقت الترويسة:

   • Header time: اكتب طابعًا زمنيًا Unix بالثواني (وليس بالمللي ثانية)، أو عنصرًا نائبًا، للحظة التي يجب أن تعرضها ساعة ترويسة البطاقة. على سبيل المثال، 1735689600 تعني 2025-01-01 00:00 UTC. إذا تم ضبط هذا الحقل وHeader time after, min معًا، يُستخدم Header time.
   • Header time after, min: اضبط عدد الدقائق بعد الإرسال التي يجب أن يُعرض فيها وقت الترويسة.
   • Run the header time as a timer: شغّله لعرض Header time كساعة جارية بدلاً من قيمة ثابتة. يُظهر هذا الخيار Count down to the header time.
   • Count down to the header time: شغّله للعد التنازلي نحو Header time بدلاً من العد التصاعدي من وقت الإرسال.
   • Hide the header time: شغّله لعرض البطاقة بدون وقت الترويسة.

   

يمكن أن يحمل أي حقل أعلاه عنصرًا نائبًا، يُحل بنفس طريقة حقول Card content في iOS: من حدث Journey أو بالتخصيص باستخدام سمة حدث.

بعض أجهزة Android لن تعرض الإشعار

• Android 15 أو أقدم، أو تطبيق بدون وحدة pushwoosh-liveupdates: يظل Pushwoosh يرسل التحديث، لكن لا يظهر شيء على الجهاز، ولا يُعرض push عادي بدلاً منه.
• أجهزة Huawei وBaidu: لا تحصل على Android Live Updates. تذهب التحديثات فقط إلى الأجهزة المسجلة عبر Firebase Cloud Messaging (FCM).

يؤدي النقر على الإشعار إلى فتح التطبيق، تمامًا مثل push عادي.

ضبط شعار التنبيه

ينطبق هذا القسم فقط عندما يكون iOS Live Activity مفعّلًا. إذا كان Android Live Updates وحده مفعّلًا، تُخفى هذه الحقول ولا يُرسل شيء.

لجميع الإجراءات الثلاثة (Start وUpdate وEnd):

1. في Alert title، اضبط عنوان الشعار المعروض على شاشة القفل.
2. في Alert text، اضبط نص الشعار.

تنبيه

إذا كان كل من Alert title وAlert text فارغين، فإن البطاقة لا تزال تبدأ أو تُحدَّث أو تنتهي، لكن شاشة القفل لا تعرض أي شعار ولا تشغّل أي صوت. املأ واحدًا على الأقل من الاثنين عندما يجب أن يظهر هذا الإجراء على شاشة مقفلة.

اختيار الجهاز الذي يحصل على البطاقة

يُضبط التوجيه مرة واحدة، في Start. اترك كلا المفتاحين متوقفين لإرسال البطاقة إلى الجهاز الذي دخل منه المسافر إلى Journey. تشغيل أحد المفتاحين يوقف الآخر:

• Send to all devices of this user: الإرسال إلى كل جهاز مسجل تحت User ID لذلك المسافر، وليس فقط الجهاز الذي دخل منه.
• Send to the last active device only: الإرسال إلى الجهاز الوحيد الذي استخدمه User ID ذاك مؤخرًا، بدلاً من كل الأجهزة أو جهاز الدخول.

نصيحة

شغّل Send to the last active device only عندما قد يتابع نفس الشخص على iPhone مختلف عن الذي دخل منه إلى Journey.

في Update وEnd، تحقق من Delivery (from the start element). فهو يحدد وضع التوجيه من Start المرتبط. يمكن للتحديث الوصول فقط إلى نفس البطاقة، لذا فهو يُرسل بنفس الطريقة.

ملاحظة

يُقفل كلا المفتاحين بمجرد بدء تشغيل Journey، وكذلك في Start. لتغيير التوجيه بعد ذلك، أوقف Journey مؤقتًا أولًا.

تخصيص المحتوى

استخدم هذا عندما يجب أن تأخذ العناصر النائبة في Alert title أو Alert text أو Card content أو في حقول Android Notification title أو Notification text أو Progress أو Header time قيمًا من حدث Journey أو الدخول القائم على API بدلاً من علامات الجهاز.

1. ضمن Overwrite personalization، شغّل Personalise message with event attributes.
2. حدد مربع Overwrite placeholder بجانب كل عنصر نائب تريد إعادة تعيينه.
3. اربط ذلك العنصر النائب بسمة حدث.

حفظ العنصر

انقر على Apply لحفظ إعدادات العنصر. يحفظ Apply هذا العنصر في Journey. لا يؤكد ذلك أن البطاقة ظهرت على الجهاز. بعد تشغيل Journey، تحقق من Total entries وحالات الخروج في هذه الخطوة، وتحقق من البطاقة على iPhone اختباري، أو جهاز اختباري بنظام Android 16 أو أحدث، أو كليهما، حسب المنصات التي فعّلتها.

القيود

• إحصائيات العنصر: في هذه الخطوة، تحقق من Total entries، وصف Delivery (وضع التوجيه)، وحالات الخروج (No recipient for the card، Live Activity send failed). استخدم No recipient for the card لترى أن المراسلة لم تجد أي جهاز للمنصات المفعّلة في ذلك الوضع، وليس أن الجهاز يفتقر إلى رمز Live Activity. لا تُبلغ هذه الخطوة عما إذا كان الجهاز قد عرض البطاقة أو ما إذا كان المستخدم قد فتحها.
• الصوت غير مضمون في كل تحديث: يحدّ iOS من معدل تنبيهات Live Activity من تلقاء نفسه. يمكن أن يشغّل تحديث متطابق صوتًا مرة ويصل بصمت في المرة التالية.
• العديد من إجراءات Start متتالية أثناء الاختبار: إذا أرسلت حوالي عشرة إجراءات Start لنفس الشخص في وقت قصير (على سبيل المثال أثناء اختبار Journey)، قد تتوقف Apple عن عرض بطاقات جديدة ولا تُرجع خطأً. في Journey، قد يظل الشخص يبدو مُسلَّمًا. اترك فاصلًا بين تشغيلات الاختبار.