Apa yang dicakup Facebook App Events di Flutter, dan apa yang tidak

App Events adalah cara Meta mengetahui apa yang terjadi di dalam aplikasi Anda. Aplikasi Anda mencatat sebuah event bernama, Facebook SDK mengumpulkannya dalam batch lalu mengirimkannya, dan event itu muncul di Events Manager. Event yang sama itulah yang diatribusikan pelaporan iklan Meta ke kampanye Anda.

Ikhtisar App Events milik Meta sendiri lebih merupakan indeks singkat daripada sebuah referensi. Ia menggambarkan App Events sebagai cara agar aplikasi Anda bisa "track events, such as a person installing your app or completing a purchase", lalu menautkan ke panduan per platform. Kalau Anda datang dari halaman itu untuk mencari daftar metode, bagian berikutnya adalah jalan pintasnya.

facebook_app_events mencakup permukaan itu dan hanya itu. Facebook Login dan fitur berbagi adalah komponen SDK yang terpisah dan bukan bagian dari plugin ini.

Ini hal paling berguna yang perlu Anda ketahui tentang plugin ini, dan artinya dalam praktik adalah Anda membaca dokumentasi Meta, bukan dokumentasi kami.

Plugin ini mencerminkan permukaan App Events dari SDK native secara 1:1. Kalau sebuah metode ada di AppEvents pada iOS, atau di AppEventsLogger, atau di antara pengaturan terkait pada Settings dan FacebookSdk pada Android, Anda semestinya menemukannya di sini dengan nama yang sama. Nama metode dari referensi native Meta adalah nama yang Anda panggil dari Dart.

Referensi Android milik Meta untuk AppEventsLogger masih hidup dan langsung bisa dipakai. logEvent, logPurchase, logPushNotificationOpen, logProductItem, flush dan getApplicationId semuanya terdokumentasi di sana, lengkap dengan signature dan catatan yang Anda butuhkan.

Padanannya untuk iOS kurang bisa diandalkan. URL referensi FBSDKCoreKit yang dirujuk oleh komentar dokumentasi plugin ini sendiri menjawab Page Not Found ketika halaman ini terakhir diperiksa, dan halaman indeks referensi iOS milik Meta sama sekali tidak memuat entri AppEvents. Sampai hal itu tertata, bacalah deklarasi AppEvents di dalam FBSDKCoreKit secara langsung.

Di tempat kedua platform benar-benar berbeda, plugin ini mengatakannya alih-alih menutupinya. clearUserDataForType bekerja di iOS dan tidak melakukan apa pun di Android, yang mencatat sebuah peringatan: pakai clearUserData() di sana.

Empat kelompok API native sengaja tidak disediakan, karena tidak bisa diterjemahkan ke Flutter:

• Varian logEvent dan logPurchase yang menerima access token.
• Augmentasi hybrid webview: augmentWebView dan augmentHybridWebView.
• Hook integrasi untuk Unity.
• logFailedStoreKit2Purchase, yang hanya ada di iOS.

Jadi kalau Anda tidak menemukan salah satunya, ia tidak ada karena sebuah keputusan, bukan karena terlewat. Keputusan itu bisa diubah: buka issue di repositori dan jelaskan kebutuhan Anda.

Baca bagian ini walau Anda melewatkan sisanya.

Facebook SDK native hanya menerima nilai parameter event bertipe String dan numerik. Event yang membawa nilai bertipe apa pun selain itu dibuang oleh SDK: tanpa suara, tanpa error, dan tidak muncul di mana pun di Events Manager. Bukan hanya parameter yang bermasalah. Seluruh event-nya.

facebook_app_events membuat kegagalan itu terlihat:

Baris null yang perlu Anda cermati, karena itulah satu-satunya yang tidak melempar error. Nilai opsional yang kebetulan kosong akan diam-diam mengeluarkan parameternya dari event yang selebihnya sampai dengan utuh. Biasanya itu memang yang Anda inginkan. Itu bukan yang Anda inginkan ketika parameter itulah yang Anda laporkan.

Nilai terstruktur harus dikodekan sebagai string JSON lebih dahulu, dan itu pula yang ditetapkan Meta untuk parameter seperti fb_content:

// Throws ArgumentError: a List is not an accepted parameter value type.
await facebookAppEvents.logEvent(
  name: 'checkout_started',
  parameters: {'fb_content': items},
);

// Correct: encode the structure as a JSON string first.
await facebookAppEvents.logEvent(
  name: 'checkout_started',
  parameters: {'fb_content': jsonEncode(items)},
);

Aturan ini berlaku di setiap tempat plugin menormalkan parameter, yaitu logEvent, logPurchase dan logProductItem. Di mana pun Anda memanggil SDK native secara langsung, atau mencatat melalui pembungkus lain, Anda mendapat perilaku native-nya: kesunyian.

activateApp() mencatat event aktivasi dan pemasangan. Anda hanya membutuhkannya kalau pencatatan app event otomatis dimatikan atau ditunda, dan itu bentuk yang biasa ketika inisialisasi digerbangi oleh persetujuan pengguna. Kalau FacebookAutoLogAppEventsEnabled di iOS atau com.facebook.sdk.AutoLogAppEventsEnabled di Android disetel false, panggil sendiri metode itu.

Anda bisa memberikan applicationId untuk mencatat ke app id selain yang ada di konfigurasi platform Anda. Penimpaan itu berlaku per panggilan: activateApp() berikutnya tanpa parameter itu kembali ke nilai bawaan.

Event tidak langsung meninggalkan perangkat saat Anda mencatatnya. SDK menyimpannya dan mengirimkannya dalam batch. Dua API menentukan kapan:

• flush() mengirim semua yang tersimpan seketika. Inilah yang Anda inginkan saat menguji, supaya event yang baru Anda picu sampai ke Test Events dalam hitungan detik, bukan menunggu batch berikutnya.
• setFlushBehavior(FlushBehavior) memilih kapan batch berjalan sendiri. FlushBehavior.auto adalah nilai bawaan SDK: event dikirim secara berkala dan ketika aplikasi masuk ke latar belakang. FlushBehavior.explicitOnly mematikan pengiriman otomatis, jadi tidak ada yang dikirim sampai Anda memanggil flush().

explicitOnly perlu Anda kenali terutama sebagai penyebab. Aplikasi yang menyetelnya lalu tidak pernah memanggil flush() mencatat event yang tidak pernah meninggalkan perangkat, dan hasilnya di Events Manager tidak bisa dibedakan dari aplikasi yang tidak mencatat apa pun. getFlushBehavior() membaca kembali nilai yang berlaku, dan itu cara cepat mengetahui apa yang dilakukan basis kode yang Anda warisi.

Plugin ini tidak menampilkan dialog ATT, tidak mengelola persetujuan pengguna, dan tidak membuat aplikasi Anda patuh aturan privasi. Tidak ada pembungkus yang bisa melakukan itu. Pekerjaan itu milik aplikasi Anda.

Yang disediakannya adalah pengaturan privasi milik SDK itu sendiri, dan menyetelnya dengan benar juga tugas aplikasi Anda. Kedua bagian itu benar, dan tidak ada yang menggantikan yang lain. Plugin menyerahkan tuasnya kepada Anda. Salah menyetel salah satunya menghasilkan data yang hilang tanpa error apa pun.

Tuas mana yang melakukan apa, dan mengapa setAdvertiserTracking sudah tidak dianjurkan serta tidak melakukan apa pun di iOS 17 dan setelahnya, dibahas di Facebook App Events tidak muncul di Events Manager.