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

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

قبل البدء

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

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

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

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

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

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

  • إعداد جهاز أو استخدام محاكي لتشغيل مشروعك على Unity

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

    • لأجهزة 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: إضافة حِزم تطوير البرامج (SDK) الخاصة بمنصّة Firebase Unity

  1. في وحدة تحكّم Firebase، انقر على تنزيل حزمة SDK لنظام التشغيل Firebase Unity، ثم فك ضغط حزمة SDK في مكان مناسب.

    • يمكنك تنزيل حزمة SDK Firebase Unity مرة أخرى في أي وقت.

    • حزمة SDK لنظام التشغيل Firebase Unity ليست مرتبطة بنظام أساسي معيّن.

  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، انقر على استيراد.

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

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

تتطلّب حزمة SDK لنظام التشغيل Android من Firebase Unity استخدام Google Play services، ويجب أن يكون محدَّثًا قبل استخدام حزمة SDK.

أضِف بيان using ورمز الإعداد التاليَين في بداية تطبيقك. يمكنك التحقّق من توفّر Google Play services واختياريًا تحديثها إلى الإصدار الذي تتطلّبه حزمة SDK Firebase Unity قبل استدعاء أي من ال methods الأخرى في حزمة 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.

تحميل مفتاح مصادقة APNs للحصول على دعم من Apple

حمِّل مفتاح مصادقة APNs إلى Firebase. إذا لم يكن لديك مفتاح مصادقة APNs، احرص على إنشاء مفتاح في Apple Developer Member Center.

  1. ضمن مشروعك في وحدة تحكّم Firebase، اختَر رمز الترس، واختَر إعدادات المشروع، ثم انقر على علامة التبويب المراسلة عبر السحابة الإلكترونية.

  2. في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على الزر تحميل .

  3. انتقِل إلى المكان الذي حفظت فيه مفتاحك، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (متاحًا في Apple Developer Member Center) وانقر على تحميل.

تفعيل الإشعارات الفورية على أنظمة Apple الأساسية

الخطوة 1: إضافة إطار عمل إشعارات المستخدمين

  1. انقر على المشروع في Xcode، ثم اختَر علامة التبويب عام من منطقة المحرِّر.

  2. انتقِل للأسفل إلى الإطارات والمراجع المرتبطة، ثم انقر على الزر + لإضافة إطار عمل.

  3. في النافذة التي تظهر، انتقِل إلى UserNotifications.framework، ثم انقر على هذا الإدخال، ثم انقر على إضافة.

الخطوة 2: تفعيل الإشعارات الفورية

  1. انقر على المشروع في Xcode، ثم اختَر علامة التبويب الإمكانات من منطقة المحرِّر.

  2. اضبط الإشعارات الفورية على تفعيل.

  3. انتقِل للأسفل إلى الأوضاع التي تعمل في الخلفية، ثم اضبط الخيار على تفعيل.

  4. ضَع علامة في مربّع الاختيار الإشعارات عن بُعد ضمن الأوضاع التي تعمل في الخلفية.

بدء Firebase Cloud Messaging

سيتم إعداد مكتبة "الرسائل السحابية من Firebase" عند إضافة معالِجات للحدثَين TokenReceived أو MessageReceived.

عند الإعداد، يتم طلب رمز مميّز للتسجيل لمثيل تطبيق العميل. سيتلقّى التطبيق الرمز المميّز مع الحدث OnTokenReceived، الذي يجب تخزينه مؤقتًا لاستخدامه لاحقًا. ستحتاج إلى هذا الرمز المميّز إذا كنت تريد استهداف هذا الجهاز المحدّد للرسائل.

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

يظهر الإعداد بالكامل على النحو التالي:

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

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

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

ضبط نشاط نقطة دخول Android

على نظام التشغيل Android، يأتي Firebase Cloud Messaging مُدمجًا مع نقطة دخول مخصّصة نشاط يستبدل UnityPlayerActivity التلقائي. إذا كنت لا تستخدم نقطة إدخال مخصّصة، سيتم إجراء هذا الاستبدال تلقائيًا ولن تضطر إلى اتخاذ أي إجراء إضافي. إنّ التطبيقات التي لا تستخدم نقطة الدخول التلقائية Activity أو التي تقدّم Assets/Plugins/AndroidManifest.xml خاص بها ستحتاج إلى إعدادات إضافية.

يتوفّر مكوّن Unity الإضافي Firebase Cloud Messaging على 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 older 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 ensures 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);
}

تستخدم الإصدارات الجديدة من حزمة تطوير البرامج (SDK) لمنصة Firebase C++ (الإصدار 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 الإشعار: علبة النظام
البيانات: في إضافات الطلب

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

تُنشئ FCM رمزًا مميزًا للتسجيل لاستهداف الأجهزة. عند إنشاء رمز مميّز، تحمّل المكتبة معرّف بيانات الضبط إلى Firebase. إذا كنت تريد الحصول على موافقة صريحة قبل استخدام الرمز المميّز، يمكنك منع إنشائه في وقت الضبط من خلال إيقاف خدمة "إشعارات Google من خادم Firebase" (و"إحصاءات 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

لإعادة تفعيل "خدمة إرسال الرسائل إلى الأجهزة الجوّالة من Google"، يمكنك إجراء مكالمة وقت التشغيل:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

يسمح FCM بإرسال الرسائل التي تحتوي على رابط لصفحة في تطبيقك. لتلقّي رسائل تحتوي على رابط لصفحة في التطبيق، يجب إضافة فلتر أهداف جديد إلى النشاط الذي يعالج روابط لصفحات في تطبيقك. من المفترض أن يلتقط فلتر الأهداف روابط لصفحات معيّنة في نطاقك. إذا كانت رسائلك لا تحتوي على رابط لصفحة في التطبيق، لن يكون هذا الإعداد ضروريًا. في ملف 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>
  <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>

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

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

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

لإضافة سلوك آخر أكثر تقدمًا إلى تطبيقك، اطّلِع على أدلة إرسال الرسائل من خادم التطبيق:

يُرجى العلم أنّك ستحتاج إلى تنفيذ الخادم للاستفادة من هذه الميزات.