了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

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

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

قبل ان تبدأ

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

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

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

    • Xcode 13.3.1 أو أعلى
    • CocoaPods 1.10.0 أو أعلى

  • تأكد من أن مشروع الوحدة الخاص بك يلبي هذه المتطلبات:

    • لنظام iOS - يستهدف iOS 11 أو أعلى
    • بالنسبة إلى tvOS - يستهدف tvOS 12 أو أعلى
    • لنظام التشغيل Android - يستهدف مستوى API 19 (KitKat) أو أعلى

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

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

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

    • لنظام Android - يجب أن تستخدم المحاكيات صورة المحاكي مع Google Play.

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

الخطوة 1: أنشئ مشروع Firebase

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

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

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

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

  2. في وسط صفحة نظرة عامة على المشروع ، انقر فوق أيقونة الوحدة ( ) لبدء سير عمل الإعداد.

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

  3. حدد أي هدف بناء لمشروع الوحدة الخاص بك الذي ترغب في تسجيله ، أو يمكنك حتى تحديد تسجيل كلا الهدفين الآن في نفس الوقت.

  4. أدخل المعرف (المعرفات) الخاص بالنظام الأساسي لمشروع الوحدة الخاص بك.

    • لنظام iOS - أدخل معرف iOS لمشروع Unity الخاص بك في حقل معرف حزمة iOS .

    • لنظام Android - أدخل معرف Android لمشروع Unity الخاص بك في حقل اسم حزمة Android .
      غالبًا ما يتم استخدام المصطلحين اسم الحزمة ومعرف التطبيق بالتبادل.

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

  6. انقر فوق تسجيل التطبيق .

الخطوة 3: أضف ملفات تهيئة Firebase

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

    • لنظام iOS - انقر فوق تنزيل GoogleService-Info.plist .

    • لنظام Android - انقر فوق تنزيل google-services.json .

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

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

الخطوة 4: أضف حزم Firebase Unity SDK

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

    • يمكنك تنزيل Firebase Unity SDK مرة أخرى في أي وقت.

    • إن حزمة Firebase Unity SDK ليست خاصة بالنظام الأساسي.

  2. في مشروع Unity المفتوح ، انتقل إلى Assets > Import Package > Custom Package .

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

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

    تم تمكين التحليلات

    • أضف حزمة Firebase لبرنامج Google Analytics: FirebaseAnalytics.unitypackage
    • أضف الحزمة لـ Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    لم يتم تمكين التحليلات

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

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

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

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

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

أضف الكود التالي في بداية التطبيق الخاص بك. يمكنك التحقق من خدمات Google Play وتحديثها اختياريًا إلى الإصدار المطلوب بواسطة Firebase Unity SDK قبل استدعاء أي طرق أخرى في SDK.

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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.
  }
});

تم تسجيل مشروع الوحدة الخاص بك وتهيئته لاستخدام Firebase.

تفعيل دفع الإخطارات على منصات Apple

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

  1. انقر فوق المشروع في Xcode ، ثم حدد علامة التبويب "عام" من منطقة المحرر .

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

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

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

  1. انقر فوق المشروع في Xcode ، ثم حدد علامة التبويب "القدرات" من منطقة المحرر .

  2. قم بتبديل دفع الإخطارات إلى تشغيل .

  3. قم بالتمرير لأسفل إلى أوضاع الخلفية ، ثم قم بتبديلها إلى وضع التشغيل .

  4. حدد مربع الاختيار الإخطارات عن بعد ضمن أوضاع الخلفية .

قم بتهيئة Firebase Cloud Messaging

ستتم تهيئة مكتبة Firebase Cloud Message عند إضافة معالجات لأحداث 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 إلى تكوين إضافي.

يأتي المكون الإضافي 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);
}

تستخدم الإصدارات الجديدة من Firebase C ++ SDK (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. إذا كنت ترغب في الحصول على اشتراك صريح قبل استخدام الرمز المميز ، فيمكنك منع الإنشاء في وقت التهيئة عن طريق تعطيل FCM (وعلى Android ، Analytics). للقيام بذلك ، أضف قيمة بيانات وصفية إلى 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;

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

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

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

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