Menyiapkan aplikasi klien Firebase Cloud Messaging dengan Unity

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

Sebelum memulai

Prasyarat

  • Instal Unity 5.3 atau yang lebih baru.

  • (khusus iOS) Instal aplikasi berikut:

    • Xcode 9.4.1 atau yang lebih baru
    • CocoaPods 1.4.0 atau yang lebih baru
  • Pastikan project Unity Anda memenuhi persyaratan berikut:

    • Untuk iOS — menargetkan iOS 8 atau yang lebih baru
    • Untuk Android — menargetkan API level 16 (Jelly Bean) atau yang lebih baru
  • Siapkan perangkat atau emulator untuk menjalankan project Unity Anda.

    • Untuk iOS — Siapkan perangkat iOS fisik atau simulator iOS untuk menjalankan aplikasi Anda.

      • Untuk Cloud Messaging, selesaikan tugas-tugas berikut:

        • Siapkan perangkat iOS fisik.
        • Dapatkan Kunci Autentikasi Apple Notifikasi Push untuk akun Developer Apple.
        • Di XCode, aktifkan Notifikasi Push di App > Capabilities.
      • Untuk semua produk Firebase lainnya, Anda dapat menggunakan perangkat iOS fisik atau simulator iOS.

    • Untuk AndroidEmulator harus menggunakan image emulator dengan Google Play.

  • Login ke Firebase menggunakan akun Google Anda.

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

Langkah 1: Buat project Firebase

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

Langkah 2: Daftarkan project Unity dengan Firebase

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

  1. Di tengah halaman ringkasan project Firebase console, klik ikon Unity untuk meluncurkan alur kerja penyiapan.

    Jika Anda sudah menambahkan aplikasi ke project Firebase, klik Tambahkan aplikasi untuk menampilkan opsi platform.

  2. Pilih target build dari project Unity Anda yang ingin didaftarkan, atau Anda bahkan dapat memilih untuk mendaftarkan kedua target sekarang.

  3. Masukkan ID khusus platform project Unity Anda.

    1. Buka project Unity Anda di Unity IDE.

    2. Buka Build Settings > iOS atau Android > Player Settings > Other Settings.

      ID project Unity adalah nilai ID Paket. (contoh ID: com.yourcompany.unity-project-name)

    3. Masukkan setiap ID khusus platform di kolom yang sesuai:

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

      • Untuk Android — Masukkan ID Android project Unity Anda di kolom nama paket Android.

        • Istilah nama paket dan ID aplikasi sering kali digunakan secara bergantian.
  4. (Opsional) Masukkan nama pengguna khusus platform project Unity Anda.

    Nama pengguna ini bersifat internal, ID yang memudahkan dan hanya dapat dilihat oleh Anda di Firebase console.

  5. Klik Daftarkan aplikasi.

Langkah 3: Tambahkan file konfigurasi Firebase ke project Unity Anda

  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 dari project Unity Anda, lalu pindahkan file konfigurasi Anda ke dalam Assets folder.

    • Sebelum memindahkan file konfigurasi, pastikan file konfigurasi tidak ditambahkan dengan karakter tambahan, seperti (2).
    • Anda dapat menempatkan file konfigurasi Firebase di mana saja dalam folder Assets.
  3. Kembali ke Firebase console, di alur kerja penyiapan, klik Berikutnya.

Langkah 4: Tambahkan Firebase SDK ke project Unity Anda

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

    • Anda dapat mendownload Firebase Unity SDK lagi kapan saja.

    • Firebase Unity SDK tidak khusus platform.

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

  3. Dari SDK yang telah dibuka kompresinya, 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. Sebagai bagian dari penyiapan Google Analytics, Anda perlu menambahkan paket Firebase untuk Google 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 Berikutnya.

Langkah 5: Konfirmasikan persyaratan versi layanan Google Play

Firebase Unity SDK di Android memerlukan layanan Google Play versi terbaru sebelum 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.

Langkah 7: 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 8: 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 penangan 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 perangkat tertentu untuk pesan.

Selain itu, Anda harus mendaftar untuk peristiwa OnMessageReceived jika Anda 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 Activity titik masuk Android

Di Android, Firebase Cloud Messaging dilengkapi dengan aktivitas titik masuk 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 masuk default atau yang menyuplai Assets/Plugins/AndroidManifest.xml mereka sendiri akan memerlukan konfigurasi ekstra.

Plugin Unity Firebase Cloud Messaging di Android sudah sepaket dengan 2 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.

File ini disediakan karena UnityPlayerActivity default tidak menangani transisi siklus hidup aktivitas onStop, 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 dari Android Activity Lifecycle dengan benar (contoh cara melakukannya ditunjukkan di bawah ini). Jika aktivitas kustom Anda merupakan ekstensi UnityPlayerActivity, sebagai gantinya Anda dapat menggunakan com.google.firebase.MessagingUnityPlayerActivity yang menerapkan semua metode yang diperlukan.

Jika Anda menggunakan Aktivitas kustom dan tidak menggunakan ekstensi 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());
  startService(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);
}

Catatan tentang pengiriman pesan di Android

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

Untuk pesan yang diterima saat aplikasi berada di latar belakang, isinya akan diambil dari kolom notifikasi dan digunakan untuk mengisi notifikasi baki sistem. Namun, isi notifikasi tersebut tidak akan disampaikan ke FCM. Artinya, FirebaseMessage.Notification akan kosong.

Rangkuman:

Status aplikasi Notification 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 dari intent.

Mencegah inisialisasi otomatis

FCM menghasilkan ID Instance yang digunakan sebagai token pendaftaran dalam FCM. Ketika ID Instance dibuat, library akan mengupload ID tersebut dan data konfigurasi ke Firebase. Jika ingin mendapatkan keikutsertaan eksplisit sebelum menggunakan ID Instance, 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 iOS, atau AndroidManifest.xml Anda 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>

iOS

FirebaseMessagingAutoInitEnabled = NO

Untuk mengaktifkan kembali FCM, Anda dapat membuat panggilan runtime:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Nilai ini akan tetap ada 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 dalam 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 menge-tap 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 sampel panduan mulai cepat yang mendemonstrasikan fungsi 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 server untuk menggunakan fitur ini.