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

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

قبل البدء

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

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

• (على منصات Apple فقط) ثبِّت ما يلي:

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

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

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

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

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

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

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

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

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

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

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

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

   افتح مشروع Unity في بيئة تطوير Unity المتكاملة، ثم انتقِل إلى قسم الإعدادات لكل منصة:

   • على أجهزة 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) الخاصة بـ Firebase Unity ليست خاصة بنظام أساسي معيّن.

2. في مشروع Unity المفتوح، انتقِل إلى Assets (الأصول) > Import Package (استيراد الحزمة) > Custom Package (حزمة مخصّصة).

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

   للحصول على أفضل تجربة مع Firebase Cloud Messaging، ننصحك بتفعيل Google Analytics في مشروعك. بالإضافة إلى ذلك، كجزء من عملية إعداد Analytics، عليك إضافة حزمة Firebase الخاصة بـ Analytics إلى تطبيقك.

   تم تفعيل Analytics لم يتم تفعيل Analytics المزيد

   • أضِف حزمة Firebase لـ Google Analytics: FirebaseAnalytics.unitypackage
   • أضِف الحزمة الخاصة بـ Firebase Cloud Messaging: FirebaseMessaging.unitypackage

   أضِف الحزمة الخاصة بـ Firebase Cloud Messaging: FirebaseMessaging.unitypackage

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

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

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

تتطلّب بعض المنتجات في حزمة تطوير البرامج (SDK) Firebase Unity لنظام التشغيل 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.

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

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

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

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

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

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

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

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

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

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

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

1. انقر على المشروع في Xcode، ثم اختَر علامة التبويب القدرات (Capabilities) من مساحة المحرّر (Editor area).

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 (يظهر أدناه مثال على كيفية إجراء ذلك). إذا كان نشاطك المخصّص يوسّع 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) للغة 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="true" >
</service>

ملاحظة حول تسليم الرسائل على Android

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

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

وباختصار:

منع بدء التشغيل التلقائي

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

لإعادة تفعيل FCM، يمكنك إجراء عملية استدعاء وقت التشغيل:

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

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

• إرسال رسائل المواضيع
• الإرسال إلى مجموعات الأجهزة

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