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

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

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

المتطلبات

• حساب Pushwoosh.
• مشروع Pushwoosh تم إعداده في حسابك.
• Unity 2021.3 أو أحدث.
• بالنسبة لـ iOS:
  • منصة iOS مهيأة لإرسال الإشعارات الفورية. نوصي باستخدام المصادقة المستندة إلى الرمز (Token-Based Authentication) كأبسط طريقة.
  • قم بتعيين البوابة (Gateway) إلى Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
• بالنسبة لـ Android:
  • منصة Android مهيأة.
  • رقم المشروع (المعروف أيضًا بـ Sender ID)، وملف google-services.json، واسم الحزمة من مشروع Firebase الخاص بك.
  • مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
• رمز تطبيق Pushwoosh الخاص بك و Pushwoosh Device API Token من لوحة تحكم Pushwoosh.

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

1. إضافة Pushwoosh Unity SDK

UPM عبر Scoped Registry (موصى به)

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

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 فقط.

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

.unitypackage

قم بتنزيل Pushwoosh.unitypackage من إصدارات GitHub وقم باستيراده عبر Assets > Import Package > Custom Package.

2. تثبيت External Dependency Manager

يتطلب SDK External Dependency Manager for Unity (EDM4U) لحل الاعتماديات الأصلية لـ Android و iOS.

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

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

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

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

3. تهيئة SDK

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

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 Device API Token إلى ملف Info.plist الخاص بك:

Info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

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

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

اتبع الدليل الأصلي لإضافة هدف الامتداد.

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

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

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

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

أضف Pushwoosh Device API Token إلى ملف Assets/Plugins/Android/AndroidManifest.xml الخاص بك داخل وسم <application>:

AndroidManifest.xml

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

تنبيه

تأكد من منح الرمز (token) حق الوصول إلى التطبيق الصحيح في لوحة تحكم Pushwoosh. اعرف المزيد

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

1. قم ببناء وتشغيل المشروع على المنصة المستهدفة.
2. امنح الإذن للإشعارات الفورية عند الطلب.
3. اذهب إلى لوحة تحكم Pushwoosh و أرسل إشعارًا فوريًا.

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

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

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

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

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

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

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();
}

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

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

// تعيين معرّف المستخدم للتتبع عبر الأجهزة
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)

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

// علامة نصية
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)

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

// تتبع حدث تسجيل الدخول
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" }
});

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

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

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

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

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

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

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

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

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

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

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

إذا واجهت أي مشاكل أثناء عملية التكامل، فارجع إلى قسم الدعم والمجتمع.