Conversions API

3: Penerapan Developer

Halaman ini membahas integrasi manual dan mencakup:

Bagian ini hanya berlaku jika Anda memutuskan untuk menyelesaikan integrasi ini menggunakan integrasi manual dan sumber daya developer. Jika Anda memutuskan untuk menyelesaikan integrasi ini menggunakan mitra, ikuti petunjuk mitra masing-masing untuk integrasi. Anda dapat melompat ke bagian 4: Verifikasikan data Anda dalam panduan ini setelah integrasi mitra selesai.

Anda akan memerlukan akses admin Pengelola Bisnis untuk menyelesaikan langkah-langkah integrasi ini. Anda bisa memperoleh akses dari email yang dikirimkan kepada Anda jika diundang sebagai developer. Jika tidak, hubungi admin Pengelola Bisnis untuk meminta akses.

Langkah 1: Buat payload

Langkah ini akan memaparkan spesifikasi payload untuk Integrasi Prospek Konversi dan memberikan beberapa rekomendasi tentang cara mengirimkannya dari server Anda.

  1. Buka panduan Integrasi CRM dari tab Pengaturan di Pixel CRM Anda untuk memulai.

  2. Tinjau Panduan Developer Conversions API untuk mendapatkan pemahaman tentang cara kerja Conversions API.

  3. Kami menyarankan agar Anda menggunakan Bantuan Payload untuk membuat payload Anda. Bantuan Payload akan memformat payload Anda dan memeriksa kesalahan. Setelah semua kesalahan payload diselesaikan, klik tombol Dapatkan Kode di dalam Bantuan Payload guna membuat template kode untuk bahasa pemrograman Anda.

  4. Berikut adalah daftar parameter yang wajib ada. Tinjau panduan Integrasi Prospek Konversi - Spesifikasi Payload guna melihat deskripsi lengkap untuk setiap parameter. Spesifikasi payload ini hanya boleh digunakan untuk peristiwa Pengoptimalan Prospek Konversi. Ini berarti peristiwa hanya boleh berkaitan dengan iklan prospek Meta dan harus memiliki ID Prospek yang valid. Jangan gunakan spesifikasi payload ini untuk jenis peristiwa lain, seperti prospek situs web.

    Parameter
    NamaDeskripsi

    event_name

    string

    Kolom teks bebas untuk menangkap tahap prospek yang Anda gunakan dalam CRM Anda.

    Parameter event_name menunjukkan prospek bergerak melalui corong penjualan di CRM Anda. Pastikan untuk mengirim semua tahap saat diperbarui, termasuk prospek mentah.

    event_time

    integer

    Cap waktu Unix dalam satuan detik, yang menunjukkan kapan peristiwa pembaruan tahap prospek diperbarui oleh CRM Anda.
    Cap waktu harus terjadi setelah waktu pembuatan prospek. Kalau tidak, peristiwa itu mungkin akan dibuang.

    action_source

    string

    Nilai:system_generated


    (Dengan menggunakan Conversions API, Anda setuju bahwa parameter action_source akurat sepanjang pengetahuan Anda.)

    lead_id

    integer

    15 atau 16 digit leadgen_id dari prospek yang Anda unduh.

    lead_event_source

    string

    Nama CRM tempat peristiwa tersebut berasal.

    event_source

    string

    Nilai:crm



    Contoh
    Contoh payload dapat seperti berikut ini. Catatan: Anda harus menggunakan lead_id yang valid, atau sistem akan menolak peristiwa Anda. 
    {
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

  5. Jika peristiwa tidak mengikuti spesifikasi payload atau tidak terkait dengan suatu iklan prospek Meta, peristiwa tersebut tidak akan dikenali untuk integrasi dan tidak akan digunakan untuk melatih model.
    Misalnya, payload Web akan diterima oleh Conversions API dan muncul di Pengelola Peristiwa, tetapi tidak dikenali untuk integrasi ini. Anda juga harus menggunakan lead_id yang valid, atau sistem akan menolak peristiwa Anda.
    Hanya payload Prospek Konversi yang akan dikenali untuk integrasi dan digunakan untuk pelatihan.

Langkah 2: Buat token akses dan panggilan API

Setelah Anda mengonfigurasi apa yang akan Anda kirim, langkah selanjutnya adalah mengonfigurasi ke mana Anda akan mengirim data.

Langkah ini akan membantu membuat token akses untuk Meta Pixel Anda, yang kemudian akan digunakan untuk membangun koneksi antara server Anda dan Conversions API.

  1. Anda dapat kembali ke panduan integrasi CRM dari tab Pengaturan di Pixel CRM Anda.

  2. Gulir ke bawah ke bagian Buat Endpoint dan klik tombol Buat Token Akses. Token akses akan digunakan untuk membuat panggilan API.
    Anda dapat membuat token akses baru dengan kembali ke panduan integrasi atau dari tab Pengaturan di Pengelola Peristiwa dengan membuka bagian Conversions API dan mengeklik tautan Buat token akses.

  3. Bagian selanjutnya dari panduan ini akan berbeda-beda, bergantung pada apakah Anda menggunakan SDK Meta. Disarankan Anda menggunakan Meta Business SDK karena SDK ini memberikan pesan kesalahan dan diagnostik yang lebih baik. Anda akan memerlukan ID Pixel dan token akses untuk melakukan panggilan API melalui Meta Business SDK. Anda bisa mendapatkan token akses dengan mengeklik Salin token akses di panduan Integrasi CRM dan menyimpannya. Contoh panggilan SDK API terdapat di Panduan Developer Conversions API atau fungsi Dapatkan Kode di dalam Bantuan Payload Meta.

  4. Ini adalah format endpoint untuk membuat permintaan POST ke Conversions API tanpa SDK. Anda bisa mendapatkan seluruh endpoint dengan mengeklik Salin endpoint di panduan integrasi CRM dan menyimpannya. 
    https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
    • API_VERSION: Versi Marketing API saat ini
    • PIXEL_ID: ID Pixel bisa didapatkan dari Pengelola Peristiwa untuk setiap Pixel
    • ACCESS_TOKEN: Token akses yang dibuat di atas
  5. Anda dapat melihat rilis dan tanggal kedaluwarsa Marketing API di dokumentasi Versi API. Pastikan untuk memperbarui versi API atau Meta Business SDK dalam kode Anda sebelum tanggal kedaluwarsa Marketing API. Menggunakan versi yang dihentikan dalam kode Anda dapat menyebabkan kesalahan dan peristiwa Anda dibuang oleh sistem.

Langkah 3: Uji payload (opsional)

Pada titik ini, Anda sebaiknya mengirim payload pengujian ke Pixel sebelum menerapkan kode pada server. Anda dapat melakukannya dengan menggunakan tab Peristiwa Pengujian di Pengelola Peristiwa.

  1. Di bagian Peristiwa Pengujian Server, klik tautan Graph API Explorer. Menggunakan tautan unik ini akan mengisikan beberapa informasi dari Pixel Anda secara otomatis. (Anda juga dapat langsung mengakses Graph API Explorer jika Anda menginginkannya.) Perhatikan nilai test_event_code, yang dapat berubah seiring waktu.

  2. Lengkapi hal berikut di fitur Graph API Explorer:
    1. Pastikan Anda berada dalam mode POST.
    2. Periksa apakah versi API dan ID Pixel Anda sudah benar.
    3. Beralih ke tampilan JSON.
    4. Masukkan payload Anda. Payload ini dapat dibuat secara manual atau dibuat menggunakan Bantuan Payload. Pastikan untuk menyertakan parameter test_event_code dari langkah sebelumnya dan lead_id yang valid.
  3. Masukkan token akses Pixel Anda, lalu klik tombol Kirim.

  4. Jika payload Anda tidak berisi kesalahan sintaksis atau API, Anda akan menerima pesan keberhasilan dengan fbtrace_id.

  5. Peristiwa pengujian akan muncul di bawah tab Peristiwa Pengujian di Pengelola Peristiwa setelah beberapa saat.

Langkah 4: Kirimkan data produksi

Data produksi harus dalam format yang sama dengan payload yang dibuat di Langkah 3, kecuali bahwa data akan datang langsung dari server Anda. Langkah ini akan berbeda-beda untuk setiap integrasi, sehingga bagian ini akan memberikan panduan secara umum, bukan panduan langkah demi langkah.

  1. Kirimkan lead_id, bukan PII, untuk pencocokan.

  2. Pastikan untuk mengirim semua tahap prospek saat diperbarui, termasuk peristiwa prospek mentah yang mewakili semua prospek yang dibuat di Meta dan diunduh ke dalam CRM Anda. Di bawah ini merupakan contoh corong. Nama dan tahap peristiwa ditentukan oleh pengiklan, jadi tidak harus sama dengan contoh ini.


    Jika kampanye Anda menghasilkan 100 prospek, kami akan mengharapkan ada 100 peristiwa "Prospek Mentah" yang diunggah untuk mewakili tahap prospek pertama. Mengirim tahap prospek pertama akan memberi tahu sistem bahwa prospek telah diterima dan diproses. Saat prospek bergerak di corong penjualan, kami mengharapkan ada 70 tahap "Prospek Memenuhi Syarat Marketing", 30 tahap "Peluang Penjualan", dan 15 tahap "Terkonversi" yang akan diunggah.

    Sebagai rangkuman, 100 prospek dihasilkan dari kampanye, tetapi kami mengharapkan ada 215 peristiwa yang akan diunggah dalam contoh skenario ini.

  3. Buat fungsi yang mengambil pembaruan dari API atau database CRM Anda setiap kali status prospek diperbarui. Selanjutnya, kirim payload Anda ke Conversions API Meta dengan menggunakan fungsi khusus atau Meta Business SDK. Pemilihan metode yang paling cocok bergantung pada konfigurasi CRM dan database Anda.

    Variabel direkomendasikan untuk:
    • lead_id
    • event_name
    • event_time
    Sebagai contoh, payload yang secara eksplisit menyatakan nilai-nilai parameter mungkin akan seperti berikut ini: 
    {
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
    Payload yang meneruskan nilai dari database Anda dengan menggunakan variabel mungkin akan seperti ini: 
    {
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}

  4. Unggah data setidaknya sehari sekali. Sebaiknya panggilan ke CRM Anda dilakukan secara real time, tetapi Anda dapat menggunakan metode batch per jam atau harian jika integrasi secara real-time tidak memungkinkan.
    Jika memilih metode batch, pastikan Anda menangkap riwayat perubahan status prospek, alih-alih snapshot prospek pada saat proses batch dilakukan. Misalnya, jika status prospek diperbarui 3 kali di antara batch, kami mengharapkan ada 3 peristiwa untuk prospek ini, bukan hanya pembaruan terakhir.
    Catatan: Setiap batch boleh mencakup hingga 1.000 peristiwa. Jika ada kesalahan dalam batch, seluruh batch akan dibuang, jadi kami SANGAT menyarankan untuk menggunakan batch yang lebih kecil dan menambahkan logika untuk upaya percobaan ulang.

  5. Opsional. Kami menyarankan membuat catatan pesan kesalahan dari panggilan CAPI dan membuat pemberitahuan jika ada masalah. Penanganan pengecualian untuk kesalahan ini juga dianjurkan.

  6. Anda dapat melakukan backfill data Anda hingga 7 hari yang lalu. Perbedaan waktu dihitung antara event_time dan upload_time. Melakukan backfill beberapa data dapat mempercepat proses pelatihan.

    PERINGATAN: Jangan mencoba melakukan backfill data lebih dari 7 hari dengan memodifikasi nilai event_time. Model ini bergantung pada cap waktu yang akurat agar optimal. Melakukan hal tersebut dapat menyebabkan semua data backfill Anda dibuang.

  7. Pastikan bahwa nilai event_time Anda adalah setelah cap waktu pembuatan prospek. Jika tidak, peristiwa Anda mungkin akan dibuang.

  8. Anda akan mulai melihat peristiwa muncul di Pengelola Peristiwa untuk Pixel Anda dalam waktu satu jam jika integrasi sedang mengunggah peristiwa ke Meta. Jangan lupa untuk menggunakan lead_id yang valid di payload Anda agar peristiwa muncul. Buka setiap peristiwa yang dikirim untuk integrasi CRM Prospek Konversi di Pengelola Peristiwa dan periksa apakah peristiwa tersebut memiliki parameter khusus lead_event_source dan event_source yang sudah diisi. Jika peristiwa tidak memiliki parameter ini, peristiwa tidak akan terdaftar sebagai peristiwa Prospek Konversi.
  9. Sistem akan memeriksa apakah peristiwa Anda adalah peristiwa Prospek Konversi yang valid. Setelah 1 hari, centang hijau akan muncul di samping langkah Kirim peristiwa CRM dari integrasi jika peristiwa yang valid terdeteksi.