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

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

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

لدمج Pushwoosh React Native 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 مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام [تكوين المصادقة المستندة إلى الرمز المميز (Token-Based Authentication)](/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 React Native SDK

أضف تبعية Pushwoosh React Native SDK إلى مشروعك:

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

### 2. تهيئة React Native SDK

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

```javascript title="index.js"
import Pushwoosh from 'pushwoosh-react-native-plugin';

AppRegistry.registerComponent(appName, () => App);

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

Pushwoosh.register();
```

حيث:
- `__YOUR_APP_ID__` هو رمز التطبيق من لوحة تحكم Pushwoosh.


### 3. الإعداد الأصلي لـ iOS

#### 3.1 القدرات (Capabilities)

لتمكين الإشعارات الفورية في مشروعك، تحتاج إلى إضافة قدرات معينة.

في قسم Signing & Capabilities، أضف القدرات التالية:
- `Push Notifications`
- `Background Modes`. بعد إضافة هذه القدرة، حدد مربع `Remote notifications`.

إذا كنت تنوي استخدام Time Sensitive Notifications (iOS 15+)، أضف أيضًا قدرة `Time Sensitive Notifications`.

#### 3.2 Info.plist

في ملف `Runner/Info.plist` الخاص بك، قم بتعيين مفتاح `__PUSHWOOSH_DEVICE_API_TOKEN__` إلى [Pushwoosh Device API Token](/ar/developer/api-reference/api-access-token/#device-api-token):
```swift title="info.plist"
<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>
```

#### 3.3 تتبع تسليم الرسائل

يجب عليك إضافة هدف 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 اللازم بداخله.

#### 3.4 تثبيت التبعيات لمشروع iOS React Native

لتثبيت التبعيات لمشروع iOS React Native، انتقل إلى مجلد ```ios``` في الطرفية وقم بتشغيل:

```bash
pod install --repo-update
```

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

#### 4.1 تثبيت التبعيات

تأكد من إضافة التبعيات والإضافات المطلوبة إلى نصوص Gradle البرمجية الخاصة بك:

أضف إضافة Google Services Gradle إلى تبعيات `build.gradle` على مستوى المشروع:

```groovy title="android/build.gradle"
buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}
```

طبق الإضافة في ملف `build.gradle` على مستوى التطبيق:

```groovy title="app/build.gradle"
apply plugin: 'com.google.gms.google-services'
```

#### 4.2 إضافة ملف تكوين Firebase

ضع ملف `google-services.json` في مجلد `android/app` في دليل مشروعك.

#### 4.3 إضافة بيانات Pushwoosh الوصفية

في ملف `main/AndroidManifest.xml` الخاص بك، أضف [Pushwoosh Device API Token](/ar/developer/api-reference/api-access-token/#device-api-token) داخل وسم `<application>`:

```xml title="AndroidManifest.xml"
<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />
```

> **هام:** تأكد من منح الرمز المميز حق الوصول إلى التطبيق الصحيح في لوحة تحكم Pushwoosh الخاصة بك. [اعرف المزيد](/ar/developer/api-reference/api-access-token/#edit-token)

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

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

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

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

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

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

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

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

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

class PushwooshNotificationHandler {
  setupPushListeners() {

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

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

  }
}
```

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

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

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

class Registration {
  afterUserLogin(user: User) {

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

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

    // Set user SMS number
    Pushwoosh.registerSMSNumber(user.getPhoneNumber());

    // Set user WhatsApp number
    Pushwoosh.registerWhatsappNumber(user.getWhatsAppNumber());

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

### العلامات (Tags)

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

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

class UpdateUser {
  afterUserUpdateProfile(user: User) {

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

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

class Registration {

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

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

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

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