Setelah Anda menyelesaikan prasyarat di halaman Memulai gunakan halaman ini untuk mempelajari cara mengirim acara dan menggunakan fitur Uji Peristiwa. Setelah Anda mengirimkan peristiwa, verifikasikan pengaturan Anda.
Conversions API didasarkan pada Marketing API Facebook, yang dibangun di atas Graph API kami. Marketing API dan Graph API memiliki jadwal penghentian versi yang berbeda. Siklus rilis kami selaras dengan Graph API, jadi setiap versi didukung setidaknya selama dua tahun. Pengecualian ini hanya valid untuk Conversions API.
Conversions API: Gambaran UmumParameterPeristiwa web, aplikasi, dan toko fisik yang dibagikan menggunakan Conversions API memerlukan parameter tertentu. Dengan menggunakan Conversions API, Anda setuju bahwa parameter action_source
akurat sesuai pengetahuan Anda. Daftar parameter wajib tersedia di sini.
Untuk mengirim peristiwa baru, buat permintaan POST
ke edge /events
API ini dari jalur: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}
. Saat Anda memposting ke edge ini, Facebook membuat peristiwa server baru.
curl -X POST \
-F 'data=[
{
"event_name": "Purchase",
"event_time": 1732199735,
"user_data": {
"em": [
"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
],
"ph": [
"254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
"6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
],
"client_ip_address": "123.123.123.123",
"client_user_agent": "$CLIENT_USER_AGENT",
"fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
"fbp": "fb.1.1558571054389.1098115397"
},
"custom_data": {
"currency": "usd",
"value": 123.45,
"contents": [
{
"id": "product123",
"quantity": 1,
"delivery_category": "home_delivery"
}
]
},
"event_source_url": "http://jaspers-market.com/product/123",
"action_source": "website"
}
]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<PIXEL_ID>/events
Lampirkan token akses aman yang Anda buat menggunakan parameter kueri access_token
ke permintaan. Anda juga dapat menggunakan Graph API Explorer untuk POST
ke /<pixel_id>/events
endpoint.
Contoh isi permintaan terlihat seperti ini:
{ "data": [ { "event_name": "Purchase", "event_time": 1633552688, "event_id": "event.id.123", "event_source_url": "http:\/\/jaspers-market.com\/product\/123", "action_source": "website", "user_data": { "client_ip_address": "192.19.9.9", "client_user_agent": "test ua", "em": [ "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd" ], "ph": [ "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4", "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6" ], "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890", "fbp": "fb.1.1558571054389.1098115397" }, "custom_data": { "value": 100.2, "currency": "USD", "content_ids": [ "product.id.123" ], "content_type": "product" }, "opt_out": false }, { "event_name": "Purchase", "event_time": 1633552688, "user_data": { "client_ip_address": "192.88.9.9", "client_user_agent": "test ua2" }, "custom_data": { "value": 50.5, "currency": "USD" }, "opt_out": false } ] }
event_time
adalah waktu transaksi peristiwa. Ini harus dikirim sebagai cap waktu Unix dalam hitungan detik yang menunjukkan kapan peristiwa sebenarnya terjadi. Waktu yang ditentukan mungkin lebih awal dari waktu Anda mengirimkan peristiwa ke Facebook. Hal ini dilakukan agar dapat memproses batch dan mengoptimalkan kinerja server.
event_time
bisa sampai 7 hari sebelum Anda mengirim peristiwa ke Meta. Jika event_time
di data
lebih dari 7 hari pada masa lalu, kami akan menampilkan kesalahan untuk seluruh permintaan dan tidak memproses peristiwa. Untuk peristiwa toko offline dan fisik dengan physical_store
sebagai action_source
, Anda harus mengunggah transaksi dalam 62 hari sejak konversi.
Dengan menggunakan Conversions API, Anda setuju bahwa parameter action_source
akurat sesuai pengetahuan Anda.
Anda dapat mengirim hingga 1.000 peristiwa dalam data
. Namun, untuk kinerja yang optimal, kami rekomendasikan Anda untuk mengirimkan peristiwa segera setelah terjadi dan idealnya dalam waktu satu jam setelah peristiwa tersebut terjadi. Jika peristiwa yang Anda kirimkan dalam satu batch ada yang tidak valid, kami menolak seluruh batch itu.
Periksalah halaman parameter informasi pelanggan kami untuk melihat parameter mana yang harus di-hash sebelum dikirim ke Facebook. Jika Anda menggunakan salah satu SDK Bisnis kami, hashing dilakukan untuk Anda oleh SDK.
Pelajari selengkapnya tentang tiga fitur SDK Bisnis khusus yang dirancang khusus untuk pengguna Conversions API: Permintaan Asinkron, Batching Bersamaan, dan Antarmuka Layanan HTTP. Versi bahasa minimum diperlukan untuk menggunakan fitur-fitur ini:
Dukungan SDK Bisnis untuk PHP 5 telah dihentikan sejak Januari 2019. Silakan tingkatkan ke PHP 7 untuk menggunakan SDK Bisnis.
Jika Anda harus menggunakan PHP 5, pertimbangkanlah untuk menggunakan implementasi Swagger kami.
Setelah Anda mengirim peristiwa Anda, konfirmasikan bahwa kami telah menerimanya di Pengelola Peristiwa:
PIXEL_ID
di permintaan POST
Anda. Untuk informasi selengkapnya, Pusat Bantuan Bisnis: Menavigasi Pengelola Peristiwa.Anda dapat memverifikasi bahwa peristiwa server Anda diterima dengan benar oleh Facebook dengan menggunakan fitur Uji Peristiwa di Pengelola Peristiwa. Untuk menemukan fitur, buka Events Manager > Data Sources > Your Pixel > Test Events
.
Fitur Peristiwa Uji membuat ID pengujian. Kirim ID sebagai parameter test_event_code
untuk mulai melihat aktivitas peristiwa muncul di jendela Uji Peristiwa.
Catatan: Kolom test_event_code
sebaiknya hanya digunakan untuk pengujian. Anda harus menghapusnya saat mengirim muatan produksi Anda.
Peristiwa yang dikirim dengan test_event_code
tidak dihentikan. Peristiwa mengalir ke Pengelola Acara dan digunakan untuk tujuan penargetan dan pengukuran iklan.
Berikut adalah contoh bagaimana struktur permintaan seharusnya:
Inilah contoh bagaimana permintaan muncul di Graph API Explorer:
Anda dapat membuat payload uji ini menggunakan fitur Bantuan Payload. Harap diperhatikan bahwa kode peristiwa uji hanya untuk menguji payload.
Peristiwa server Anda muncul di jendela Uji Peristiwa setelah permintaan dikirim.
Untuk kedua API ini, terapkan opsi pemrosesan data dengan menambahkan data_processing_options
, data_processing_options_country
, dan data_processing_options_state
di dalam tiap peristiwa dengan parameter data peristiwa Anda.
Catatan: Peristiwa Aplikasi dan Offline Conversions API tidak lagi direkomendasikan untuk integrasi baru. Sebagai gantinya, Anda direkomendasikan untuk menggunakan Conversions API karena sekarang API ini mendukung web, aplikasi, dan peristiwa offline. Lihat <Conversions API untuk Peristiwa Aplikasi dan <Conversions API untuk Peristiwa Offline untuk informasi selengkapnya.
Untuk secara eksplisit tidak mengaktifkan Penggunaan Data Terbatas (LDU), tentukan array kosong untuk setiap peristiwa atau cukup hapus kolom di payload:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": [] } ] }
Untuk mengaktifkan LDU dan meminta Meta melakukan geolokasi:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>", "client_ip_address": "256.256.256.256" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": ["LDU"], "data_processing_options_country": 0, "data_processing_options_state": 0 } ] }
Untuk mengaktifkan LDU dan menentukan lokasi secara manual, contoh, untuk California:
{ "data": [ { "event_name": "Purchase", "event_time": <EVENT_TIME>, "user_data": { "em": "<EMAIL>" }, "custom_data": { "currency": "<CURRENCY>", "value": "<VALUE>" }, "data_processing_options": ["LDU"], "data_processing_options_country": 1, "data_processing_options_state": 1000 } ] }
Offline Conversions API menawarkan opsi untuk secara manual mengunggah peristiwa dari file .csv
. Dalam hal ini, tambahkan Opsi Pemrosesan Data, Negara Pemrosesan Data, dan Negara Bagian Pemrosesan Data sebagai kolom dalam file. Informasi selengkapnya tentang ini dapat ditemukan di antarmuka pengguna unggah.
Pelajari selengkapnya tentang Opsi Pemrosesan Data.
Marketing API memiliki logika pembatas lajunya sendiri dan dikecualikan dari semua pembatasan laju Graph API. Jadi, jika Anda membuat panggilan Marketing API, maka hal tersebut tidak akan dihitung ke dalam pelambatan Graph API.
Tidak ada batas laju khusus untuk Conversions API. Panggilan Conversions API dihitung sebagai panggilan Marketing API. Satu-satunya batasan adalah Anda dapat mengirimkan hingga 1.000 peristiwa dalam satu waktu. Lihat Mengirim Permintaan untuk informasi selengkapnya.
Pembatasan Laju Marketing APIPanduan ini membantu Anda menavigasi fitur canggih Meta Business SDK yang dirancang khusus untuk pengguna Conversions API Gateway. Untuk penggunaan dasar Conversions API Gateway, lihat dokumentasi Conversions API Gateway.
Sebelum menggunakan fitur yang tercantum di bawah ini, Anda harus telah menginstal Meta Business SDK. Lihat Memulai Meta Business SDK atau ikuti instruksi README yang tercantum di sini:
Saat ini, fitur-fitur ini hanya tersedia di PHP dan Java Business SDK. Bahasa-bahasa lainnya akan diterapkan pada akhir 2023.
Versi bahasa minimum yang diperlukan untuk menggunakan fitur-fitur ini adalah:
PHP >= 7.2
Java >= 8
Catatan: Untuk menghapus duplikat peristiwa ke endpoint Conversions API, teruskan eventId
dalam permintaan Anda. Ini akan membantu mencegah peristiwa duplikat agar tidak muncul jika penerbitan Conversions API diaktifkan.
CAPIGatewayIngressRequest
Parameter | Deskripsi |
---|---|
endpointUrl string | Endpoint Conversations API yang merupakan tempat tujuan pengiriman peristiwa. Tidak ada pravalidasi yang akan dilakukan pada parameter selain memeriksa apakah itu adalah URL yang valid. Contoh: https://test.example.com |
accessKey string | Kode akses Conversions API Gateway yang diperlukan untuk mengirim peristiwa ke endpoint peristiwa Conversions API Gateway. Ini adalah instruksi untuk membuatnya. |
CAPIGatewayIngressRequest
Parameter | Deskripsi |
---|---|
setSendToDestinationOnly Boolean | Bendera Boolean untuk menandai apakah peristiwa hanya dikirim ke endpoint yang dipilih. Default: |
setFilter Fungsi CustomEndpointRequest.Filter() | Fungsi filter yang memproses setiap peristiwa. Jika logika pemfilteran memberikan true, peristiwa itu berhasil lewat. Jika tidak, peristiwa itu akan dibatalkan. Anda harus menerapkan fungsi shouldSendEvent di antarmuka yang memiliki parameter Event. Default: |
Untuk sistem yang sudah menggunakan SDK Bisnis, Anda hanya perlu merujuk CAPIGatewayIngressRequest yang baru dan melampirkannya ke objek customEndpoint milik eventRequest.
// this is the standard event request that we attach events to $event_request = new EventRequest($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); // pass the events to this event Request object $event_request->setEvents($events); $event_request->execute()
Untuk sistem yang sudah menggunakan SDK Bisnis, Anda hanya perlu merujuk CAPIGatewayIngressRequest yang baru dan melampirkannya ke objek customEndpoint milik eventRequest.
// this is the standard event request that we attach events to EventRequest eventRequest = new EventRequest(PIXEL_ID, context); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); eventRequest.addDataItem(testEvent); eventRequest.execute();
$api = Api::init(null, null, $this->access_token); $api->setLogger(new CurlLogger()); $event_request = new EventRequest($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); $user_data = (new UserData()) ->setEmails(array('joe@eg.com')) ->setPhones(array('12345678901', '14251234567')) ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890') ->setFbp('fb.1.1558571054389.1098115397'); $event1 = (new Event()) ->setEventName('Purchase') ->setEventId('125') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123') ->setUserData($user_data); $events = array($event1, $event2); $event_request->setEvents($events); $response = $event_request->execute(); print($response->__toString());
EventRequest eventRequest = new EventRequest(PIXEL_ID, context); UserData userData = new UserData() .email("abc@eg.com"); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); Event testEvent = new Event(); testEvent.eventId("125").eventName("Purchase") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .dataProcessingOptions(new String[]{}).setEventId("134423232"); eventRequest.namespaceId("11") .uploadId("22222") .uploadTag("upload-tag-4") .uploadSource("upload-source-4") .testEventCode("test-event-code-5") .partnerAgent("partner-agent-6"); eventRequest.addDataItem(testEvent); eventRequest.execute();
$api = Api::init(null, null, $this->access_token); $api->setLogger(new CurlLogger()); $event_request = new EventRequestAsync($this->pixel_id); $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $capiIngressRequest->setSendToDestinationOnly(true); $event_request->setCustomEndpoint($capiIngressRequest); $event1 = (new Event()) ->setEventName('test Async Event') ->setEventId('134423232') ->setEventTime(time()) ->setEventSourceUrl('http://jaspers-market.com/product/123'); $events = array($event1, $event2); $event_request->setEvents($events); $response = $event_request->execute()->wait();
EventRequest eventRequest = new EventRequest(PIXEL_ID, context); UserData userData = new UserData() .email("abc@eg.com"); CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); capiSyncRequest.setSendToDestinationOnly(true); eventRequest.setCustomEndpoint(capiSyncRequest); Event testEvent = new Event(); testEvent.eventName("test Async Event") .eventTime(System.currentTimeMillis() / 1000L) .userData(userData) .dataProcessingOptions(new String[]{}).setEventId("134423232"); eventRequest.namespaceId("11222") .uploadId("22222") .uploadTag("upload-tag-4") .uploadSource("upload-source-4") .testEventCode("test-event-code-5") .partnerAgent("partner-agent-6"); eventRequest.addDataItem(testEvent); eventRequest.executeAsync();
lass APIFilter implements Filter { public function shouldSendEvent(Event $event): bool { if ($event->getEventId() === '125') { return false; } return true; } } $capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); $event_request->setCustomEndpoint($capiIngressRequest); $capiIngressRequest->setFilter(new APIFilter());
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); eventRequest.setCustomEndpoint(capiSyncRequest); capiSyncRequest.setFilter(new CustomEndpointRequest.Filter() { @Override public boolean shouldSendEvent(Event event) { if (event.getEventId().equals("125")) { return true; } return false; } });