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

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

قبل البدء

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

  • تثبيت Unity 2019.1 أو إصدار أحدث. قد تكون الإصدارات السابقة متوافقة أيضًا ولكن لن تكون مدعومة بشكل نشط. يُعَدّ دعم Unity 2019.1 متوقفًا ولن يعود متاحًا بشكل نشط بعد الإصدار الرئيسي التالي.

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

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

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

    • لنظام التشغيل iOS: يستهدف الإصدار 11 من نظام التشغيل iOS أو الإصدارات الأحدث.
    • لنظام التشغيل tvOS - يستهدف الإصدار tvOS 12 أو الإصدارات الأحدث.
    • لنظام التشغيل Android: يستهدف المستوى 19 من واجهة برمجة التطبيقات (KitKat) أو أعلى

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

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

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

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

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

    تفعيل الإحصاءات

    • إضافة حزمة Firebase الخاصة بخدمة "إحصاءات Google": FirebaseAnalytics.unitypackage
    • إضافة حزمة "المراسلة عبر السحابة الإلكترونية من Firebase": FirebaseMessaging.unitypackage

    عدم تفعيل الإحصاءات

    إضافة حزمة "المراسلة عبر السحابة الإلكترونية من Firebase": FirebaseMessaging.unitypackage

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

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

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

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

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

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

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

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

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

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

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

  2. بدِّل مفتاح الإشعارات الفورية إلى تفعيل.

  3. انتقِل للأسفل وصولاً إلى أوضاع الخلفية، ثم بدِّل الوضع إلى تفعيل.

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

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

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

تهيئة نشاط نقطة دخول مخصص

إذا كان تطبيقك لا يستخدم القيمة التلقائية "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

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

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

وباختصار:

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

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

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

لإعادة تفعيل خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، يمكنك إجراء مكالمة في بيئة التشغيل:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

تظل هذه القيمة سارية في جميع عمليات إعادة تشغيل التطبيق بعد ضبطها.

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

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

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