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

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


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

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

قبل البدء

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

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

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

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

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

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

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

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

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

    • بالنسبة إلى أجهزة 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 المفتوح، انتقِل إلى Assets > Import Package > Custom Package.

  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. في نافذة Import Unity Package (استيراد حزمة Unity)، انقر على 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 Developer.

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

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

  1. انقر على مشروعك في Xcode، ثم اختَر علامة التبويب عام من مساحة المحرِّر.
  2. انتقِل إلى أُطر العمل والمكتبات المرتبطة (Linked Frameworks and Libraries)، ثم انقر على الزر + لإضافة إطار عمل.
  3. في النافذة التي تظهر، انتقِل إلى UserNotifications.framework، وانقر على هذا الإدخال، ثم انقر على إضافة.
  4. انقر على مشروعك في Xcode، ثم اختَر علامة التبويب الإمكانات من مساحة المحرِّر.
  5. اضبط الإشعارات الفورية على تفعيل.
  6. انتقِل إلى أوضاع الخلفية، ثم اضبطه على تفعيل.
  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 comes bundled with a custom entry point activity that replaces the default 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="false" >
</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: