Outsystems

تثبيت إضافة Pushwoosh

ابدأ بتثبيت إضافة Pushwoosh من OutSystems Forge. أسرع طريقة للقيام بذلك هي الانتقال إلى علامة تبويب OutSystems في بيئة التطوير الخاصة بك وتثبيتها من هناك.

إعداد Pushwoosh

ستحتاج إلى إعداد Pushwoosh لكل منصة من المنصات التي ستدعمها. بمجرد الانتهاء من الإعداد، ستحصل على رمز تطبيق (Application Code) من Pushwoosh سيتم استخدامه مع إضافتك.

لنظام iOS

تعرف على كيفية إعداد Pushwoosh لنظام iOS.

لنظام Android

تعرف على كيفية إعداد Pushwoosh لنظام Android.

إضافة إضافة Pushwoosh إلى تطبيقك

1. في تطبيقك، استخدم “Manage Dependencies…” لإضافة مرجع إلى إضافة Pushwoosh.

2. أضف كتلة “PushwooshNotifications” إلى:

   • كتلة “Layout” إذا كان تطبيقك لا يتطلب تسجيل الدخول
   • كتلة “LayoutBlank” إذا كان تطبيقك يتطلب تسجيل الدخول

   عند إضافة كتلة “PushwooshNotifications”، تجنب إضافتها داخل العناصر النائبة (placeholders)، لأن بعضها متاح فقط في وقت التصميم، وفي وقت التشغيل، لن يعمل Pushwoosh.

3. قم بتعيين المعلمات التالية في PushwooshNotifications:

   • PushwooshApplicationCode: رمز Pushwoosh الذي حصلت عليه بعد إنشاء التطبيق في Pushwoosh.
   • FCMSenderId: رقم التعريف الذي حصلت عليه أثناء إعداد Android. يمكنك ترك هذا الحقل فارغًا إذا كان تطبيقك متاحًا فقط لنظام iOS.
   • NotificationReceivedEvent (اختياري): حدث يتم استدعاؤه عند استلام إشعار بينما يكون التطبيق في حالة الواجهة الأمامية.
   • NotificationOpenedEvent (اختياري): حدث يتم استدعاؤه عندما ينقر المستخدم على إشعار على جهازه.

إذا كنت تستخدم إضافة Pushwoosh في تطبيق Android الخاص بك، فقم بما يلي:

1. احصل على google-services.json من Firebase. يجب أن يتطابق اسم الحزمة (package name) من خدمات Google مع معرّف التطبيق (app identifier) لتطبيق OutSystems الذي يتم بناؤه.
2. أنشئ ملف zip يحتوي على google-services.json في الجذر.
3. قم بتحميل ملف “google-services.zip” من الخطوة السابقة إلى تطبيق OutSystems الخاص بك وتأكد من:
   • تعيين “Name” إلى “google-services.zip”
   • تعيين “Deploy to Target Directory” إلى “google-services”

تعيين رمز التطبيق في وقت البناء (موصى به)

بدءًا من إصدار مكون Pushwoosh Plugin 4.7.0 (للتحديث: قم بتثبيت الإصدار الأحدث من Forge، وقم بتحديث التبعية في Manage Dependencies، وقم بإنشاء بنية أصلية جديدة)، يمكن كتابة رمز التطبيق (Application Code) ورمز Device API في البنية الأصلية نفسها. أضفها كتفضيلات إلى خاصية Extensibility Configurations في تطبيقك:

{
  "preferences": {
    "global": [
      { "name": "PW_APPID", "value": "XXXXX-XXXXX" },
      { "name": "PW_API_TOKEN", "value": "your Device API token" }
    ]
  }
}

مع وجود هذا الإعداد، يتم تكوين SDK قبل تشغيل أي JavaScript، لذلك يتم التعامل مع الإشعارات التي يتم تسليمها أثناء عدم تشغيل التطبيق بشكل صحيح ولا يتم فقدان إحصائيات الدفع. أسماء التفضيلات حساسة لحالة الأحرف — اكتبها تمامًا كما هو موضح. PW_API_TOKEN اختياري؛ يمكن أيضًا تعيين الرمز في وقت التشغيل باستخدام إجراء العميل SetApiToken.

يستمر تمرير رمز التطبيق (Application Code) عبر كتلة PushwooshNotifications في العمل؛ عند تعيين كليهما، تكون الأسبقية للقيمة المعينة في وقت التشغيل.

تسجيل الجهاز

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

