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

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

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

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

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh تم إعداده في حسابك.
• للتكامل مع iOS:
  • منصة iOS مكونة لإرسال الإشعارات الفورية. نوصي باستخدام تكوين المصادقة المستندة إلى الرمز المميز كأبسط نهج.
  • اضبط البوابة (Gateway) على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
• للتكامل مع Android:
  • منصة Android مكونة
  • ملف google-services.json و package name من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• Pushwoosh Application Code الخاص بك و رمز 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__"
    });

    // 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.

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

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

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

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

• مستمعو الأحداث المسجلون بعد onDeviceReady(): إذا تم تشغيل التطبيق عن طريق النقر على إشعار فوري (بدء بارد)، فإن onDeviceReady() يسلم فورًا حمولة إشعار التشغيل إلى JavaScript. إذا لم تكن مستمعاتك مسجلة بعد في تلك المرحلة، فإن إشعار التشغيل يُفقد دون أي طريقة لاستعادته.
• registerDevice() تم استدعاؤه قبل onDeviceReady(): قد لا يكون SDK الأصلي مكونًا بشكل صحيح مع App 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:

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 داخل وسم <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()
    });
  }
}

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

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