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

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

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

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

المتطلبات

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

Pushwoosh.register();

حيث:

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

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 يوجد مستمعان للأحداث، مصممان للتعامل مع الإشعارات الفورية:

• يتم تشغيل حدث 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: فشل في استرداد الرمز المميز. هل تم تكوين 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