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

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

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

قبل البدء

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

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

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

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

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

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

• اضبط جهازًا أو استخدِم محاكيًا لتشغيل مشروع 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 (plat_unity) لبدء سير عمل الإعداد.

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

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

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

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

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

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

   افتح مشروعك على Unity في بيئة التطوير المتكاملة (IDE) في 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: إضافة حِزم Firebase Unity SDK

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

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

   لم يتم تفعيل Analytics

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

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

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

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

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

تحميل مفتاح مصادقة خدمة الإشعارات الفورية من Apple‏ (APNs)

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

1. في وحدة تحكّم "Firebase"، انتقِل إلى settings الإعدادات > إعدادات عامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.
2. في مفتاح مصادقة APNs ضمن إعداد تطبيق iOS، انقر على تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب توفير طريقة اتصال واحدة على الأقل.
3. انتقِل إلى الموقع الذي حفظت فيه المفتاح، واختَره، ثم انقر على فتح. أضِف رقم تعريف المفتاح (المتوفر في Apple Developer Member Center) وانقر على تحميل.

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

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

إعداد Firebase Cloud Messaging

تفعيل التسجيل باستخدام معرّف تثبيت Firebase

لتفعيل تسجيل مثيل تطبيقك باستخدام Firebase Cloud Messaging من خلال رقم تعريف التثبيت في Firebase (FID)، عليك أولاً تفعيل أرقام تعريف التثبيت في إعدادات تطبيقك على كلّ من منصتَي Android وApple:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

التسجيل في فعاليات "FCM"

سيتم تهيئة مكتبة Firebase Cloud Messaging عند إضافة معالِجات لأحداث RegistrationReceived أو MessageReceived.

عند بدء التشغيل، تسجِّل Firebase Cloud Messaging مثيل تطبيق العميل لتلقّي الرسائل باستخدام رقم تعريف عملية تثبيت Firebase (FID). يتلقّى التطبيق معرّف مثيل Firebase مع الحدث RegistrationReceived، والذي يجب تخزينه مؤقتًا على الخادم لاستهداف هذا الجهاز المحدّد للرسائل.

بالإضافة إلى ذلك، عليك التسجيل في الحدث OnMessageReceived إذا أردت أن تتمكّن من تلقّي الرسائل الواردة.

سيظهر الإعداد على النحو التالي:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

بعد الحصول على رقم تعريف التثبيت على Firebase، أرسِله إلى خادم تطبيقك وخزِّنه باستخدام طريقتك المفضّلة.

التسجيل يدويًا عند إيقاف ميزة "التهيئة التلقائية"

يمكنك أيضًا تفعيل التسجيل يدويًا باستخدام FCM في وقت التشغيل من خلال RegisterAsync():

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

الوصول إلى رمز التسجيل في FCM (متوقّف نهائيًا)

إذا كان تطبيقك لا يزال يستخدم واجهات برمجة التطبيقات المتوقّفة نهائيًا للرموز المميّزة، يمكنك الاستماع إلى TokenReceived:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

بدء الإعداد باستخدام أنظمة Android الأساسية

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

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

Firebase Cloud Messaging comes bundled with a custom entry point activity that replaces the default UnityPlayerActivity. إذا كنت لا تستخدم نقطة دخول مخصّصة، سيتم إجراء هذا الاستبدال تلقائيًا، ولن تحتاج إلى اتّخاذ أي إجراء إضافي.

تتضمّن 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 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);
}

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

وباختصار:

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

تسمح FCM بإرسال رسائل تحتوي على رابط عميق في تطبيقك. لتلقّي رسائل تحتوي على رابط عميق، عليك إضافة intent filter جديد إلى النشاط الذي يعالج الروابط العميقة في تطبيقك. يجب أن يرصد intent filter الروابط العميقة في نطاقك. في ملف 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 أكثر مرونة. على سبيل المثال:

<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>

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

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

تنشئ 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.RegistrationOnInitEnabled = true;

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

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

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

• إرسال الرسائل إلى الأجهزة
• تلقّي الرسائل في Unity Client
• إرسال رسائل المواضيع