Conversions API untuk Peristiwa Aplikasi

Conversions API memungkinkan pengiklan mengirim peristiwa web, aplikasi, toko fisik, dan pengiriman pesan bisnis ke Meta melalui satu endpoint, dan bukan melalui berbagai sumber. Konsolidasi ini akan menyederhanakan stack teknologi pengiklan dan menciptakan tampilan yang lebih komprehensif dalam Pengelola Peristiwa Meta dengan menggunakan set data.

Dokumentasi ini memberikan panduan untuk mengintegrasikan peristiwa aplikasi ke Conversions API.

Prasyarat

1. Set data

Peristiwa aplikasi yang dikirim melalui Conversions API harus dikaitkan dengan set data.

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

Anda dapat melakukan panggilan GET ke https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container untuk mendeteksi apakah set data pengiklan telah digabungkan sehingga memenuhi syarat untuk meneruskan peristiwa aplikasi melalui Conversions API.

2. Izin

Untuk menerapkan integrasi langsung sebagai pengiklan, silakan ikuti petunjuknya di sini untuk prasyarat dan izin.
Untuk menerapkan integrasi platform mitra, silakan ikuti petunjuknya di sini untuk prasyarat dan izin.

Konfigurasi

Mengirim Peristiwa Aplikasi ke Conversions API

a. Menautkan ID set data dan ID aplikasi

Di Pengelola Peristiwa, ada dua cara untuk menautkan aplikasi Anda dengan set data:

Pilih tab “Sumber Data”, temukan tab “Pengaturan” aplikasi Anda dan lakukan penautan.
Pilih tab “Sumber Data”, di tab “Rangkuman” aplikasi Anda, gunakan tombol “Tautkan ke set data” di bagian “Semua Aktivitas”.

Setelah Anda menyelesaikan penautan, set data menyertakan aplikasi yang terhubung.

b. Kolom yang diperlukan

Anda bisa merujuk di sini ke kumpulan parameter saat ini yang dapat dikirim melalui Conversions API. Untuk mengirim peristiwa aplikasi, server_event fields berikut ini dapat dibagikan dalam payload:

Parameter action_source harus berisi nilai app untuk peristiwa aplikasi.
event_id wajib ada untuk kasus pengaturan deduplikasi.
app_data fields
user_data fields
custom_data fields

Kolom Data Aplikasi

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`vendor_id` string	Optional Vendor ID.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

Parameter Informasi Pelanggan

Parameter	Deskripsi
`anon_id` string	Jangan hash. ID penginstalan Anda. Kolom ini mewakili instance instalasi aplikasi unik.
`madid` string	Jangan hash. ID pengiklan seluler Anda, ID iklan dari perangkat Android atau Pengidentifikasi Iklan (IDFA) dari perangkat Apple.

Data Khusus

Parameter	Deskripsi
`description` string	Opsional. String, deskripsi peristiwa, khusus.
`level` string	Opsional. String, level game, khusus.
`max_rating_value`	Opsional. Panjang, batas atas skala peringkat, contohnya 5 dari skala 5 bintang, khusus.
`success` boolean	Opsional. `1` untuk ya, `0` untuk tidak, khusus.

Singkatnya, peristiwa aplikasi yang dibagikan menggunakan Conversions API akan mewajibkan parameter data berikut:

action_source: Harus diatur ke 'app'. (Dengan menggunakan Conversions API, Anda setuju bahwa parameter action_source akurat sepanjang pengetahuan Anda)
event_id: Diwajibkan untuk pengaturan deduplikasi, lihat detailnya di bagian 'Menyiapkan deduplikasi untuk beberapa saluran'.
advertiser_tracking_enabled
application_tracking_enabled
extinfo

Di bawah ini adalah contoh extinfo. Pastikan semua subparameter di bawah ini terisi dan berurutan. Jika ada subparameter yang tidak terisi, gunakan string kosong sebagai placeholder.

