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

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

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

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

المتطلبات

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

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

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

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

expo install pushwoosh-expo-plugin

قم بتثبيت Pushwoosh React Native SDK

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

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

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

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

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

• قم باستيراد إضافة 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__ هو رمز التطبيق من لوحة تحكم 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. البناء المسبق للتطبيق

قم بإنشاء الكود الأصلي وتكوين التبعيات لكل منصة عن طريق تشغيل البناء المسبق:

npx expo prebuild

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

1. قم ببناء وتشغيل المشروع:

Android

npx expo run:android

iOS

npx expo run:ios

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

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

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

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

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

• يتم تشغيل حدث 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.

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

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

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

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

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

FCM registration error: Failed to retrieve token. Is firebase configured correctly?

تأكد من أن خاصية 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

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

npx expo prebuild