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

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

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

لدمج Pushwoosh Flutter 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 Flutter SDK

أضف حزمة `pushwoosh_flutter` إلى ملف `pubspec.yaml` الخاص بك:

```yaml title="pubspec.yaml"
dependencies:
  flutter:
    sdk: flutter
  # استخدم أحدث إصدار من https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]
```
تحقق من [أحدث إصدار](https://pub.dev/packages/pushwoosh_flutter) على pub.dev.

بعد ذلك، قم بتشغيل الأمر التالي في الدليل الجذري لمشروعك لتثبيت الاعتمادية:

```bash
flutter pub get
```

تحقق مرة أخرى من أن الحزمة مثبتة بشكل صحيح:
```bash
flutter pub deps | grep pushwoosh_flutter

# مثال على المخرجات:
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11
```

### 2. تهيئة Flutter SDK

في المكون الجذري لملف `main.dart` الخاص بك:
- قم باستيراد حزمة `pushwoosh_flutter`.
- قم بتهيئة Pushwoosh SDK.
- استدعِ `registerForPushNotifications()` في منطق التهيئة الخاص بك للتسجيل في الإشعارات الفورية.

```dart title="main.dart"
import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

void main() async {
  runApp(const MyApp());
  Pushwoosh.initialize({
    "app_id": "__YOUR_APP_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}
```

حيث:
- `__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 اللازم بداخله.

للتأكد من أن Notification Service Extension مدمج بشكل صحيح في مشروع Flutter الخاص بك، تحتاج إلى استخدام تكوين Podfile التالي:

```ruby title="Podfile"
target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end
```

#### 3.4 تثبيت الاعتماديات لمشروع iOS Flutter

لتثبيت الاعتماديات لمشروع iOS Flutter، قم بتشغيل الأمر التالي:

```bash
flutter run
```

أو انتقل إلى مجلد `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 الوصفية (metadata)

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

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

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

```dart
import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class PushwooshNotificationHandler {
  void setupPushListeners(Pushwoosh pushwoosh) {

    pushwoosh.onPushReceived.listen((event) {
      print("Push received: ${event.pushwooshMessage.payload}");
    });

    pushwoosh.onPushAccepted.listen((event) {
      print("Push accepted: ${event.pushwooshMessage.payload}");
    });
    
  }
}
```

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

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

```dart
import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {
  void afterUserLogin(User user) {
  
    // تعيين معرف المستخدم
    Pushwoosh().setUserId(user.getId());
    
    // تعيين بريد المستخدم الإلكتروني
    Pushwoosh().setEmail(user.getEmail());

    // تسجيل رقم SMS
    // يجب أن تكون أرقام SMS و WhatsApp بتنسيق E.164 (على سبيل المثال، "+1234567890") وأن تكون صالحة
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // تسجيل رقم WhatsApp
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());
    
    // تعيين معلومات مستخدم إضافية كعلامات لـ Pushwoosh
    Pushwoosh().setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}
```

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

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

```dart
import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User user) {

    // تعيين قائمة الفئات المفضلة
    Pushwoosh().setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });
    
    // تعيين معلومات الدفع
    Pushwoosh().setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}
```

### الأحداث (Events)

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

```dart
import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

  // تتبع حدث تسجيل الدخول
  void afterUserLogin(User user) {
    Pushwoosh().postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  void afterUserPurchase(Product product) {

  // تتبع حدث الشراء
  Pushwoosh().postEvent("purchase", {
    "product_id": product.getId(),
    "product_name": product.getName(),
    "price": product.getPrice(),
    "quantity": product.getQuantity()
  });
 }
}
```

## استخدام ProGuard

<Aside type="note">
لاحظ أن أمر `flutter build apk` يقوم بإخفاء (obfuscates) الكود الخاص بك بشكل افتراضي.
</Aside>

وبالتالي، قد تحصل على هذا الاستثناء:

```java
java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension
```

هناك حلان في هذه الحالة:

1. استخدم الأمر `flutter build apk --no-shrink` لتجميع الكود الخاص بك بدون إخفاء.
2. أو يمكنك تمكين ProGuard يدويًا وإضافة القواعد اللازمة.

لتمكين ProGuard لمشروعك، أضف السلاسل التالية إلى ملف `build.gradle` الخاص بك:

```java title="build.gradle"
buildTypes {
        release {
            minifyEnabled true
            useProguard true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

            signingConfig signingConfigs.debug
        }
    }
```

بعد ذلك، أضف القواعد التالية إلى `android/app/proguard-rules.pro`

```java title="proguard-rules.pro"
#Pushwoosh Flutter
-keep class com.pushwoosh.plugin.PushwooshPlugin { *; }
-keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; }
```


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

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