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

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

المتطلبات المسبقة

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

المتطلبات

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

Pushwoosh.register();

حيث:

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

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:

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 target إلى مشروعك. هذا ضروري لتتبع التسليم الدقيق وميزات مثل Rich Media على iOS.

اتبع خطوات الدليل الأصلي لإضافة extension target وكود 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: لا يمكن قراءة الخاصية ‘init’ من null

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

npx expo prebuild