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

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

برای نوشتن برنامه کارخواه چندسکویی Firebase Cloud Messaging با Unity، از Firebase Cloud Messaging API استفاده کنید. کیت توسعه نرم‌افزار 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 (plat_unity) کلیک کنید تا گردش کار راه‌اندازی شروع شود.

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

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

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

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

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

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

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

   • برای iOS — به Build Settings (تنظیمات ساخت) > 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. پنجره Project پروژه Unity را باز کنید، سپس فایل(های) پیکربندی را به پوشه Assets منتقل کنید.

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

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

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

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

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

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

1. در کنسول Firebase، به settings تنظیمات > موارد کلی بروید. سپس، روی برگه پیام‌رسانی ابری کلیک کنید.
2. در کلید اصالت‌سنجی APN در بخش پیکربندی برنامه 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)، باید ابتدا 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) ثبت می‌کند. برنامه 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 (نسخه ۷.۱.۰ به بعد) از 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 (و Analytics در 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
• ارسال پیام‌های موضوع