Menyiapkan aplikasi klien Firebase Cloud Messaging dengan Unity

Untuk menulis aplikasi klien Firebase Cloud Messaging lintas platform dengan Unity, gunakan Firebase Cloud Messaging API. Unity SDK berfungsi di Android dan Apple, dengan beberapa penyiapan tambahan untuk setiap platform.

Sebelum memulai

Prasyarat

  • Instal Unity 2019.1 atau yang lebih baru. Versi sebelumnya mungkin juga kompatibel, tetapi tidak akan didukung terus-menerus. Dukungan untuk Unity 2019.1 dianggap tidak digunakan lagi, dan tidak akan lagi didukung secara aktif setelah rilis utama berikutnya.

  • (Khusus platform Apple) Instal aplikasi berikut:

    • Xcode 13.3.1 atau versi yang lebih tinggi
    • CocoaPods 1.10.0 atau versi yang lebih tinggi

  • Pastikan project Unity Anda memenuhi persyaratan berikut:

    • Untuk iOS — menargetkan iOS 11 atau versi yang lebih tinggi
    • Untuk tvOS - menargetkan tvOS 12 atau yang lebih baru
    • Untuk Android — menargetkan API level 19 (KitKat) atau versi yang lebih tinggi

  • Siapkan perangkat atau gunakan emulator untuk menjalankan project Unity Anda.

    • Untuk iOS atau tvOS — Siapkan perangkat fisik untuk menjalankan aplikasi Anda, dan selesaikan tugas-tugas berikut:

      • Dapatkan Kunci Autentikasi Notifikasi Push Apple untuk akun Apple Developer.
      • Di XCode, aktifkan Push Notifications di bagian App > Capabilities.

    • Untuk Android — Emulator harus menggunakan image emulator dengan Google Play.

Jika belum memiliki project Unity dan hanya ingin mencoba produk Firebase, download salah satu contoh panduan memulai.

Langkah 1: Buat project Firebase

Agar dapat menambahkan Firebase ke project Unity, Anda perlu membuat project Firebase untuk dihubungkan ke project Unity. Buka bagian Memahami Project Firebase untuk mempelajari project Firebase lebih lanjut.

Langkah 2: Daftarkan aplikasi ke Firebase

Anda dapat mendaftarkan satu atau beberapa aplikasi atau game untuk dihubungkan dengan project Firebase Anda.

  1. Buka Firebase console.

  2. Di bagian tengah halaman ringkasan project, klik ikon Unity () untuk meluncurkan alur kerja penyiapan.

    Jika sudah menambahkan aplikasi ke project Firebase, klik Add app untuk menampilkan opsi platform.

  3. Pilih target build project Unity yang ingin Anda daftarkan, atau Anda bahkan dapat memilih untuk mendaftarkan kedua target sekaligus.

  4. Masukkan ID khusus platform project Unity Anda.

    • Untuk iOS — Masukkan ID iOS project Unity Anda di kolom iOS bundle ID.

    • Untuk Android — Masukkan ID Android project Unity Anda di kolom Android package name.
      Istilah nama paket dan ID aplikasi memiliki arti yang sama.

  5. (Opsional) Masukkan nama panggilan khusus platform project Unity Anda.
    Nama panggilan ini adalah ID internal praktis yang hanya terlihat oleh Anda di Firebase console.

  6. Klik Register app.

Langkah 3: Tambahkan file konfigurasi Firebase

  1. Dapatkan file konfigurasi Firebase khusus platform Anda di alur kerja penyiapan Firebase console.

    • Untuk iOS — Klik Download GoogleService-Info.plist.

    • Untuk Android — Klik Download google-services.json.

  2. Buka jendela Project untuk project Unity Anda, lalu pindahkan file konfigurasi ke folder Assets.

  3. Kembali ke Firebase console, di alur kerja penyiapan, klik Next.

