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

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

قبل البدء

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

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

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

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

  • تأكَّد من أنّ مشروعك على 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 خاص بها ستحتاج إلى إعدادات إضافية.

يأتي Firebase Cloud Messaging Unity Plugin على 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 (يُعرَض أدناه مثال على كيفية إجراء ذلك). إذا كان ال activity المخصّص يمتد إلى UnityPlayerActivity، يمكنك بدلاً من ذلك توسيع com.google.firebase.MessagingUnityPlayerActivity الذي ينفِّذ كل ال methods اللازمة.

إذا كنت تستخدِم نشاطًا مخصّصًا ولا تُمدِّد 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) لـ C++ في Firebase (بدءًا من الإصدار 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. لمزيد من المعلومات، اطّلِع على نموذج البدء السريع الذي يوضّح هذه الوظيفة.

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

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