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

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

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

حساب Pushwoosh.
مشروع Pushwoosh مُعد في حسابك.
Unity 2021.3 أو أحدث.
بالنسبة لـ iOS:
- منصة iOS مُعدة لإرسال الإشعارات الفورية. نوصي باستخدام المصادقة المستندة إلى الرمز المميز (Token-Based Authentication) كأبسط طريقة.
- اضبط البوابة (Gateway) على Sandbox لإرسال الإشعارات إلى جهاز محاكاة.
- للحصول على iOS SDK الأصلي باستخدام Swift Package Manager: Unity 2021.3.15 أو أحدث، وضبط Target minimum iOS Version على 15.0 أو أعلى، وإمكانية الوصول إلى github.com عندما يبني Xcode المشروع. مع Unity 2021.3.0–2021.3.14 أو إصدار iOS مستهدف أقل، تتم إضافة SDK باستخدام CocoaPods (راجع اختيار طريقة إضافة iOS SDK).
بالنسبة لـ Android:
- منصة Android مُعدة.
- رقم المشروع (project number) (المعروف أيضًا بـ Sender ID)، وملف google-services.json، واسم الحزمة (package name) من مشروع Firebase الخاص بك.
- مشروع Firebase متصل بتطبيق Android الخاص بك. اتبع دليل إعداد Firebase إذا لزم الأمر.
رمز تطبيق Pushwoosh الخاص بك ورمز واجهة برمجة تطبيقات جهاز Pushwoosh من لوحة تحكم Pushwoosh.

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

1. إضافة Pushwoosh Unity SDK

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

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.3.0",
    "com.pushwoosh.unity.android": "6.3.0",
    "com.pushwoosh.unity.ios": "6.3.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

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

في 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

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

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

يتطلب جزء Android من SDK أداة External Dependency Manager for Unity (EDM4U) لحل التبعيات الأصلية لـ Android. تخطَّ هذه الخطوة إذا كنت تستهدف iOS فقط.

أضف السجل المحدد النطاق التالي إلى ملف 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. اختيار طريقة إضافة iOS SDK

بشكل افتراضي، يحصل تصدير iOS على SDK الأصلي من حزمة Swift Pushwoosh-XCFramework باستخدام Swift Package Manager. لا تحتاج إلى CocoaPods أو EDM4U لـ iOS، ولا تحتاج إلى تشغيل pod install.

لتغيير مصدر iOS SDK أو إضافة وحدات اختيارية، افتح Window > Pushwoosh SDK Setup في Unity Editor:

في iOS SDK from، حدد Swift Package Manager أو CocoaPods.
مع Swift Package Manager، ضمن Modules (Swift Package Manager only)، حدد الوحدات الاختيارية التي يستخدمها تطبيقك: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. يتم ربط الوحدات بهدف التطبيق (target). لاستخدام وحدة في امتداد التطبيق الخاص بك، أضفها إلى هدف الامتداد في Xcode. مع CocoaPods، يتم التصدير بدون هذه الوحدات.

يعود التصدير إلى CocoaPods، وتوضح وحدة تحكم Unity السبب، عند تحقق أي من الحالات التالية:

تم تحديد CocoaPods في Window > Pushwoosh SDK Setup.
يحتوي المشروع بالفعل على pod باسم PushwooshXCFramework، في ملف *Dependencies.xml يقرؤه EDM4U أو في ملف Podfile. للتبديل إلى Swift Package Manager، أزل هذا الـ pod. بالنسبة لـ Geozones، أزل الـ pod PushwooshXCFramework/Geozones وحدد PushwooshGeozones في Window > Pushwoosh SDK Setup.
إصدار Unity أقدم من 2021.3.15.
قيمة Target minimum iOS Version أقل من 15.0.

مع CocoaPods، لا يلزم EDM4U. يشغّل SDK الأمر pod install بعد التصدير وينشئ ملف Podfile بنفسه، ما لم يكن EDM4U مثبتًا ويكتب ملف Podfile بدلاً منه. إذا فشل pod install، تعرض وحدة تحكم Unity الخطأ. شغّل pod install في مجلد مشروع Xcode الذي تم تصديره.

إذا كانت بيئة البناء لديك لا تستطيع الوصول إلى github.com، فلن يتمكن Xcode من حل حزمة Swift. حدد CocoaPods في Window > Pushwoosh SDK Setup لمثل هذه البناءات.

يحافظ التصدير باستخدام Swift Package Manager على Unity-iPhone.xcworkspace، لذا تعمل سكربتات البناء و CI التي تبني مساحة العمل (workspace) دون تغييرات.

عند التحديث إلى 6.3.0 أو أحدث، ينتقل المشروع الذي حصل على iOS SDK من خلال CocoaPods أو EDM4U إلى Swift Package Manager، ما لم تُبقِه إحدى الحالات المذكورة أعلاه على CocoaPods.

للإبقاء على CocoaPods، حدده في Window > Pushwoosh SDK Setup.
إذا قمت بالتصدير باستخدام Swift Package Manager إلى مجلد تصدير سابق باستخدام CocoaPods، تتم إزالة pod الخاص بـ Pushwoosh من ملف Podfile، لكن مشروع Xcode يظل يشير إلى Pods ولا يُبنى إلا من Unity-iPhone.xcworkspace. ابنِ مساحة العمل (workspace)، أو صدّر إلى مجلد جديد للحصول على مشروع بدون CocoaPods.

4. تهيئة SDK

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

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

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

5.1 القدرات (Capabilities)

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

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

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

5.2 Info.plist

أضف رمز واجهة برمجة تطبيقات جهاز Pushwoosh إلى ملف Info.plist الخاص بك:

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

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

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

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

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

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

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

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

أضف رمز واجهة برمجة تطبيقات جهاز Pushwoosh إلى ملف Assets/Plugins/Android/AndroidManifest.xml داخل وسم <application>:

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

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

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

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

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

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

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

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

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

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)

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

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

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

إذا لم يتم تسليم إشعار Push، فابحث عن رمز الخطأ الخاص بمنصتك في أخطاء الإرسال لمعرفة معناه وكيفية إصلاحه.

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