بدء استخدام "المراسلة عبر السحابة الإلكترونية من Firebase" في تطبيقات Unity

اختيار المنصة: iOS+ Android الويب Flutter Unity C++‎


يوضّح هذا الدليل كيفية بدء استخدام Firebase Cloud Messaging في تطبيقات عملاء Unity لكي تتمكّن من إرسال الرسائل بشكل موثوق.

لكتابة تطبيق عميل Firebase Cloud Messaging من عدّة منصات باستخدام Unity، استخدِم واجهة برمجة التطبيقات Firebase Cloud Messaging. تعمل حزمة تطوير البرامج (SDK) في Unity مع كل من Android وApple، مع بعض الإعدادات الإضافية المطلوبة لكل نظام أساسي.

قبل البدء

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

  • ثبِّت الإصدار Unity 2022 LTS أو إصدارًا أحدث. قد تكون الإصدارات السابقة متوافقة أيضًا، ولكن لن يتم توفير الدعم لها بشكل نشط.

  • (أنظمة Apple الأساسية فقط) ثبِّت ما يلي:

    • الإصدار 26.2 من Xcode أو إصدار أحدث

  • تأكَّد من أنّ مشروع Unity يستوفي المتطلبات التالية:

    • بالنسبة إلى أجهزة iOS: يستهدف الإصدار 15 من نظام التشغيل iOS أو الإصدارات الأحدث
    • بالنسبة إلى tvOS: يستهدف الإصدار 15 من tvOS أو الإصدارات الأحدث
    • على أجهزة Android: يستهدف المستوى 24 من واجهة برمجة التطبيقات (Nougat) أو الإصدارات الأحدث

  • اضبط جهازًا أو استخدِم محاكيًا لتشغيل مشروع Unity.

    • بالنسبة إلى نظام التشغيل iOS أو tvOS: عليك إعداد جهاز فعلي لتشغيل تطبيقك، وإكمال المهام التالية:

      • احصل على مفتاح مصادقة الإشعارات الفورية من Apple لحساب المطوّر على Apple.
      • فعِّل الإشعارات الفورية في XCode ضمن التطبيق > الإمكانات.

    • على أجهزة Android: برامج المحاكاة يجب استخدام صورة محاكاة مع Google Play.

إذا لم يكن لديك مشروع Unity وتريد فقط تجربة أحد منتجات Firebase، يمكنك تنزيل أحد نماذج البدء السريع.

الخطوة 1: إنشاء مشروع Firebase

قبل إضافة Firebase إلى مشروع Unity، عليك إنشاء مشروع Firebase لربطه بمشروع Unity. انتقِل إلى مقالة فهم مشاريع Firebase لمزيد من المعلومات عن مشاريع Firebase.

الخطوة 2: تسجيل تطبيقك في Firebase

يمكنك تسجيل تطبيق أو لعبة أو أكثر لربطها بمشروعك على Firebase.

  1. انتقِل إلى وحدة تحكّم Firebase.

  2. في وسط صفحة النظرة العامة على المشروع، انقر على رمز Unity () لبدء سير عمل الإعداد.

    إذا سبق لك إضافة تطبيق إلى مشروعك على Firebase، انقر على إضافة تطبيق لعرض خيارات المنصّة.

  3. اختَر هدف الإصدار الذي تريد تسجيله في مشروع Unity، أو يمكنك اختيار تسجيل كلا الهدفَين الآن في الوقت نفسه.

  4. أدخِل أرقام تعريف مشروعك على Unity الخاصة بالمنصة.

    • بالنسبة إلى أجهزة iOS: أدخِل معرّف iOS لمشروع Unity في حقل معرّف حزمة iOS.

    • بالنسبة إلى Android: أدخِل معرّف Android لمشروع Unity في حقل اسم حزمة Android.
      غالبًا ما يُستخدَم المصطلحان اسم الحزمة ورقم تعريف التطبيق بالتبادل.

  5. اختياري: أدخِل الأسماء المميّزة الخاصة بالمنصّة لمشروع Unity.
    هذه الأسماء المستعارة هي معرّفات داخلية ومريحة ولا تظهر إلا لك في وحدة تحكّم "Firebase".

  6. انقر على تسجيل التطبيق.

