قم بإعداد تطبيق عميل 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.12.0 أو أعلى
  • تأكد من أن مشروع Unity الخاص بك يلبي هذه المتطلبات:

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

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

      • احصل على مفتاح مصادقة إشعارات Apple Push لحساب 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، انقر فوق تنزيل 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.

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

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

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

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

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

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

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

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

تهيئة خدمة المراسلة السحابية من Firebase

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

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

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

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

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