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

این راهنما نحوه شروع به کار با 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 — سطح API 23 (Marshmallow) یا بالاتر را هدف‌یابی می‌کند

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   شناسه پروژه Unity خود را کجا پیدا می‌کنید؟

   پروژه Unity خود را در Unity IDE باز کنید، سپس به بخش تنظیمات برای هر پلاتفرم پیمایش کنید:

   • برای iOS — به تنظیمات ساخت > iOS پیمایش کنید.

   • برای Android — به Android > تنظیمات پخش‌کننده > تنظیمات دیگر بروید.

   شناسه پروژه Unity شما مقدار شناسه بسته است (شناسه نمونه: com.yourcompany.yourproject).

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

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

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

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

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

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

   چه چیزی درباره این فایل پیکربندی باید بدانید؟

   • فایل پیکربندی Firebase حاوی شناسه‌های یکتا اما غیرمحرمانه برای پروژه و برنامه شما است. برای کسب اطلاعات بیشتر درباره این فایل پیکربندی، به آشنایی با پروژه‌های Firebase مراجعه کنید.

   • هرزمان بخواهید می‌توانید فایل پیکربندی Firebase را دوباره بارگیری کنید.

   • مطمئن شوید که نام فایل پیکربندی با نویسه‌های اضافی، مثل (2)، اضافه نشده باشد.

2. پنجره پروژه پروژه 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. در پنجره وارد کردن بسته Unity، روی وارد کردن کلیک کنید.

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

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

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

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

فعال کردن اعلان‌های لحظه‌ای در پلاتفرم‌های Apple

1. در Xcode، روی پروژه‌تان کلیک کنید، سپس برگه عمومی را از ناحیه ویرایشگر انتخاب کنید.
2. به چارچوب‌ها و کتابخانه‌های پیوندی پیمایش کنید، سپس روی دکمه + کلیک کنید تا چارچوبی اضافه کنید.
3. در پنجره‌ای که ظاهر می‌شود، به UserNotifications.framework پیمایش کنید، روی آن ورودی کلیک کنید، سپس روی افزودن کلیک کنید.
4. روی پروژه خود در Xcode کلیک کنید، سپس برگه قابلیت‌ها را از ناحیه ویرایشگر انتخاب کنید.
5. اعلان‌های لحظه‌ای را به روشن تغییر دهید.
6. به حالت‌های پس‌زمینه پیمایش کنید، سپس آن را به روشن تغییر دهید.
7. چارگوش اعلان‌های از دور را در زیر حالت‌های پس‌زمینه انتخاب کنید.

مقداردهی اولیه Firebase Cloud Messaging

فعال کردن ثبت‌نام بااستفاده از «شناسه نصب Firebase»

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

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

مدیریت پیام‌های دارای پیوند عمیق در Android

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 (و در 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.RegistrationOnInitEnabled = true;

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

مراحل بعدی

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

• ارسال پیام به دستگاه‌ها
• دریافت پیام در «کارخواه Unity»
• ارسال پیام‌های موضوعی