الخطوة 3: إضافة ملفات إعداد Firebase

  1. احصل على ملفات إعداد Firebase الخاصة بالمنصة في سير عمل إعداد وحدة تحكّم Firebase.

    • بالنسبة إلى أجهزة iOS: انقر على تنزيل GoogleService-Info.plist.

    • بالنسبة إلى Android: انقر على تنزيل google-services.json.

  2. افتح نافذة المشروع في مشروع Unity، ثم انقل ملفات الإعداد إلى مجلد Assets.

  3. بالعودة إلى وحدة تحكّم Firebase، في سير عمل الإعداد، انقر على التالي.

الخطوة 4: إضافة حزم Firebase Unity SDK

  1. في وحدة تحكّم Firebase، انقر على تنزيل حزمة تطوير البرامج (SDK) لـ Firebase Unity، ثم استخرِج حزمة تطوير البرامج (SDK) في مكان مناسب.

  2. في مشروع Unity المفتوح، انتقِل إلى مواد العرض > استيراد حزمة > حزمة مخصّصة.

  3. من حزمة تطوير البرامج (SDK) التي تم استخراجها، اختَر منتجات Firebase المتوافقة التي تريد استخدامها في تطبيقك.

    للحصول على تجربة مثالية مع "Firebase Cloud Messaging"، ننصحك بتفعيل "Google Analytics" في مشروعك. كجزء من عملية إعداد Analytics، عليك أيضًا إضافة حزمة Firebase لـ Analytics إلى تطبيقك.

    تم تفعيل Analytics

    • أضِف حزمة Firebase لـ Google Analytics: FirebaseAnalytics.unitypackage
    • أضِف الحزمة لـ Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    ‫Analytics غير مفعَّل

    أضِف حزمة Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. في نافذة استيراد حزمة Unity‏ (Import Unity Package)، انقر على استيراد (Import).

  5. بالعودة إلى وحدة تحكّم Firebase، في سير عمل الإعداد، انقر على التالي.

الخطوة 5: التأكّد من متطلبات إصدار "خدمات Google Play"

تتطلّب بعض المنتجات في حزمة تطوير البرامج (SDK) لـ Unity Firebase لنظام التشغيل Android استخدام Google Play services. المنتجات التي تتطلّب هذا الإجراء يجب تحديث "Google Play services" قبل استخدام هذه المنتجات.

أضِف عبارة using ورمز الإعداد التاليَين في بداية تطبيقك. يمكنك التحقّق من توفّر تحديث لـ Google Play services وتحديثه اختياريًا إلى الإصدار المطلوب قبل استدعاء أي طرق أخرى في حزمة SDK.

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

أن يكون مشروع Unity مسجَّلاً ومُعدًّا لاستخدام Firebase

إعداد منصات Apple

اتّبِع التعليمات التالية لإعداد FCM مع منصّتَي Unity وApple.

تحميل مفتاح مصادقة APNs

حمِّل مفتاح مصادقة APNs إلى Firebase. إذا لم يكن لديك مفتاح مصادقة APNs، احرص على إنشاء مفتاح في مركز أعضاء مطوّري Apple.

  1. في وحدة تحكّم Firebase، انتقِل إلى الإعدادات > الإعدادات العامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.
  2. في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب توفير طريقة اتصال واحدة على الأقل.
  3. انتقِل إلى الموقع الذي حفظت فيه مفتاحك، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (المتوفّر في مركز أعضاء مطوّري Apple) وانقر على تحميل.

