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

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

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

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

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh تم إعداده في حسابك.
• للتكامل مع iOS:
  • منصة iOS مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام تهيئة المصادقة المستندة إلى الرمز كأبسط نهج.
  • قم بتعيين Gateway إلى Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
• للتكامل مع Android:
  • منصة Android مهيأة
  • رقم المشروع (المعروف أيضًا باسم Sender ID)، وملف google-services.json، واسم الحزمة من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• رمز تطبيق Pushwoosh الخاص بك ورمز Pushwoosh Device API من لوحة تحكم 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__",
        projectid: "__YOUR_FCM_SENDER_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.
• __YOUR_FCM_SENDER_ID__ هو رقم مشروع Firebase من Firebase Console.

ترتيب التهيئة مهم

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

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

قد يؤدي تغيير هذا الترتيب إلى المشكلات التالية:

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

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

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

3.1 القدرات (Capabilities)

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

في قسم 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__ إلى Pushwoosh Device API Token:

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 الخاص بك، أضف Pushwoosh Device API Token داخل وسم <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)

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

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)

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

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()
    });
  }
}

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

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