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

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

• سجّل الدخول إلى Firebase باستخدام حسابك الحساب.

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

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

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

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

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

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

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

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

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

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

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

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

   أين يمكنك العثور على رقم تعريف مشروع Unity؟

   افتح مشروعك على Unity في Unity IDE ثم انتقِل إلى الإعدادات. قسم لكل نظام أساسي:

   • على أجهزة iOS - انتقِل إلى إعدادات الإنشاء > iOS.

   • على أجهزة Android - انتقِل إلى Android > إعدادات المشغّل > إعدادات أخرى

   رقم تعريف مشروع Unity هو قيمة معرِّف الحزمة (رقم التعريف المثالي: com.yourcompany.yourproject).

5. (اختياري) أدخِل الأسماء المستعارة الخاصة بمنصة مشروع Unity.
   هذه الألقاب هي معرّفات داخلية ومعرّفات ملائمة ومرئية فقط. إليك في وحدة تحكّم Firebase.

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

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

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

   • لنظام التشغيل iOS - انقر على تنزيل GoogleService-Info.plist.

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

   ما الذي تحتاج إلى معرفته عن ملف الإعداد هذا؟

   • يحتوي ملف تهيئة Firebase على معرّفات فريدة ولكنها غير سرية لمشروعك. لمزيد من المعلومات حول ملف الإعداد هذا، انتقِل إلى فهم Firebase المشاريع:

   • يمكنك تنزيل إعدادات Firebase. ملف ومرة أخرى في أي وقت.

   • تأكد من عدم إلحاق اسم ملف التهيئة بأحرف إضافية، مثل (2).

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

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

الخطوة 4: إضافة حِزم تطوير البرامج (SDK) الخاصة بمنصّة Firebase Unity

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

   • يمكنك تنزيل Firebase Unity حزمة تطوير البرامج (SDK) مرة أخرى متى شئت.

   • وحزمة تطوير البرامج (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) Firebase "Unity" لنظام التشغيل Android Google Play services، الذي يجب أن يكون مُحدّثًا قبل استخدام حزمة SDK.

أضف عبارة using ورمز الإعداد التالي في بداية التطبيق. يمكنك البحث عن Google Play services وتعديله بشكل اختياري إلى تطلبه حزمة تطوير البرامج (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.

تحميل مفتاح مصادقة أسماء نقاط الوصول (APN) إلى خدمة الدعم في Apple

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

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

2. في مفتاح مصادقة أسماء نقاط الوصول (APN) ضمن ضبط تطبيق iOS، انقر على تحميل .

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

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

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

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

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

تستخدم الإصدارات الجديدة من حزمة تطوير برامج 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 فارغًا.

وباختصار:

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

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

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

التعامل مع الرسائل التي تتضمن روابط لصفحات معيّنة على Android

يسمح 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. لمزيد من المعلومات، يُرجى مراجعة نموذج للبدء السريع الذي يوضح هذه الوظيفة.

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

• إرسال رسائل بشأن المواضيع
• الإرسال إلى مجموعات الأجهزة
• إرسال رسائل عند استلام الطلب

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