Conversions API Gateway untuk Beberapa Akun - Control Plane API

Integrasi Mitra

Ringkasan

Conversions API Gateway untuk beberapa akun - control plane API adalah set API GraphQL yang diekspos dari instance Gateway. Hal ini memungkinkan developer untuk mengelola akun, sumber data, dan konfigurasi lain dari instance Gateway secara terprogram. Mitra dapat mengintegrasikan API untuk membuat UI yang dapat dilihat pengiklan mereka dan menawarkan sebuah alur onboarding dan pengelolaan yang lancar kepada pengiklan.

Kasus penggunaan potensial:

Pengiklan melakukan onboarding ke Gateway menggunakan UI mitra dan melakukan tindak lanjut melalui pengaturan admin Gateway. Hal ini memerlukan integrasi parsial dari control plane API.
Pengiklan melakukan semua tindakan di UI mitra, termasuk onboarding ke Gateway dan tindak lanjut. Ini bisa menjadi kasus penggunaan yang baik untuk mitra yang tidak ingin mengekspos UI Gateway tetapi masih ingin menyediakan Gateway sebagai layanan untuk pengiklan. Hal ini memerlukan integrasi penuh dari control plane API.

Lihat bagian di bawah ini untuk rincian selengkapnya tentang langkah-langkah integrasi.

Conversions API Gateway untuk beberapa akun - control plane API atau Gateway digunakan secara bergantian dalam dokumen ini.

Panduan Integrasi

Tergantung pada kasus penggunaan, bisa ada dua jalur integrasi (seperti yang ditunjukkan pada bagan di bawah):

Integrasi parsial dari control plane API. Hal ini tidak memerlukan autentikasi dari pengiklan.
Integrasi penuh dengan control plane API. Ini membutuhkan autentikasi dari pengiklan baik menggunakan Meta Business Extension (MBE) atau pembuatan token secara manual.

Prasyarat

Untuk kedua jalur integrasi, mitra harus terlebih dahulu menyelesaikan langkah-langkah di bawah:

Langkah 1: Onboard sebagai penyelenggara dari instance Gateway

Langkah 2: Buat nama akun API dan secret key API

Buka:

https://<Conversions API Gateway Endpoint>/hub/

Buka Tab pengaturan Penyelenggara, pilih Halaman Kelola akun API, dan klik tombol akun Tambahkan API.

Masukkan kembali kata sandi Anda. Klik Lanjut.

Masukkan nama akun API. Klik Lanjut.

Nama akun hanya boleh terdiri dari huruf dan angka, dan tidak boleh berisi spasi. Panjang maksimalnya adalah 20.

Salin dan simpan secret key yang dibuat. Anda tidak akan bisa melihatnya lagi.

Untuk menghapus akun API, klik Hapus akun API. Harap diperhatikan bahwa tindakan ini tidak dapat diubah dan berpotensi menyebabkan gangguan pada aplikasi atau layanan pengiklan mana pun yang menggunakan API.

Integrasi Parsial

Kasus penggunaan berdasarkan integrasi parsial:

Pengiklan memilih layanan Gateway menggunakan UI mitra.
Mitra membuat tautan undangan yang dapat digunakan oleh pengiklan untuk menyiapkan kata sandi dan menyelesaikan pembuatan akun Gateway.
Pengiklan menggunakan fungsionalitas pada UI Gateway untuk melakukan tindakan seperti pengelolaan sumber data serta pengelolaan pengguna akun, domain, dan routing.
Mitra mengambil penggunaan akun pengiklan dan tagihan yang sesuai.

Alur pengguna tingkat tinggi mungkin terlihat seperti di bawah:

Untuk mencapai hal di atas, mitra dapat mengintegrasikan subset dari control plane API, termasuk:

Dapatkan Token Akses API
Buat Akun untuk pengiklan
Dapatkan Penggunaan Akun, contoh, untuk keperluan tagihan

Integrasi Penuh

Sebuah kasus penggunaan berdasarkan integrasi penuh:

Pengiklan memilih layanan Gateway menggunakan UI mitra.
Mitra melakukan onboard ke akun Gateway pengiklan dan menerima izin untuk mengelola akun; pengiklan memberi otorisasi mitra menggunakan Meta Business Extension (MBE) atau pembuatan token manual.
Pengiklan dapat melakukan pengelolaan sumber data serta pengelolaan pengguna akun, domain, dan routing di UI mitra.
Mitra mengambil penggunaan akun pengiklan dan tagihan yang sesuai.

Alur pengguna tingkat tinggi mungkin terlihat seperti di bawah:

Untuk jalur integrasi ini, mitra perlu meminta izin dan mendapatkan token akses pengguna sistem melalui autentikasi untuk mengirim peristiwa atas nama pengiklan.

Autentikasi

Mitra memiliki dua opsi autentikasi berikut untuk Pixel Meta yang tidak dikelola oleh mereka:

Opsi 1 - Meta Business Extension (MBE)

Sebelum Anda memulai, Anda harus:

Lengkapi semua persyaratan untuk menerapkan MBE
Hubungi perwakilan Meta Anda untuk menambahkan aplikasi Anda ke daftar yang diizinkan untuk Izin Pribadi: open_bridge_configuration_management

MBE menyediakan endpoint untuk mengambil token akses pengguna sistem yang dibuat di Pengelola Bisnis pengiklan. Mitra dapat menindaklanjuti ke Langkah 4 dari panduan integrasi MBE. Pastikan bahwa Anda:

Atur nilai parameter saluran dalam objek konfigurasi pengaturan sebagai CONVERSIONS_API_GATEWAY_ADVERTISER.
Dapat menerima tanggapan webhook pada saat penyelesaian onboarding.
Gunakan token akses yang ditampilkan melalui MBE dan ubah menjadi Token Akses Pengguna Sistem dengan melakukan panggilan API tambahan.
Simpan salinan external_business_id, pixel_id, business_id dan token akses pengguna sistem di sistem Anda.

Opsi 2 - Token Akses Pengguna Sistem Klien

Dengan opsi ini, mitra mungkin memiliki pengiklan:

Secara manual membuat token akses pengguna sistem melalui Conversions API di dalam Pengaturan di Pengelola Peristiwa (EM)
Bagikan pixel_id, business_id dan token akses pengguna sistem dengan mitra dan simpan salinannya.

Integrasi

Mitra dapat mengintegrasikan set lengkap control plane API. Rincian lebih lanjut tercakup dalam Referensi API.

Paritas API dan UI

Kami memberlakukan paritas API dan UI dengan mengekspos endpoint API yang sama dengan yang digunakan di Gateway UI. Namun, setiap endpoint API yang tidak tercakup dalam Referensi API dapat berubah di pengembangan masa mendatang. Untuk meminimalkan dampak tak terduga, endpoint API yang tidak ditemukan tersebut menampilkan Kode kesalahan: 418. Anda masih bisa menggunakan API tetapi dengan risiko Anda sendiri.