شروع به کار با «پیام‌رسانی ابریِ Firebase» در برنامه‌های Unity

انتخاب پلاتفرم: iOS+ Android وب Flutter Unity C++


این راهنما نحوه شروع به کار با Firebase Cloud Messaging در برنامه‌های مشتری Unity را شرح می‌دهد تا بتوانید پیام‌ها را به‌طور مطمئن ارسال کنید.

برای نوشتن برنامه کارخواه Firebase Cloud Messaging چندپلاتفرمی با Unity، از میانای برنامه‌سازی کاربردی Firebase Cloud Messaging استفاده کنید. کیت توسعه نرم‌افزار Unity برای Android و Apple کار می‌کند، اما برای هر پلاتفرم به چند راه‌اندازی دیگر نیاز است.

قبل از شروع

پیش‌نیازها

  • ‫Unity 2021 LTS یا نسخه‌های جدیدتر را نصب کنید. نسخه‌های قبلی نیز ممکن است سازگار باشند اما به‌طور فعال پشتیبانی نخواهند شد.

  • (فقط پلاتفرم‌های Apple) موارد زیر را نصب کنید:

    • Xcode نسخه ۲۶.۲ یا بالاتر
    • CocoaPods نسخه ۱.۱۲.۰ یا بالاتر

  • مطمئن شوید که پروژه Unity شما این الزامات را برآورده می‌کند:

    • ویژه iOS — iOS 15 یا بالاتر را هدف قرار می‌دهد
    • برای tvOS - tvOS 15 یا بالاتر را هدف قرار می‌دهد
    • برای Android — میانای برنامه‌سازی کاربردی سطح ۲۴ (Nougat) یا بالاتر را هدف قرار می‌دهد

  • برای اجرای پروژه Unity، دستگاهی را راه‌اندازی کنید یا از شبیه‌ساز استفاده کنید.

    • برای iOS یا tvOS — یک دستگاه فیزیکی برای اجرای برنامه خود راه‌اندازی کنید و این وظایف را تکمیل کنید:

      • «کلید اصالت‌سنجی اعلان لحظه‌ای Apple» را برای حساب توسعه‌دهنده Apple خود دریافت کنید.
      • «اعلان‌های لحظه‌ای» را در XCode در بخش برنامه > قابلیت‌ها فعال کنید.

    • برای Android — شبیه‌سازها باید از تصویر شبیه‌ساز با Google Play استفاده کنند.

اگر ازقبل پروژه Unity ندارید و فقط می‌خواهید محصول Firebase را امتحان کنید، می‌توانید یکی از نمونه‌های شروع سریع ما را بارگیری کنید.

مرحله ۱: ایجاد پروژه Firebase

قبل‌از اینکه بتوانید Firebase را به پروژه Unity خود اضافه کنید، باید پروژه Firebase ای بسازید تا به پروژه Unity خود متصل کنید. برای کسب اطلاعات بیشتر درباره پروژه‌های Firebase، به آشنایی با پروژه‌های Firebase مراجعه کنید.

مرحله ۲: ثبت برنامه در Firebase

می‌توانید یک یا چند برنامه یا بازی را برای اتصال به پروژه Firebase خود ثبت کنید.

  1. به کنسول Firebase بروید.

  2. در مرکز صفحه نمای کلی پروژه، روی نماد Unity () کلیک کنید تا گردش کار راه‌اندازی شروع شود.

    اگر قبلاً برنامه‌ای به پروژه Firebase خود اضافه کرده‌اید، روی افزودن برنامه کلیک کنید تا گزینه‌های پلاتفرم نمایش داده شود.

  3. هدف ساخت پروژه Unity خود را که می‌خواهید ثبت کنید انتخاب کنید، یا حتی می‌توانید انتخاب کنید که هر دو هدف را اکنون به‌طور هم‌زمان ثبت کنید.

  4. شناسه(های) مختص پلاتفرم پروژه Unity خود را وارد کنید.

    • برای iOS — شناسه iOS پروژه Unity خود را در فیلد شناسه بسته iOS وارد کنید.

    • برای Android — شناسه Android پروژه Unity خود را در فیلد نام بسته Android وارد کنید.
      اصطلاحات نام بسته و شناسه برنامه اغلب به‌جای یکدیگر استفاده می‌شوند.

  5. (اختیاری) نام(های) مستعار مختص پلاتفرم پروژه Unity خود را وارد کنید.
    این نام‌های مستعار شناسه‌های داخلی و راحتی هستند و فقط برای شما در کنسول Firebase قابل‌مشاهده هستند.

  6. روی ثبت برنامه کلیک کنید.