تفعيل الإشعارات الفورية على منصات Apple

  1. انقر على مشروعك في Xcode، ثم اختَر علامة التبويب عام من مساحة المحرِّر.
  2. انتقِل إلى أُطر العمل والمكتبات المرتبطة (Linked Frameworks and Libraries)، ثم انقر على الزر + لإضافة إطار عمل.
  3. في النافذة التي تظهر، انتقِل إلى UserNotifications.framework، وانقر على هذا الإدخال، ثم انقر على إضافة.
  4. انقر على مشروعك في Xcode، ثم اختَر علامة التبويب الإمكانات من مساحة المحرِّر.
  5. اضبط الإشعارات الفورية على تفعيل.
  6. انتقِل إلى أوضاع الخلفية (Background Modes)، ثم اضبطه على تفعيل (On).
  7. ضَع علامة في مربّع الاختيار الإشعارات عن بُعد ضمن أوضاع الخلفية.

إعداد Firebase Cloud Messaging

تفعيل التسجيل باستخدام معرّف تثبيت Firebase

لتفعيل تسجيل نسخة تطبيقك في "Firebase Cloud Messaging" باستخدام رقم تعريف تثبيت Firebase‏ (FID)، عليك أولاً تفعيل أرقام تعريف تثبيت Firebase في إعدادات تطبيقك لكلّ من نظامَي التشغيل Android وApple:

Android

أضِف عنصر <meta-data> التالي داخل عنصر <application> في AndroidManifest.xml:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

Swift

أضِف المفتاح FirebaseMessagingInstallationIdEnabled إلى Info.plist واضبطه على YES:

FirebaseMessagingInstallationIdEnabled = YES

التسجيل في فعاليات "FCM"

ستتم تهيئة مكتبة Firebase Cloud Messaging عند إضافة معالِجات للحدثَين RegistrationReceived أو MessageReceived.

عند الإعداد، تسجّل Firebase Cloud Messaging مثيل تطبيق العميل لتلقّي الرسائل باستخدام رقم تعريف تثبيت Firebase‏ (FID). يتلقّى التطبيق معرّف مثيل Firebase مع الحدث RegistrationReceived، والذي يجب تخزينه مؤقتًا على الخادم لاستهداف هذا الجهاز المحدّد للرسائل.

بالإضافة إلى ذلك، عليك التسجيل في الحدث OnMessageReceived إذا أردت أن تتمكّن من تلقّي الرسائل الواردة.

سيظهر الإعداد على النحو التالي:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

بعد الحصول على معرّف Firebase Installation ID، أرسِله إلى خادم تطبيقك وخزِّنه باستخدام الطريقة المفضّلة لديك.

التسجيل يدويًا عند إيقاف الإعداد التلقائي

يمكنك أيضًا تفعيل التسجيل يدويًا باستخدام FCM في وقت التشغيل من خلال RegisterAsync():

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

الوصول إلى رمز التسجيل في FCM (متوقّف نهائيًا)

إذا كان تطبيقك لا يزال يستخدم واجهات برمجة التطبيقات المتوقّفة نهائيًا للرموز المميّزة، يمكنك الاستماع إلى TokenReceived:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

بدء الإعداد باستخدام أنظمة Android الأساسية

اتّبِع التعليمات التالية لإعداد FCM مع نظامَي Unity وAndroid الأساسيَّين.

إعداد نشاط نقطة دخول Android

يأتي Firebase Cloud Messaging مرفقًا مع نشاط نقطة دخول مخصّصة يحلّ محلّ UnityPlayerActivity التلقائي. إذا لم تكن تستخدم نقطة دخول مخصّصة، سيتم إجراء هذا الاستبدال تلقائيًا ولن تحتاج إلى اتخاذ أي إجراء إضافي.

يأتي المكوّن الإضافي Firebase Cloud Messaging Unity على Android مرفقًا بملفَّين إضافيَّين:

  • يحتوي Assets/Plugins/Android/libmessaging_unity_player_activity.jar على نشاط يُسمى MessagingUnityPlayerActivity يحلّ محلّ UnityPlayerActivity العادي.
  • يوجّه Assets/Plugins/Android/AndroidManifest.xml التطبيق لاستخدام MessagingUnityPlayerActivity كنقطة دخول إلى التطبيق.