Langkah 4: Tambahkan Firebase Unity SDK

  1. Di Firebase console, klik Download Firebase Unity SDK, lalu ekstrak SDK di tempat yang mudah diakses.

    • Anda dapat mendownload Firebase Unity SDK lagi kapan saja.

    • Firebase Unity SDK tidak khusus untuk platform tertentu.

  2. Di dalam project Unity, buka Assets > Import Package > Custom Package.

  3. Dari SDK yang telah diekstrak, pilih produk Firebase yang didukung yang ingin digunakan dalam aplikasi Anda.

    Untuk mendapatkan pengalaman yang optimal saat menggunakan Firebase Cloud Messaging, sebaiknya aktifkan Google Analytics di project Anda. Selain itu, sebagai bagian dari penyiapan Analytics, Anda harus menambahkan paket Firebase untuk Analytics ke aplikasi Anda.

    Analytics diaktifkan

    • Tambahkan paket Firebase untuk Google Analytics: FirebaseAnalytics.unitypackage
    • Tambahkan paket untuk Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Analytics tidak diaktifkan

    Tambahkan paket untuk Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. Di jendela Import Unity Package, klik Import.

  5. Kembali ke Firebase console, di alur kerja penyiapan, klik Next.

Langkah 5: Konfirmasi persyaratan versi layanan Google Play

Firebase Unity SDK untuk Android memerlukan layanan Google Play versi terbaru agar SDK dapat digunakan.

Tambahkan kode berikut di awal aplikasi Anda. Anda dapat memeriksa dan mengupdate layanan Google Play secara opsional ke versi yang diperlukan oleh Firebase Unity SDK sebelum memanggil metode lain di SDK.

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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.
  }
});

Project Unity Anda sudah terdaftar dan dikonfigurasi untuk menggunakan Firebase.

Mengaktifkan notifikasi push di platform Apple

Langkah 1: Tambahkan framework notifikasi pengguna

  1. Klik project di Xcode, lalu pilih tab General dari Editor area.

  2. Scroll ke bawah ke Linked Frameworks and Libraries, lalu klik tombol + untuk menambahkan framework.

  3. Di jendela yang muncul, scroll ke UserNotifications.framework, klik entri tersebut, lalu klik Add.

Langkah 2: Aktifkan notifikasi push

  1. Klik project di Xcode, lalu pilih tab Capabilities dari Editor area.

  2. Alihkan Push Notifications ke On.

  3. Scroll ke bawah ke Background Modes, lalu alihkan ke On.

  4. Pilih kotak centang Remote notifications di bagian Background Modes.

Menginisialisasi Firebase Cloud Messaging

Library Firebase Cloud Messaging akan diinisialisasi saat menambahkan pengendali untuk peristiwa TokenReceived atau MessageReceived.

Setelah diinisialisasi, token pendaftaran akan diminta untuk instance aplikasi klien. Aplikasi akan menerima token dengan peristiwa OnTokenReceived, yang harus disimpan dalam cache untuk digunakan nanti. Anda akan memerlukan token ini jika ingin menargetkan pesan ke perangkat khusus ini.

Selain itu, Anda harus mendaftar ke peristiwa OnMessageReceived jika ingin dapat menerima pesan masuk.

Seluruh penyiapan ini akan tampak seperti berikut:

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);
}

Mengonfigurasi Aktivitas titik masuk Android

Di Android, Firebase Cloud Messaging dilengkapi dengan aktivitas titik masuk kustom yang menggantikan UnityPlayerActivity default. Jika Anda tidak menggunakan titik masuk kustom, penggantian ini terjadi secara otomatis dan Anda tidak perlu melakukan tindakan tambahan. Aplikasi yang tidak menggunakan Aktivitas titik entri default atau yang menyediakan Assets/Plugins/AndroidManifest.xml-nya sendiri akan memerlukan konfigurasi tambahan.

Plugin Unity Firebase Cloud Messaging di Android dilengkapi dengan dua file tambahan:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar berisi aktivitas yang disebut MessagingUnityPlayerActivity yang menggantikan UnityPlayerActivity standar.
  • Assets/Plugins/Android/AndroidManifest.xml memerintahkan aplikasi untuk menggunakan MessagingUnityPlayerActivity sebagai titik masuk ke aplikasi.

Kedua file ini disediakan karena UnityPlayerActivity default tidak menangani onStop, transisi siklus proses aktivitas onRestart, atau menerapkan onNewIntent yang diperlukan agar Firebase Cloud Messaging dapat menangani pesan masuk dengan benar.

Mengonfigurasi Aktivitas titik masuk kustom

Jika aplikasi Anda tidak menggunakan UnityPlayerActivity default, Anda harus menghapus AndroidManifest.xml yang disediakan dan memastikan bahwa aktivitas kustom menangani semua transisi Android Activity Lifecycle dengan benar (contoh cara melakukannya ditunjukkan di bawah ini). Jika aktivitas kustom Anda memperluas UnityPlayerActivity, sebagai gantinya Anda dapat memperluas com.google.firebase.MessagingUnityPlayerActivity yang menerapkan semua metode yang diperlukan.

Jika menggunakan Aktivitas kustom dan tidak memperluas com.google.firebase.MessagingUnityPlayerActivity, Anda harus menyertakan cuplikan berikut di Aktivitas.

/**
 * 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 versi baru (7.1.0 dan berikutnya) menggunakan JobIntentService yang memerlukan modifikasi tambahan di file AndroidManifest.xml.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Catatan tentang pengiriman pesan di Android

Saat aplikasi tidak berjalan sama sekali dan pengguna mengetuk sebuah notifikasi, secara default pesannya tidak dirutekan melalui callback bawaan FCM. Dalam kasus ini, payload pesan diterima melalui Intent yang digunakan untuk memulai aplikasi.

Untuk pesan yang diterima saat aplikasi berada di latar belakang, isi kolom notifikasinya akan digunakan untuk mengisi notifikasi baki sistem. Namun, isi notifikasi tersebut tidak akan disampaikan ke FCM. Artinya, FirebaseMessage.Notification akan berupa null.

Rangkuman:

Status aplikasi Notifikasi Data Keduanya
Latar depan Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Latar belakang Baki sistem Firebase.Messaging.FirebaseMessaging.MessageReceived Notifikasi: baki sistem
Data: di bagian tambahan intent.

Mencegah inisialisasi otomatis

FCM membuat token pendaftaran untuk penargetan perangkat. Saat token dibuat, library mengupload ID dan data konfigurasi ke Firebase. Jika menginginkan keikutsertaan eksplisit sebelum menggunakan token, Anda dapat mencegah pembuatan pada waktu konfigurasi dengan menonaktifkan FCM (dan di Android, Analytics). Untuk melakukan ini, tambahkan nilai metadata ke Info.plist (bukan GoogleService-Info.plist) di Apple, atau AndroidManifest.xml di 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

Untuk mengaktifkan kembali FCM, Anda dapat membuat panggilan runtime:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Nilai ini akan tetap sama setiap kali aplikasi dimulai ulang.

FCM memungkinkan pengiriman pesan yang berisi deep link ke aplikasi Anda. Untuk menerima pesan yang berisi deep link, Anda harus menambahkan filter intent baru ke aktivitas yang menangani deep link untuk aplikasi Anda. Filter intent harus menangkap deep link domain Anda. Jika pesan Anda tidak mengandung deep link, konfigurasi ini tidak diperlukan. Pada 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>

Anda juga dapat menentukan karakter pengganti agar filter intent lebih fleksibel. Misalnya:

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

Ketika pengguna mengetuk notifikasi yang berisi link ke skema dan host yang Anda tentukan, aplikasi akan memulai aktivitas dengan filter intent ini untuk menangani link.

Langkah berikutnya

Setelah menyiapkan aplikasi klien, Anda siap mengirimkan pesan downstream dan topik dengan Firebase. Untuk mempelajari lebih lanjut, lihat contoh panduan memulai yang menunjukkan fungsionalitas ini.

Untuk menambahkan perilaku lain yang lebih canggih ke aplikasi Anda, lihat panduan mengenai cara mengirimkan pesan dari server aplikasi:

Perlu diingat bahwa Anda memerlukan penerapan pada server untuk menggunakan fitur ini.