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

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

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

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

<Aside type="note" title="المتطلبات">
 - [حساب Pushwoosh](https://sso.pushwoosh.com/login).
 - [مشروع Pushwoosh](/ar/product/first-steps/start-with-your-project/create-your-project) تم إعداده في حسابك.
 - **للتكامل مع iOS:**
    - منصة iOS مكونة لإرسال الإشعارات الفورية. نوصي باستخدام [تكوين المصادقة المستندة إلى الرمز](/ar/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/) كأبسط نهج.
    - اضبط البوابة (Gateway) على `Sandbox` لإرسال الإشعارات إلى جهاز محاكاة.
 - **للتكامل مع Android:**
    - [منصة Android مكونة](/ar/developer/first-steps/connect-messaging-services/android-configuration/android-firebase-configuration)
    - ملف `google-services.json` و `package name` من مشروع Firebase الخاص بك.
    - مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع [دليل إعداد Firebase](https://firebase.google.com/docs/android/setup#manually_add_firebase) إذا لزم الأمر.
 - `Pushwoosh Application Code` و [Pushwoosh Device API Token](/ar/developer/api-reference/api-access-token/#device-api-token) الخاص بك من لوحة تحكم Pushwoosh لتطبيقك.
</Aside>

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

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

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

```bash
expo install pushwoosh-expo-plugin
```

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

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

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

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

```json title="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](/ar/developer/api-reference/api-access-token/#device-api-token) الخاص بك.

### 3. تهيئة Pushwoosh

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

```javascript title="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`:

```json title="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`:

```json title="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. البناء المسبق للتطبيق
قم بإنشاء الكود الأصلي وتكوين التبعيات لكل منصة عن طريق تشغيل البناء المسبق:
```bash
npx expo prebuild
```

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

1. قم ببناء وتشغيل المشروع:
<Tabs>
<TabItem label="Android">
```bash
npx expo run:android
```
</TabItem>

<TabItem label="iOS">
```bash
npx expo run:ios
```
</TabItem>
</Tabs>

2. اذهب إلى لوحة تحكم Pushwoosh و [أرسل إشعارًا فوريًا](/ar/product/messaging-channels/push-notifications/send-push-notifications/one-time-push).
3. يجب أن ترى الإشعار في التطبيق.

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

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

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

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

- يتم تشغيل حدث `onPushReceived` عند استلام إشعار فوري.
- يتم تشغيل حدث `onPushAccepted` عندما يفتح المستخدم إشعارًا.

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

```typescript
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));
    });

  }
}
```

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

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

```typescript
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) هي أزواج من المفاتيح والقيم يتم تعيينها للمستخدمين أو الأجهزة، مما يسمح بالتقسيم بناءً على سمات مثل التفضيلات أو السلوك، مما يتيح المراسلة المستهدفة.

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

```typescript
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.

اتبع [خطوات الدليل الأصلي](/ar/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#4-message-delivery-tracking) لإضافة هدف الامتداد وكود Pushwoosh اللازم بداخله.

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

| الخاصية <div style="width:180px"></div> | الافتراضي <div style="width:100px"></div> | الوصف |
|-----------------|---------|-------------|
| **خصائص 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 |

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

إذا واجهت أي مشاكل أثناء عملية التكامل، يرجى الرجوع إلى قسم [الدعم والمجتمع](/ar/developer/pushwoosh-sdk/support-and-community).

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

تأكد من أن خاصية `googleServicesFile` الخاصة بـ Firebase معدة في ملف تكوين Expo وأن ملف `google-services.json` مضاف إلى الدليل الجذري لمشروعك:
```json title="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

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

```bash
npx expo prebuild
```