Siapkan 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 untuk Android dan Apple, dengan beberapa penyiapan tambahan yang diperlukan untuk setiap platform.

Sebelum kamu memulai

Prasyarat

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

• (Hanya platform Apple) Instal yang berikut ini:

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

• Pastikan project Unity Anda memenuhi persyaratan berikut:

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

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

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

    • Dapatkan Kunci Autentikasi Notifikasi Push Apple untuk akun Pengembang Apple Anda.
    • Aktifkan Push Notifications di XCode di bawah App > Capabilities .

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

• Masuk ke Firebase menggunakan akun Google Anda.

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

Langkah 1: Buat proyek Firebase

Sebelum Anda dapat menambahkan Firebase ke proyek Unity Anda, Anda perlu membuat proyek Firebase untuk terhubung ke proyek Unity Anda. Kunjungi Memahami Proyek Firebase untuk mempelajari lebih lanjut tentang proyek Firebase.

Langkah 2: Daftarkan aplikasi Anda ke Firebase

Anda dapat mendaftarkan satu atau beberapa aplikasi atau game untuk terhubung dengan proyek Firebase Anda.

1. Buka konsol Firebase .

2. Di tengah halaman ikhtisar proyek, klik ikon Unity ( plat_unity ) untuk meluncurkan alur kerja penyiapan.

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

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

4. Masukkan ID khusus platform project Unity Anda.

   • Untuk iOS — Masukkan ID iOS project Unity Anda di bidang ID bundel iOS .

   • Untuk Android — Masukkan ID Android proyek Unity Anda di kolom nama paket Android .
     Istilah nama paket dan ID aplikasi sering digunakan secara bergantian.

   Di mana Anda menemukan ID proyek Unity Anda?

   Buka proyek Unity Anda di Unity IDE Anda, lalu arahkan ke bagian pengaturan untuk setiap platform:

   • Untuk iOS — Buka Build Settings > iOS .

   • Untuk Android — Navigasikan ke Android > Pengaturan Pemain > Pengaturan Lainnya .

   ID proyek Unity Anda adalah nilai Pengenal Bundel (contoh ID: com.yourcompany.yourproject ).

5. (Opsional) Masukkan nama panggilan khusus platform project Unity Anda.
   Nama panggilan ini adalah pengidentifikasi kenyamanan internal dan hanya dapat dilihat oleh Anda di konsol Firebase.

6. Klik Daftarkan aplikasi .

Langkah 3: Tambahkan file konfigurasi Firebase

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

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

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

   Apa yang perlu Anda ketahui tentang file konfigurasi ini?

   • File konfigurasi Firebase berisi pengidentifikasi unik namun tidak rahasia untuk proyek Anda. Untuk mempelajari lebih lanjut tentang file konfigurasi ini, kunjungi Memahami Proyek Firebase .

   • Anda dapat mengunduh kembali file konfigurasi Firebase Anda kapan saja.

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

2. Buka jendela Proyek proyek Unity Anda, lalu pindahkan file konfigurasi Anda ke folder Assets .

3. Kembali ke konsol Firebase, di alur kerja penyiapan, klik Berikutnya .

Langkah 4: Tambahkan Firebase Unity SDK

1. Di konsol Firebase, klik Download Firebase Unity SDK , lalu unzip SDK di tempat yang nyaman.

   • Anda dapat mendownload Firebase Unity SDK lagi kapan saja.

   • Firebase Unity SDK tidak khusus platform.

2. Di proyek Unity Anda yang terbuka, navigasikan ke Assets > Import Package > Custom Package .

3. Dari SDK yang telah dibuka zipnya, pilih produk Firebase yang didukung yang ingin Anda gunakan di aplikasi Anda.

   Untuk pengalaman optimal dengan Firebase Cloud Messaging, sebaiknya aktifkan Google Analytics di proyek 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 diaktifkan

   Tambahkan paket untuk Firebase Cloud Messaging: FirebaseMessaging.unitypackage

4. Di jendela Import Unity Package , klik Import .

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

Langkah 5: Konfirmasi persyaratan versi layanan Google Play

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

Tambahkan kode berikut di awal aplikasi Anda. Anda dapat memeriksa dan secara opsional mengupdate layanan Google Play 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.
  }
});

Proyek Unity Anda terdaftar dan dikonfigurasi untuk menggunakan Firebase.

Langkah 7: Tambahkan kerangka pemberitahuan pengguna

1. Klik proyek di Xcode, lalu pilih tab Umum dari area Editor .

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

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

2. Alihkan Notifikasi Push ke Aktif .

