Buka konsol

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 dapat digunakan di Android dan iOS, dengan beberapa penyiapan tambahan untuk masing-masing platform.

Sebelum memulai

Langkah 1: Menyiapkan lingkungan Anda

  • Instal Unity 5.3 atau yang lebih baru.

  • (Khusus iOS) Pastikan Anda memiliki akses ke kedua hal berikut:

    • Xcode 9.4.1 atau yang lebih baru
    • CocoaPods 1.4.0 atau yang lebih baru
  • Pastikan bahwa project Unity Anda menargetkan tingkat OS yang sesuai:

    • 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 - Untuk Firebase Cloud Messaging, Anda akan memerlukan:

      • Perangkat iOS fisik
      • Sertifikat APN dengan Notifikasi Push aktif
    • Untuk AndroidEmulator harus menggunakan image emulator dengan Google Play.

  • Login ke Firebase menggunakan akun Google Anda.

Jika belum memiliki project Unity, Anda dapat mendownload salah satu contoh quickstart kami jika Anda hanya ingin mencoba produk Firebase.

Langkah 2: Membuat 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 lebih lanjut project Firebase.

Langkah 3: Mendaftarkan project Unity dengan project Firebase Anda

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 penyiapan alur kerja.

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

  2. Pilih target built 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 4: Menambahkan file konfigurasi Firebase ke project Unity Anda

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

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

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

Langkah 5: Menambahkan Firebase SDK ke project Unity Anda

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

    • 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 kompresi zip-nya, pilih untuk mengimpor Firebase Cloud Messaging SDK (FirebaseMessaging.unitypackage).

    Anda juga dapat mengimpor produk Firebase lain yang didukung.

  4. Di jendela Import Unity Package, klik Import.

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

Langkah 6: Konfirmasikan persyaratan versi layanan Google Play

Firebase Unity SDK untuk Android memerlukan layanan Google Play, yang harus merupakan yang 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: Menambahkan 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: Mengaktifkan 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

Pustaka Firebase Cloud Messaging akan diinisialisasi saat menambahkan penangan untuk peristiwa TokenReceived atau MessageReceived.

Setelah inisialisasi, token pendaftaran diminta untuk instance aplikasi klien. Aplikasi akan menerima token tersebut dengan peristiwa OnTokenReceived, yang harus di-cache untuk digunakan nanti. Anda memerlukan token ini jika ingin menargetkan perangkat khusus ini untuk pesan.

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 Activity titik masuk Android

Di Android, Firebase Cloud Messaging dilengkapi dengan aktivitas titik masuk khusus yang menggantikan UnityPlayerActivity default. Jika Anda tidak menggunakan titik masuk khusus, penggantian ini terjadi secara otomatis dan Anda tidak perlu melakukan tindakan tambahan. Aplikasi yang tidak menggunakan Activity titik masuk default atau yang menyuplai Assets/Plugins/AndroidManifest.xml mereka sendiri akan memerlukan konfigurasi ekstra.

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

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar berisi peristiwa 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 proses aktivitas onStop, onRestart, atau menerapkan onNewIntent yang diperlukan agar Firebase Cloud Messaging mampu menangani pesan masuk dengan benar.

Mengonfigurasi Activity titik masuk khusus

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

Jika Anda menggunakan Activity kustom dan tidak menggunakan ekstensi com.google.firebase.MessagingUnityPlayerActivity, Anda harus menyertakan cuplikan berikut dalam Activity Anda.

/**
 * 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
 * receieved 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 menge-tap 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 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 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 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.