مرحله ۳: افزودن فایل‌های پیکربندی Firebase

  1. فایل(های) پیکربندی Firebase مختص پلاتفرم خود را در گردش کار راه‌اندازی کنسول Firebase دریافت کنید.

    • برای iOS — روی بارگیری GoogleService-Info.plist کلیک کنید.

    • برای Android — روی بارگیری google-services.json کلیک کنید.

  2. پنجره Project پروژه Unity را باز کنید، سپس فایل(های) پیکربندی را به پوشه Assets منتقل کنید.

  3. به کنسول Firebase برگردید و در گردش کار راه‌اندازی، روی بعدی کلیک کنید.

مرحله ۴: افزودن کیت‌های توسعه نرم‌افزار Firebase در Unity

  1. در کنسول Firebase، روی بارگیری کیت توسعه نرم‌افزار Firebase Unity کلیک کنید، سپس کیت توسعه نرم‌افزار را در جایی مناسب از حالت فشرده خارج کنید.

    • هرزمان بخواهید می‌توانید Firebase Unity SDK را دوباره بارگیری کنید.

    • کیت توسعه نرم‌افزار Firebase Unity مختص پلاتفرم نیست.

  2. در پروژه Unity بازشده، به دارایی‌ها > وارد کردن بسته > بسته سفارشی بروید.

  3. از کیت توسعه نرم‌افزار ازحالت فشرده خارج‌شده، محصولات پشتیبانی‌شده 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، روی Import کلیک کنید.

  5. به کنسول Firebase برگردید و در گردش کار راه‌اندازی، روی بعدی کلیک کنید.

مرحله ۵: تأیید کردن الزامات نسخه «خدمات Google Play»

برخی‌از محصولات در کیت توسعه نرم‌افزار Firebase Unity برای Android به Google Play services نیاز دارند. ببینید کدام محصولات این وابستگی را دارند. Google Play services باید به‌روز باشد تا بتوان از آن محصولات استفاده کرد.

عبارت using و کد مقداردهی اولیه زیر را در ابتدای برنامه‌تان اضافه کنید. می‌توانید قبل‌از فراخوانی هر روش دیگری در کیت توسعه نرم‌افزار، Google Play services را به نسخه موردنیاز بررسی و درصورت تمایل به‌روزرسانی کنید.

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، از دستورالعمل‌های زیر استفاده کنید.

بارگذاری کلید اصالت‌سنجی APN

کلید اصالت‌سنجی APNs را در Firebase بارگذاری کنید. اگر ازقبل کلید اصالت‌سنجی APN ندارید، حتماً یکی در مرکز اعضای توسعه‌دهنده Apple ایجاد کنید.

  1. در کنسول Firebase، به تنظیمات > موارد کلی بروید. سپس، روی زبانه «پیام‌رسانی ابری» کلیک کنید.
  2. در کلید اصالت‌سنجی APNs در بخش پیکربندی برنامه iOS، روی بارگذاری کلیک کنید تا کلید اصالت‌سنجی توسعه، یا کلید اصالت‌سنجی تولید، یا هر دو را بارگذاری کنید. حداقل یکی لازم است.
  3. به مکانی که کلیدتان را ذخیره کرده‌اید بروید، آن را انتخاب کنید، و روی باز کردن کلیک کنید. شناسه کلید را برای کلید (در مرکز اعضای توسعه‌دهنده Apple دردسترس است) اضافه کنید و روی بارگذاری کلیک کنید.

فعال کردن اعلان‌های لحظه‌ای در پلاتفرم‌های 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)، ابتدا باید شناسه‌های نصب Firebase را در پیکربندی برنامه‌تان برای هر دو پلاتفرم Android و Apple فعال کنید:

Android

عنصر <meta-data> زیر را به عنصر <application> در AndroidManifest.xml خود اضافه کنید:

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

Swift

کلید FirebaseMessagingInstallationIdEnabled را به Info.plist اضافه کنید و آن را روی YES تنظیم کنید:

FirebaseMessagingInstallationIdEnabled = YES

برای FCM رویداد ثبت‌نام کنید

کتابخانه Firebase Cloud Messaging هنگام افزودن مدیریت‌کننده‌ها برای رویدادهای RegistrationReceived یا MessageReceived مقداردهی اولیه خواهد شد.

در زمان مقداردهی اولیه، Firebase Cloud Messaging نمونه برنامه کارخواه را برای دریافت پیام بااستفاده از شناسه نصب Firebase (FID) ثبت می‌کند. برنامه ‫FID را با رویداد 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 با فعالیت نقطه ورودی سفارشی همراه است که جایگزین 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 (از ۷.۱.۰ به بعد) از 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 تهی خواهد بود.

به‌طور خلاصه:

وضعیت برنامه اعلان Data هردو
پیش‌زمینه 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 (و Analytics در 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.RegistrationOnInitEnabled = true;

این مقدار پس‌از تنظیم، در بازراه‌اندازی‌های برنامه حفظ می‌شود.

مراحل بعدی

پس‌از تکمیل مراحل راه‌اندازی، در اینجا چند گزینه برای پیشبرد کار با FCM برای Unity آورده شده است: