Menyiapkan aplikasi klien Firebase Cloud Messaging dengan Unity

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

Sebelum memulai

Prasyarat

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

• (Khusus platform Apple) Instal aplikasi berikut:

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

• Pastikan project Unity Anda memenuhi persyaratan berikut:

  • Untuk iOS — menarget iOS 13 atau versi yang lebih tinggi
  • Untuk tvOS - menargetkan tvOS 13 atau yang lebih baru
  • Untuk Android — menarget API level 21 (Lollipop) 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.

• Login ke Firebase menggunakan akun Google Anda.

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.

Membuat project Firebase

1. Di Firebase console, klik Add project.

   • Untuk menambahkan resource Firebase ke project Google Cloud yang sudah ada, masukkan nama project-nya atau pilih dari menu dropdown.

   • Untuk membuat project baru, masukkan nama project yang diinginkan. Anda juga dapat mengedit project ID yang ditampilkan di bawah nama project.

     Firebase menghasilkan ID unik untuk project Firebase Anda berdasarkan nama yang Anda berikan. Jika ingin mengedit project ID ini, Anda harus melakukannya sekarang karena project ID tidak dapat diubah setelah Firebase menyediakan resource untuk project Anda. Buka artikel Memahami Project Firebase untuk mempelajari cara Firebase menggunakan project ID.

2. Jika diminta, tinjau dan setujui persyaratan Firebase.

3. Klik Continue.

4. (Opsional) Siapkan Google Analytics untuk project Anda dan optimalkan penggunaan produk-produk Firebase berikut:

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Personalisasi Remote Config Firebase A/B Testing

   Pilih akun Google Analytics yang ada atau buat akun baru.

   Jika Anda membuat akun baru, pilih lokasi pelaporan Analytics, lalu setujui setelan berbagi data dan persyaratan Google Analytics untuk project Anda.

   Anda dapat sewaktu-waktu menyiapkan Google Analytics dari tab Integrations di Project settings Anda.

5. Klik Create project (atau Add Firebase, jika Anda menggunakan project Google Cloud yang sudah ada).

Firebase menyediakan resource untuk project Firebase Anda secara otomatis. Begitu selesai, Anda akan dibawa ke halaman ringkasan untuk project Firebase Anda di Firebase console.

Langkah 2: Daftarkan aplikasi Anda ke Firebase

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

Jika merilis game di iOS dan Android, daftarkan kedua target build project Unity Anda ke project Firebase yang sama. Jika memiliki beberapa varian build dengan ID paket iOS atau ID aplikasi Android yang berbeda, Anda harus mendaftarkan setiap varian ke project Firebase yang sama.

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.

   Catatan: Jika hanya mendaftarkan satu target build project Unity sekarang, Anda dapat kembali ke alur kerja penyiapan kapan saja untuk mendaftarkan target build lainnya.

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.

   Di mana lokasi ID project Unity?

   Buka project Unity di Unity IDE Anda, lalu buka bagian setelan untuk setiap platform:

   • Untuk iOS — Buka Build Settings > iOS.

   • Untuk Android — Buka Android > Player Settings > Other Settings.

   ID project Unity Anda adalah nilai Bundle Identifier (contoh ID: com.yourcompany.yourproject).

   Pastikan untuk memasukkan ID yang benar-benar digunakan project Anda. Nilai ID peka huruf besar/kecil, dan tidak dapat diubah untuk aplikasi Firebase ini setelah didaftarkan ke project Firebase Anda.

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 Daftarkan aplikasi.

Langkah 3: Tambahkan file konfigurasi Firebase

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

   Jika mendaftarkan target build project Unity untuk iOS dan Android, Anda harus mendownload dan menambahkan file konfigurasi untuk kedua platform.

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

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

   Apa yang perlu Anda ketahui tentang file konfigurasi ini?

   • File konfigurasi Firebase berisi ID unik, tetapi tidak bersifat rahasia, untuk project Anda. Untuk mempelajari file konfigurasi ini lebih lanjut, baca Memahami Project Firebase.

   • Anda dapat mendownload file konfigurasi Firebase lagi kapan saja.

   • Pastikan nama file konfigurasi tidak diberi karakter tambahan, seperti (2).

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 bersifat khusus untuk platform tertentu.

2. Pada project Unity yang terbuka, buka Aset > Impor Paket > Paket Kustom.

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

   Untuk mengoptimalkan penggunaan Firebase Cloud Messaging, sebaiknya aktifkan Google Analytics di project Anda. Selain itu, sebagai bagian dari penyiapan Analytics, Anda perlu 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 aktif

   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.

Penting: Saat menggunakan Firebase Unity SDK untuk iOS, jangan nonaktifkan method swizzling. Swizzling diperlukan oleh SDK. Jika dinonaktifkan, fitur-fitur penting Firebase (seperti penanganan token FCM) tidak akan berfungsi dengan benar.

Langkah 5: Konfirmasi persyaratan versi layanan Google Play

Firebase Unity SDK untuk Android memerlukan Google Play services, yang harus diperbarui sebelum SDK dapat digunakan.

Tambahkan pernyataan using dan kode inisialisasi berikut di awal aplikasi Anda. Anda dapat memeriksa dan mengupdate Google Play services secara opsional ke versi yang diperlukan oleh Firebase Unity SDK sebelum memanggil metode lain di 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.
  }
});

Project Unity Anda sudah terdaftar dan dikonfigurasi untuk menggunakan Firebase.

Buka bagian Menambahkan Firebase ke project Unity untuk:

• Pelajari Produk Firebase yang didukung oleh Firebase Unity SDK.
• Menyiapkan alur kerja desktop untuk project Unity.
• Memecahkan masalah umum.

Mengupload kunci autentikasi APNs untuk dukungan Apple

Upload kunci autentikasi APN Anda ke Firebase. Jika Anda belum memiliki kunci autentikasi APN, pastikan untuk membuatnya di Apple Developer Member Center.

1. Pada project Anda di Firebase console, pilih ikon roda gigi, pilih Project Settings, lalu pilih tab Cloud Messaging.

2. Di APNs authentication key di bagian iOS app configuration, klik tombol Upload.

3. Cari lokasi penyimpanan kunci, pilih lokasi tersebut, lalu klik Open. Tambahkan ID kunci tersebut (tersedia di Apple Developer Member Center) dan klik Upload.

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.

Lakukan inisialisasi 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 entri 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 kosong.

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.

Menangani Pesan dengan Deep Link di Android

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. Contoh:

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

• Mengirimkan pesan topik
• Mengirimkan pesan ke grup perangkat
• Mengirimkan pesan upstream

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