Nama Subparameter	Diwajibkan	Jenis Data	Contoh
versi extinfo	Ya	string	`i2` (versi harus a2 untuk Android, harus i2 untuk iOS)
nama paket aplikasi	Tidak	string	`com.facebook.sdk.samples.hellofacebook`
versi pendek	Tidak	string	`1.0`
versi panjang	Tidak	string	`1.0 long`
versi os	Ya	string	`13.4.1`
nama model perangkat	Tidak	string	`iPhone5,1`
locale	Tidak	string	`En_US`
singkatan zona waktu	Tidak	string	`PDT`
operator	Tidak	string	`AT&T`
lebar layar	Tidak	string	`320`
tinggi layar	Tidak	string	`568`
kepadatan layar	Tidak	string	`2`
core cpu	Tidak	string	`2`
ukuran penyimpanan eksternal	Tidak	string	`13`
ruang kosong dalam ukuran penyimpanan eksternal	Tidak	string	`8`
zona waktu perangkat	Tidak	string	`USA/New York`

c. Menyiapkan Deduplikasi untuk Beberapa Saluran

Mekanisme deduplikasi akan diperlukan untuk menghapus lalu lintas peristiwa duplikat antara integrasi Conversions API dan semua integrasi lain yang Anda miliki dengan peristiwa aplikasi termasuk SDK, MMP, dan App Events API.

Untuk peristiwa aplikasi, kami menerapkan fungsi deduplikasi yang sama dengan yang sudah ada untuk peristiwa web. Logika ini memanfaatkan deduplikasi berbasis kolom event_id dan event_name (Conversions API dan SDK / Peristiwa App Events API yang membawa event_id yang sama). Parameter event_id adalah pengidentifikasi yang dapat secara unik membedakan peristiwa serupa. Jika ID peristiwa ini tidak akurat, dapat terjadi kekeliruan dalam deduplikasi konversi Anda, sehingga selanjutnya berdampak pada pelaporan konversi dan kinerja kampanye.

Anda dapat merujuk ke dokumentasi developer berikut untuk menerapkan pengaturan deduplikasi:

Berikut adalah contoh cara mencatat peristiwa khusus. Untuk melakukannya, teruskan nama peristiwa sebagai AppEvents.Name di iOS SDK:

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

Untuk peristiwa penginstalan aplikasi, sudah ada mekanisme deduplikasi yang memastikan hanya satu penginstalan yang diatribusikan dalam jangka waktu 90 hari terakhir. Kami menyimpan peristiwa pertama dan melepas peristiwa berikutnya, apa pun sumber tindakannya. Tidak ada persyaratan untuk menerapkan deduplikasi untuk peristiwa aplikasi yang terkait dengan peristiwa penginstalan.

d. Mengirim Peristiwa

Untuk mengirim peristiwa baru, buat permintaan POST ke Conversions API dari jalur ini: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}. Saat Anda memposting ke edge ini, Meta membuat peristiwa server aplikasi baru. Untuk lebih jelasnya, silakan simak dokumen developer berikut ini.

Berikut ini ringkasan tentang kesesuaian parameter dalam keseluruhan skema di payload:

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1684389752,
            "action_source": "app",
            "user_data": {
                "em": [
                    "30a79640dfd8293d4f4965ec11821f640ca77979ca0a6b365f06372f81a3f602"
                ],
                "ph": [
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
                ],
                "madid": "bbbbbbbbbbbb",
      "anon_id": "cccccccc"
            },
            "custom_data": {
                "currency": "USD",
                "value": "142.52"
            },
            "app_data": {
                "advertiser_tracking_enabled": "True",
                "application_tracking_enabled": "True",
                "campaign_ids": "aaaaaaaaa",
                "extinfo": [
                    "a2",
                    "com.some.app",
                    "771",
                    "Version 7.7.1",
                    "10.1.1",
                    "OnePlus6",
                    "en_US",
                    "GMT-1",
                    "TMobile",
                    "1920",
                    "1080",
                    "2.00",
                    "2",
                    "128",
                    "8",
                    "USA/New York"
                ]
            }
        }
    ]
}

Pemecahan Masalah

Anda dapat menggunakan fitur Bantuan Payload untuk membuat data payload:

Pilih sumber tindakan app jika berlaku
Isi info untuk peristiwa yang akan dikirimkan ke Meta
Ini akan menghasilkan payload peristiwa, yang dapat digunakan sebagai template untuk integrasi Conversions API Anda

Gunakan fitur Uji Peristiwa di Pengelola Peristiwa untuk pengujian.