أضف الكود لتسجيل الجهاز بعد إجراء “DoLogin”. يجب أن يبدو شيئًا كهذا:

إذا كان تطبيقك لا يتطلب تسجيل الدخول، يمكنك إضافة هذا الكود إلى حدث OnInitializeOver في كتلة PushwooshNotifications.

في معالج الأحداث هذا، استدعِ إجراء RegisterDevice.

إذا كنت تقوم بإنشاء تطبيق جوال لنظام iOS باستخدام شهادة مطور، فستحتاج إلى إضافة تفضيل إلى خاصية Extensibility Configurations في وحدة OutSystems الخاصة بك:

{
  "preferences": {
    "global": [
      {
        "name": "aps-environment",
        "value": "development"
      }
    ]
  }
}

سيتم إضافة هذا التفضيل إلى ملف الاستحقاقات (entitlements) الخاص بك (تعرف على المزيد حول الاستحقاقات في وثائق مطوري Apple).

إذا كنت تقوم بإنشاء تطبيق جوال لنظام iOS باستخدام شهادة إنتاج، فلن تحتاج إلى تحديد أي تفضيل، لأن القيمة الافتراضية لتفضيل aps-environment في OutSystems هي production.

تطبيقك الآن جاهز لاستقبال إشعارات الدفع. قم بإعداد وإنشاء تطبيق الجوال الخاص بك وقم بتثبيته على جهازك. في هذه المرحلة، يمكنك استخدام واجهة Pushwoosh لإرسال إشعارات إلى تطبيقك والتأكد من أن كل شيء تم إعداده بشكل صحيح. لاحظ أنك لن ترى إشعارًا إذا كان التطبيق قيد التشغيل. بدلاً من ذلك، يتم إطلاق الحدث NotificationReceivedEvent على الفور.

إرسال الإشعارات

لإرسال الإشعارات، تحتاج إلى رمز وصول API من Pushwoosh. أنشئ واحدًا عن طريق الوصول إلى لوحة تحكم Pushwoosh، انتقل إلى “API Access”، وانقر على “Generate new access token”.

لإرسال إشعار إلى جميع الأجهزة، استخدم إجراء SendPushNotificationToAll.

يأخذ هذا الإجراء المعلمات التالية:

• PushwooshApplicationCode: رمز Pushwoosh الذي حصلت عليه بعد إنشاء التطبيق في Pushwoosh.
• ApiAccessToken: رمز وصول Pushwoosh API الذي تم الحصول عليه سابقًا.
• Message: نص الرسالة الذي ترغب في إرساله.
• Badge: رقم يتم عرضه على أيقونة تطبيق iOS.
• Deeplink: رابط عميق (deep link) لإرساله مع الإشعار. تعلم كيفية تحديد الروابط العميقة.
• InboxDays (اختياري، منذ الإصدار 4.7.0): عدد الأيام التي يتم فيها الاحتفاظ بالرسالة في صندوق الوارد (Inbox) الخاص بالمستخدم، بحد أقصى 30. بدونه (وبدون InboxDate) لا يتم حفظ الإشعار في صندوق الوارد.
• InboxDate (اختياري، منذ الإصدار 4.7.0): التاريخ الذي يتم فيه الاحتفاظ بالرسالة في صندوق الوارد الخاص بالمستخدم. بديل لـ InboxDays.
• InboxImage (اختياري، منذ الإصدار 4.7.0): عنوان URL لصورة مخصصة تظهر بجوار الرسالة في صندوق الوارد.

يوجد إجراءان خادمان شقيقان يأخذان نفس المعلمات: SendPushNotificationToToken يرسل إلى جهاز واحد محدد برمز الدفع الخاص به، و SendPushNotificationToUserId يرسل إلى جميع الأجهزة المسجلة تحت معرف مستخدم (User ID) معين (يتم تعيينه باستخدام إجراء العميل SetUserId).

على سبيل المثال، إذا استخدمت هذا الإجراء لإرسال رسالة “Hello from OutSystems” إلى تطبيق يسمى “PushTest”، فسيظهر ما يلي في نظام iOS:

معلومات إضافية

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

شاركنا ملاحظاتك

تساعدنا ملاحظاتك في إنشاء تجربة أفضل، لذلك نود أن نسمع منك إذا واجهت أي مشاكل أثناء عملية دمج SDK. إذا واجهت أي صعوبات، فلا تتردد في مشاركة أفكارك معنا عبر هذا النموذج.