دليل التكامل الأساسي لـ Cordova SDK

يحتوي هذا القسم على معلومات حول كيفية دمج Pushwoosh Cordova SDK في تطبيقك.

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

لدمج Pushwoosh Cordova SDK في تطبيقك، ستحتاج إلى ما يلي:

Requirements

• حساب Pushwoosh.
• مشروع Pushwoosh تم إعداده في حسابك.
• لتكامل iOS:
  • منصة iOS مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام تكوين المصادقة المستندة إلى الرمز كأبسط طريقة.
  • اضبط البوابة (Gateway) على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
• لتكامل Android:
  • منصة Android مهيأة
  • ملف google-services.json واسم الحزمة (package name) من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• رمز تطبيق Pushwoosh الخاص بك ورمز API للجهاز من Pushwoosh من لوحة تحكم Pushwoosh لتطبيقك.

خطوات التكامل

1. إضافة اعتمادية Pushwoosh Cordova SDK

أضف اعتمادية Pushwoosh Cordova SDK إلى مشروعك:

cordova plugin add pushwoosh-cordova-plugin

2. تهيئة Cordova SDK

في المكون الجذري لملف index.js الخاص بك، أضف الكود التالي داخل معالج حدث deviceready. اتبع الخطوات بالترتيب الدقيق:

index.js

document.addEventListener('deviceready', function() {
    var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

    // 1. Register notification callbacks before initialization
    document.addEventListener('push-receive', function(event) {
        var notification = event.notification;
        console.log("Push received: " + JSON.stringify(notification));
    });

    document.addEventListener('push-notification', function(event) {
        var notification = event.notification;
        console.log("Push opened: " + JSON.stringify(notification));
    });

    // 2. Initialize Pushwoosh
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__"
    });

    // 3. Register the device to receive push notifications
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // Handle successful registration
        },
        function(status) {
            // Handle registration error
        }
    );
}, false);

حيث:

• __YOUR_APP_ID__ هو رمز التطبيق من لوحة تحكم Pushwoosh.

Initialization order matters

يجب أن يتبع تسلسل التهيئة الترتيب الدقيق الموضح أعلاه:

1. تسجيل مستمعي الأحداث أولاً (push-receive, push-notification)
2. ثم استدعاء onDeviceReady()
3. ثم استدعاء registerDevice()

تغيير هذا الترتيب يمكن أن يسبب المشاكل التالية:

• مستمعو الأحداث المسجلون بعد onDeviceReady(): إذا تم تشغيل التطبيق عن طريق النقر على إشعار فوري (تشغيل بارد)، فإن onDeviceReady() يسلم حمولة إشعار التشغيل على الفور إلى JavaScript. إذا لم تكن مستمعاتك مسجلة بعد في تلك اللحظة، فسيتم فقدان إشعار التشغيل دون أي طريقة لاستعادته.
• استدعاء registerDevice() قبل onDeviceReady(): قد لا يكون SDK الأصلي مهيأً بشكل صحيح بمعرف التطبيق الخاص بك بعد، مما قد يؤدي إلى فشل تسجيل الجهاز بصمت أو إرجاع خطأ.
• مستمعو الأحداث المسجلون بعد registerDevice(): أي إشعار فوري يصل ويتم معالجته قبل أن تكون مستمعاتك في مكانها سيتم إرساله كحدث DOM وسيتم تجاهله بصمت نظرًا لعدم وجود آلية إعادة تشغيل في المكون الإضافي.

لا يقوم المكون الإضافي بوضع الأحداث الفائتة في قائمة انتظار أو تخزينها مؤقتًا على جانب JavaScript. يتم تسليم أحداث DOM التي يتم إطلاقها بواسطة document.dispatchEvent() فقط إلى المستمعين المسجلين بالفعل في وقت الإرسال.

3. الإعداد الأصلي لـ iOS

3.1 القدرات

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

في قسم التوقيع والقدرات (Signing & Capabilities)، أضف القدرات التالية:

• Push Notifications
• Background Modes. بعد إضافة هذه القدرة، حدد مربع Remote notifications.

إذا كنت تنوي استخدام الإشعارات الحساسة للوقت (Time Sensitive Notifications) (iOS 15+)، فأضف أيضًا قدرة Time Sensitive Notifications.

