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

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

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

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

المتطلبات

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

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

1. تثبيت الإضافة (plugin)

ثبّت إضافة Pushwoosh Expo باستخدام Expo CLI

expo install pushwoosh-expo-plugin

ثبّت Pushwoosh React Native SDK

npm install pushwoosh-react-native-plugin --save

2. تعيين خصائص الإضافة

أضف الإضافة في بداية مصفوفة الإضافات (plugin array) مع الخصائص اللازمة:

app.json/app.config.js

{
  "expo": {
    "plugins": [
      [
        "pushwoosh-expo-plugin",
        {
          "mode": "development",
          "ios": {
            "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
          },
          "android": {
            "apiToken": "__YOUR_DEVICE_API_TOKEN__"
          }
        }
      ]
    ]
  }
}

حيث:

• يُستخدم mode لتهيئة استحقاق بيئة APNs. القيم المتاحة هي “Development” أو “production”.
• PW_API_TOKEN و apiToken هو Pushwoosh Device API Token الخاص بك.

3. تهيئة Pushwoosh

في المكون الجذري (root component) لتطبيقك:

• استورد إضافة pushwoosh-react-native-plugin.
• هيّئ Pushwoosh SDK.
• استدعِ register() في منطق التهيئة الخاص بك للتسجيل في الإشعارات الفورية.

index.tsx

import Pushwoosh from 'pushwoosh-react-native-plugin';

Pushwoosh.init({
    "pw_appid": "__YOUR_APP_ID__"
});

Pushwoosh.register();

حيث:

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

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

أضف ملف تهيئة Firebase:

1. انسخ ملف google-services.json الخاص بك إلى الدليل الجذري للمشروع.
2. اضبط خاصية googleServicesFile على مسار ملف google-services.json الخاص بك وحدد خاصية package:

app.json/app.config.js

  "expo": {
    "name": "sample",
  "android": {
    "package": "com.pushwoosh.sample",
    "googleServicesFile": "./google-services.json"
  },
  "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
        "ios": {
          "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
        },
        "android": {
          "apiToken": "__YOUR_DEVICE_API_TOKEN__"
        }
      }
    ]
  ]
}

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

اضبط خاصية bundleIdentifier على كائن ios:

app.json/app.config.js

  "expo": {
    "name": "sample",
    "ios": {
      "bundleIdentifier": "com.pushwoosh.sample"
    },
    "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
        "ios": {
          "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
        },
        "android": {
          "apiToken": "__YOUR_DEVICE_API_TOKEN__"
        }
      }
    ]
  ]
}

6. البناء المسبق للتطبيق (Prebuild)

أنشئ الكود الأصلي وهيّئ الاعتماديات لكل منصة عن طريق تشغيل prebuild:

npx expo prebuild

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

1. ابنِ وشغّل المشروع:

Android

npx expo run:android

iOS

npx expo run:ios

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

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

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

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

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

• يتم إطلاق حدث onPushReceived عند استلام إشعار فوري
• يتم إطلاق حدث onPushAccepted عندما يفتح المستخدم إشعارًا

يجب عليك إعداد مستمعي الأحداث هؤلاء مباشرة بعد تهيئة الـ SDK عند بدء تشغيل التطبيق:

import { DeviceEventEmitter } from 'react-native';
import Pushwoosh from 'pushwoosh-react-native-plugin';

class PushwooshNotificationHandler {
  setupPushListeners(): void {

    DeviceEventEmitter.addListener("pushReceived", (e) => {
      console.warn("Push received: " + JSON.stringify(e));
    });

    DeviceEventEmitter.addListener("pushOpened", (e) => {
      console.warn("Push opened:" + JSON.stringify(e));
    });

  }
}

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

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

import Pushwoosh from 'pushwoosh-react-native-plugin';

class Registration {
  afterUserLogin(user: User): void {

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

    // Set user email
    Pushwoosh.setEmails(user.getEmailList());

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

العلامات (Tags)

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

import Pushwoosh from 'pushwoosh-react-native-plugin';

class UpdateUser {
  afterUserUpdateProfile(user: User): void {

    // 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) هي إجراءات أو وقائع محددة للمستخدم داخل التطبيق يمكن تتبعها لتحليل السلوك وتشغيل الرسائل أو الإجراءات المقابلة

import Pushwoosh from 'pushwoosh-react-native-plugin';

class Registration {

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

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

تتبع تسليم الرسائل لـ iOS

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

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

خصائص الإضافة الإضافية

الخاصية	الافتراضي	الوصف
خصائص iOS
Pushwoosh_LOG_LEVEL	INFO	مستوى السجل (Log level) لـ iOS. القيم الممكنة: NONE, ERROR, WARN, INFO, DEBUG, NOISE
خصائص Android
logLevel	INFO	مستوى السجل (Log level) لـ Android. واحد من: NONE, ERROR, WARN, INFO, DEBUG, NOISE
multiNotificationMode	true	يمكن تغييره إلى false في حال كنت ترغب في عرض آخر إشعار للمستخدم فقط
icon	-	مسار أيقونة إشعار مخصصة لـ Android

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

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

خطأ تسجيل FCM: فشل في استرداد الرمز المميز. هل تم تكوين firebase بشكل صحيح؟

تأكد من أن خاصية googleServicesFile الخاصة بـ Firebase مُعدة في ملف تكوين Expo وأن ملف google-services.json مضاف إلى الدليل الجذري لمشروعك:

app.json/app.config.js

"expo": {
  "name": "sample",
  "android": {
    "package": "com.pushwoosh.sample",
    "googleServicesFile": "./google-services.json"
  },
  "plugins": [
    [
      "pushwoosh-expo-plugin",
      {
        "mode": "development",
        "ios": {
          "PW_API_TOKEN": "__YOUR_DEVICE_API_TOKEN__"
        },
        "android": {
          "apiToken": "__YOUR_DEVICE_API_TOKEN__"
        }
      }
    ]
  ]
}

TypeError: Cannot read property ‘init’ of null

قد تواجه هذا الخطأ عند محاولة تشغيل التطبيق على جهاز. لحل المشكلة، تأكد من أنك قد أكملت خطوة البناء المسبق (prebuild). فهي تنشئ الكود الأصلي وتهيئ الاعتماديات لكل منصة.

npx expo prebuild