3. Gulir ke bawah ke Mode Latar Belakang , lalu aktifkan .

4. Pilih kotak centang Notifikasi jarak jauh di bawah Mode Latar Belakang .

Inisialisasi Firebase Cloud Messaging

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

Setelah inisialisasi, token pendaftaran diminta untuk instance aplikasi klien. Aplikasi akan menerima token 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 untuk acara OnMessageReceived jika ingin dapat menerima pesan masuk.

Seluruh pengaturan terlihat seperti ini:

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 dibundel dengan aktivitas titik masuk kustom yang menggantikan UnityPlayerActivity default. Jika Anda tidak menggunakan titik masuk khusus, penggantian ini terjadi secara otomatis dan Anda tidak perlu melakukan tindakan tambahan apa pun. Aplikasi yang tidak menggunakan Aktivitas titik masuk default atau yang menyediakan Assets/Plugins/AndroidManifest.xml mereka sendiri akan memerlukan konfigurasi tambahan.

Plugin Firebase Cloud Messaging Unity di Android dibundel 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 menginstruksikan aplikasi untuk menggunakan MessagingUnityPlayerActivity sebagai titik masuk ke aplikasi.

File-file ini disediakan karena UnityPlayerActivity default tidak menangani onStop , transisi siklus hidup aktivitas onRestart atau mengimplementasikan 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 Anda menangani semua transisi Daur Hidup Aktivitas Android dengan benar (contoh cara melakukannya ditunjukkan di bawah). Jika aktivitas kustom Anda memperluas UnityPlayerActivity Anda dapat memperluas com.google.firebase.MessagingUnityPlayerActivity yang mengimplementasikan semua metode yang diperlukan.

Jika Anda menggunakan Aktivitas khusus dan tidak memperluas com.google.firebase.MessagingUnityPlayerActivity , Anda harus menyertakan cuplikan berikut dalam Aktivitas 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
 * 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);
}

Versi baru Firebase C++ SDK (7.1.0 dan seterusnya) menggunakan JobIntentService yang memerlukan modifikasi tambahan pada 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 notifikasi, pesan tersebut, secara default, tidak dirutekan melalui callback bawaan FCM. Dalam hal ini, muatan pesan diterima melalui Intent yang digunakan untuk memulai aplikasi.

Pesan yang diterima saat aplikasi berada di latar belakang memiliki konten kolom notifikasi yang digunakan untuk mengisi notifikasi baki sistem, tetapi konten notifikasi tersebut tidak akan dikomunikasikan ke FCM. Artinya, FirebaseMessage.Notification akan menjadi null.

Kesimpulan:

Cegah inisialisasi otomatis

FCM menghasilkan token pendaftaran untuk penargetan perangkat. Saat token dibuat, perpustakaan mengunggah pengidentifikasi dan data konfigurasi ke Firebase. Jika Anda ingin mendapatkan keikutsertaan eksplisit sebelum menggunakan token, Anda dapat mencegah pembuatan pada waktu konfigurasi dengan menonaktifkan FCM (dan di Android, Analytics). Untuk melakukannya, tambahkan nilai metadata ke Info.plist Anda (bukan GoogleService-Info.plist Anda) di Apple, atau AndroidManifest.xml Anda di 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

Untuk mengaktifkan kembali FCM, Anda dapat melakukan panggilan runtime:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Nilai ini tetap ada saat aplikasi dimulai ulang setelah ditetapkan.

Menangani Pesan dengan Tautan Dalam di Android

FCM memungkinkan pengiriman pesan berisi tautan dalam ke aplikasi Anda. Untuk menerima pesan yang berisi tautan dalam, Anda harus menambahkan filter maksud baru ke aktivitas yang menangani tautan dalam untuk aplikasi Anda. Filter maksud harus menangkap tautan dalam dari domain Anda. Jika pesan Anda tidak berisi tautan dalam, konfigurasi ini tidak diperlukan. Di 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>

Dimungkinkan juga untuk menentukan wildcard untuk membuat filter maksud lebih fleksibel. Sebagai 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>

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

Langkah selanjutnya

Setelah menyiapkan aplikasi klien, Anda siap mengirim pesan downstream dan topik dengan Firebase. Untuk mempelajari lebih lanjut, lihat contoh quickstart yang menunjukkan fungsi ini.

Untuk menambahkan perilaku lain yang lebih canggih ke aplikasi Anda, lihat panduan untuk mengirim pesan dari server aplikasi:

• Kirim pesan topik
• Kirim ke grup perangkat
• Kirim pesan upstream

Perlu diingat bahwa Anda memerlukan implementasi server untuk menggunakan fitur ini.