3.2 Info.plist

في ملف Runner/Info.plist الخاص بك، اضبط مفتاح __PUSHWOOSH_DEVICE_API_TOKEN__ على رمز API للجهاز من Pushwoosh:

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 تتبع تسليم الرسائل

يجب عليك إضافة هدف ملحق خدمة الإشعارات (Notification Service Extension) إلى مشروعك. هذا ضروري لتتبع التسليم بدقة وميزات مثل الوسائط الغنية (Rich Media) على iOS.

اتبع خطوات الدليل الأصلي لإضافة هدف الملحق وكود Pushwoosh اللازم بداخله.

4. الإعداد الأصلي لـ Android

4.1 تثبيت الاعتماديات

تأكد من إضافة الاعتماديات والمكونات الإضافية المطلوبة إلى نصوص Gradle الخاصة بك:

أضف مكون Google Services Gradle الإضافي إلى اعتماديات build.gradle على مستوى المشروع:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

طبق المكون الإضافي في ملف build.gradle على مستوى التطبيق:

app/build.gradle

apply plugin: 'com.google.gms.google-services'

4.2 إضافة ملف تكوين Firebase

ضع ملف google-services.json في مجلد android/app في دليل مشروعك.

4.3 إضافة بيانات Pushwoosh الوصفية

في ملف main/AndroidManifest.xml الخاص بك، أضف رمز API للجهاز من Pushwoosh داخل وسم <application>:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

مهم: تأكد من منح الرمز وصولاً إلى التطبيق الصحيح في لوحة تحكم Pushwoosh. اعرف المزيد

5. تشغيل المشروع

1. قم ببناء وتشغيل المشروع.
2. اذهب إلى لوحة تحكم Pushwoosh وأرسل إشعارًا فوريًا.
3. يجب أن ترى الإشعار في التطبيق.

التكامل الممتد

في هذه المرحلة، لقد قمت بالفعل بدمج SDK ويمكنك إرسال واستقبال الإشعارات الفورية. الآن، دعنا نستكشف الوظائف الأساسية

مستمعو أحداث الإشعارات الفورية

في Pushwoosh SDK، يوجد مستمعان للأحداث، مصممان للتعامل مع الإشعارات الفورية:

• يتم تشغيل حدث push-receive عند استلام إشعار فوري بينما يكون التطبيق في المقدمة
• يتم تشغيل حدث push-notification عندما يفتح المستخدم إشعارًا

يجب تسجيل مستمعي الأحداث هؤلاء قبل استدعاء onDeviceReady()، كما هو موضح في خطوة التهيئة أعلاه. يمكنك تخصيص منطق المعالج ليناسب احتياجاتك:

index.js

// Register before onDeviceReady()
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // Add your custom logic here
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // Add your custom logic here (e.g., navigate to a specific screen)
});

تكوين المستخدم

من خلال التركيز على سلوك المستخدم الفردي وتفضيلاته، يمكنك تقديم محتوى مخصص، مما يؤدي إلى زيادة رضا المستخدم وولائه

class Registration {
  afterUserLogin(user) {

    // Set user ID
    pushwoosh.setUserId(user.getId());

    // Setting additional user information as tags for Pushwoosh
    pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

العلامات (Tags)

العلامات (Tags) هي أزواج من المفاتيح والقيم يتم تعيينها للمستخدمين أو الأجهزة، مما يسمح بالتقسيم بناءً على سمات مثل التفضيلات أو السلوك، مما يتيح المراسلة المستهدفة.

class UpdateUser {
  afterUserUpdateProfile(user) {

    // Set list of favorite categories
    pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Set payment information
    pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

الأحداث (Events)

الأحداث (Events) هي إجراءات أو وقائع محددة للمستخدم داخل التطبيق يمكن تتبعها لتحليل السلوك وتشغيل الرسائل أو الإجراءات المقابلة

class Registration {

  // Track login event
  afterUserLogin(user) {
    pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Track purchase event
  afterUserPurchase(product) {
    pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

استكشاف الأخطاء وإصلاحها

إذا واجهت أي مشاكل أثناء عملية التكامل، يرجى الرجوع إلى قسم الدعم والمجتمع.