يتم توفير هذه الملفات لأنّ UnityPlayerActivity التلقائي لا يتعامل مع عمليات نقل مراحل النشاط onStop وonRestart أو لا ينفّذ onNewIntent اللازم لـ Firebase Cloud Messaging للتعامل مع الرسائل الواردة بشكل صحيح.

ضبط نشاط نقطة دخول مخصّصة

إذا كان تطبيقك لا يستخدم UnityPlayerActivity التلقائي، عليك إزالة AndroidManifest.xml المقدَّم والتأكّد من أنّ نشاطك المخصّص يتعامل بشكل صحيح مع جميع عمليات نقل مراحل نشاط Android (يظهر أدناه مثال على كيفية إجراء ذلك). إذا كان نشاطك المخصّص يمتد إلى UnityPlayerActivity، يمكنك بدلاً من ذلك تمديد com.google.firebase.MessagingUnityPlayerActivity الذي ينفّذ جميع الطرق اللازمة.

إذا كنت تستخدم نشاطًا مخصّصًا ولا تمدّد com.google.firebase.MessagingUnityPlayerActivity، يجب تضمين المقتطفات التالية في نشاطك.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For earlier versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This makes sure that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

تستخدم الإصدارات الجديدة من حزمة Firebase C++ SDK (الإصدار 7.1.0 والإصدارات الأحدث) JobIntentService، ما يتطلّب تعديلات إضافية في ملف AndroidManifest.xml.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="true" >
</service>

تسليم الرسائل على أجهزة Android

عندما لا يكون التطبيق قيد التشغيل على الإطلاق وينقر المستخدم على إشعار، لا يتم توجيه الرسالة تلقائيًا من خلال عمليات الاستدعاء المضمّنة في FCM. في هذه الحالة، يتم تلقّي حمولات الرسائل من خلال Intent يُستخدَم لبدء التطبيق.

بالنسبة إلى الرسائل التي يتم تلقّيها عندما يكون التطبيق في الخلفية، يتم استخدام محتوى حقل الإشعار الخاص بها لملء إشعار لوحة النظام، ولكن لن يتم إرسال محتوى الإشعار هذا إلى FCM. هذا يعني أنّ FirebaseMessage.Notification ستكون قيمة فارغة.

وباختصار:

حالة التطبيق إشعار البيانات كلاهما
لون الواجهة Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
الخلفية علبة النظام Firebase.Messaging.FirebaseMessaging.MessageReceived الإشعار: في لوحة الإشعارات
البيانات: في الإضافات الخاصة بالintent

يسمح FCM بإرسال رسائل تحتوي على رابط عميق في تطبيقك. لتلقّي الرسائل التي تحتوي على رابط عميق، يجب إضافة intent filter جديد إلى النشاط الذي يتعامل مع الروابط العميقة في تطبيقك. يجب أن يلتقط intent filter الروابط العميقة في نطاقك. في ملف AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

يمكنك أيضًا تحديد حرف بدل لجعل intent filter أكثر مرونة. على سبيل المثال:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

عندما ينقر المستخدمون على إشعار يحتوي على رابط إلى المخطط والمضيف اللذين تحدّدهما، سيبدأ تطبيقك النشاط باستخدام intent filter هذا لمعالجة الرابط.

منع الإعداد التلقائي

تنشئ FCM رمزًا مميزًا للتسجيل من أجل استهداف الأجهزة. عند إنشاء رمز مميّز، تحمّل المكتبة المعرّف وبيانات الإعدادات إلى Firebase. إذا أردت الحصول على موافقة صريحة قبل استخدام الرمز المميّز، يمكنك منع إنشائه في وقت الضبط من خلال إيقاف FCM (و"إحصاءات Google" على Android). يمكنك إضافة قيمة بيانات وصفية إلى Info.plist (وليس GoogleService-Info.plist) على Apple، أو AndroidManifest.xml على Android:

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

لإعادة تفعيل FCM، يمكنك إجراء مكالمة أثناء التشغيل:

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

وتظل هذه القيمة محفوظة عند إعادة تشغيل التطبيق بعد ضبطها.

الخطوات التالية

بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمضي قدمًا في استخدام "FCM" في Unity: