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


يوضّح دليل البدء السريع هذا كيفية إعداد Firebase Cloud Messaging في تطبيقات الأجهزة الجوّالة وتطبيقات الويب الخاصة بالعملاء حتى تتمكّن من إرسال الرسائل بشكل موثوق. بالنسبة إلى بيئات الخادم، يُرجى الاطّلاع على بيئة الخادم وFCM.

إعداد تطبيق عميل Firebase Cloud Messaging باستخدام Unity

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

قبل البدء

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

  • ثبِّت الإصدار 2021 من Unity 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: عليك إعداد جهاز فعلي لتشغيل تطبيقك، وإكمال المهام التالية:

      • احصل على مفتاح مصادقة لخدمة الإشعارات الفورية من Apple لحسابك على Apple Developer.
      • فعِّل الإشعارات الفورية في 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: إضافة حِزم Firebase Unity SDK

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

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

  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. المنتجات التي تتضمّن هذه التبعية يجب أن يكون 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.

إعداد منصات Apple

اتّبِع التعليمات التالية لإعداد FCM باستخدام منصتَي Unity وApple.

تحميل مفتاح مصادقة APNs

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

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

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

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

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

  1. انقر على مشروعك في Xcode، ثم اختَر علامة التبويب عام (General) من مساحة المحرّر (Editor area).
  2. انتقِل إلى الأُطر والمكتبات المرتبطة، ثم انقر على الزر + لإضافة إطار.
  3. في النافذة التي تظهر، انتقِل إلى UserNotifications.framework، وانقر على هذا الإدخال، ثم انقر على إضافة.
  4. انقر على مشروعك في Xcode، ثم اختَر علامة التبويب الإمكانات (Capabilities) من مساحة المحرّر (Editor area).
  5. فعِّل الإشعارات الفورية.
  6. انتقِل إلى أوضاع الخلفية، ثم فعِّلها.
  7. ضَع علامة في مربّع الاختيار الإشعارات عن بُعد ضمن أوضاع التشغيل في الخلفية.

إعداد 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

اتّبِع التعليمات التالية لإعداد FCM باستخدام منصّتَي Unity وAndroid.

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

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

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

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

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

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

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

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

بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمضي قدمًا في استخدام FCM مع Unity: