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

يرشدك هذا الدليل خلال عملية دمج Pushwoosh Unity SDK في تطبيقك.

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

<Aside type="note" title="المتطلبات">
 - [حساب Pushwoosh](https://sso.pushwoosh.com/login).
 - [مشروع Pushwoosh](/ar/product/first-steps/start-with-your-project/create-your-project) مُعد في حسابك.
 - Unity 2021.3 أو أحدث.
 - **بالنسبة لـ 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).
    - `رقم المشروع (project number)` (المعروف أيضًا بـ Sender ID)، وملف `google-services.json`، و`اسم الحزمة (package name)` من مشروع Firebase الخاص بك.
    - مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع [دليل إعداد Firebase](https://firebase.google.com/docs/android/setup#manually_add_firebase) إذا لزم الأمر.
 - `رمز تطبيق Pushwoosh` الخاص بك و[رمز واجهة برمجة تطبيقات جهاز Pushwoosh](/ar/developer/api-reference/api-access-token/#device-api-token) من لوحة تحكم Pushwoosh.
</Aside>

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

### 1. إضافة Pushwoosh Unity SDK

<Tabs>
  <TabItem label="UPM عبر Scoped Registry (موصى به)">

أضف ما يلي إلى ملف `Packages/manifest.json` الخاص بك:

```json title="Packages/manifest.json"
{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.2.7",
    "com.pushwoosh.unity.android": "6.2.7",
    "com.pushwoosh.unity.ios": "6.2.7"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}
```

أضف فقط حزم المنصة التي تحتاجها. على سبيل المثال، احذف `com.pushwoosh.unity.android` إذا كنت تستهدف iOS فقط.

  </TabItem>
  <TabItem label="UPM عبر Git URL">

في Unity، انتقل إلى **Window > Package Manager > + > Add package from git URL** وأضف عناوين URL التالية واحدًا تلو الآخر:

```
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios
```

  </TabItem>
  <TabItem label=".unitypackage">

قم بتنزيل `Pushwoosh.unitypackage` من [GitHub Releases](https://github.com/Pushwoosh/pushwoosh-unity/releases) وقم باستيراده عبر **Assets > Import Package > Custom Package**.

  </TabItem>
</Tabs>

### 2. تثبيت مدير التبعيات الخارجية

يتطلب SDK [External Dependency Manager for Unity (EDM4U)](https://github.com/googlesamples/unity-jar-resolver) لحل التبعيات الأصلية لـ Android و iOS.

أضف السجل المحدد النطاق التالي إلى ملف `Packages/manifest.json` الخاص بك:

```json
{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}
```

ثم أضف الحزمة إلى تبعياتك:

```json
"com.google.external-dependency-manager": "1.2.183"
```

### 3. تهيئة SDK

أنشئ سكربت `PushNotificator.cs` وأرفقه بأي GameObject في المشهد:

```csharp title="PushNotificator.cs"
using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}
```

استبدل:
- `XXXXX-XXXXX` برمز تطبيق Pushwoosh الخاص بك.
- `XXXXXXXXXXXX` برقم مشروع Firebase الخاص بك (Android فقط).

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

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

بعد بناء مشروع iOS من Unity، افتح مشروع Xcode الذي تم إنشاؤه وأضف القدرات التالية في **Signing & Capabilities**:

- **Push Notifications**
- **Background Modes** مع تحديد **Remote notifications**

بالنسبة للإشعارات الحساسة للوقت (Time Sensitive Notifications) (iOS 15+)، أضف أيضًا قدرة **Time Sensitive Notifications**.

#### 4.2 Info.plist

أضف [رمز واجهة برمجة تطبيقات جهاز Pushwoosh](/ar/developer/api-reference/api-access-token/#device-api-token) إلى ملف `Info.plist` الخاص بك:

```xml title="Info.plist"
<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>
```

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

أضف هدف Notification Service Extension إلى مشروع Xcode الخاص بك. هذا مطلوب لتتبع التسليم بدقة والوسائط الغنية (Rich Media) على iOS.

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

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

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

ضع ملف `google-services.json` في دليل **Assets** بمشروع Unity الخاص بك.

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

أضف [رمز واجهة برمجة تطبيقات جهاز Pushwoosh](/ar/developer/api-reference/api-access-token/#device-api-token) إلى ملف `Assets/Plugins/Android/AndroidManifest.xml` داخل وسم `<application>`:

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

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

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

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

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

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

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

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

- `OnPushNotificationsReceived` — يتم تشغيله عند وصول إشعار فوري
- `OnPushNotificationsOpened` — يتم تشغيله عندما ينقر المستخدم على إشعار

قم بإعداد هؤلاء المستمعين أثناء تهيئة SDK:

```csharp title="PushNotificator.cs"
void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}
```

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

قم بتخصيص الإشعارات الفورية عن طريق تحديد المستخدمين وتعيين خصائصهم:

```csharp
// تعيين معرف المستخدم للتتبع عبر الأجهزة
Pushwoosh.Instance.SetUserId("user-123");

// تعيين بريد إلكتروني للمستخدم
Pushwoosh.Instance.SetEmail("user@example.com");

// تعيين مستخدم بمعرف وبريد إلكتروني
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// تعيين اللغة المفضلة
Pushwoosh.Instance.SetLanguage("en");
```

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

العلامات هي أزواج من المفاتيح والقيم يتم تعيينها للأجهزة، مما يتيح تقسيم المستخدمين وتوجيه الرسائل:

```csharp
// علامة نصية
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// علامة عدد صحيح
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// علامة قائمة
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// الحصول على جميع العلامات
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});
```

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

تتبع إجراءات المستخدم لتحليل السلوك وتشغيل الرسائل الآلية:

```csharp
// تتبع حدث تسجيل الدخول
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// تتبع حدث شراء
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});
```

### تفضيلات الاتصال

اسمح للمستخدمين بالاشتراك أو إلغاء الاشتراك في الإشعارات الفورية برمجيًا:

```csharp
// تمكين الاتصال
Pushwoosh.Instance.SetCommunicationEnabled(true);

// تعطيل الاتصال
Pushwoosh.Instance.SetCommunicationEnabled(false);

// التحقق من الحالة الحالية
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();
```

### إدارة الشارات (Badge)

تحكم في رقم شارة التطبيق على المنصات المدعومة:

```csharp
// تعيين الشارة إلى رقم محدد
Pushwoosh.Instance.SetBadgeNumber(3);

// زيادة الشارة
Pushwoosh.Instance.AddBadgeNumber(1);

// مسح الشارة
Pushwoosh.Instance.SetBadgeNumber(0);
```

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

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