Mendapatkan ID Aset dan Token Akses

Setelah pengguna menginstal Meta Business Extension, dan Anda memiliki token akses pengguna mereka (yang digunakan untuk melakukan panggilan API untuk pengguna), Anda perlu mendapatkan ID Pixel, ID Bisnis Instagram, ID Halaman, ID Pengelola Bisnis, ID Akun Iklan, ID Katalog (opsional), atau token akses dari pengguna untuk mengonfigurasi fitur yang relevan. ID ini akan digunakan untuk endpoint API dan konfigurasi bisnis.

Dengan solusi OBO, klien bisa mendapatkan token akses, menggunakan token akses pengguna sistem admin Pengelola Bisnis partner, dan bukan hanya token akses admin Pengelola Bisnis klien.

Mengumpulkan ID untuk Endpoint API dan Konfigurasi Bisnis

Inilah cara untuk mendapatkan informasi itu:

• Webhooks—Wajib bagi semua partner platform yang ingin tercantum dalam daftar di App Store
• Endpoint API Penginstalan MBE—Direkomendasikan untuk bisnis yang di-hosting sendiri

Pembuatan Pengguna Sistem

Setelah pengguna menginstal MBE, ekstensi membuat pengguna sistem karyawan pada Pengelola Bisnis klien. Penamaan untuk pengguna sistem baru ini mengikuti skema {App Name} System User (FBE).

Pengguna sistem mewakili server atau perangkat lunak yang melakukan panggilan API ke aset yang dimiliki atau dikelola oleh Pengelola Bisnis.

Pengguna sistem ini memiliki izin ke semua aset MBE terkait dengan izin tugas berikut:

1. Halaman: 'MANAGE'
2. Akun Iklan: 'MANAGE'
3. Katalog: 'MANAGE'
4. Pixel: 'EDIT'

Mendapatkan Token Pengguna Sistem dengan API

Jika Anda menerima token akses pengguna melalui Webhooks atau Login Bisnis setelah penginstalan MBE, Anda dapat menggunakan token yang sama untuk mendapatkan token akses pengguna sistem Pengelola Bisnis. Untuk melakukannya, lakukan panggilan API berikut:

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

Untuk kolom scope, gunakan izin manage_business_extension, tetapi tergantung penggunaan Anda, mungkin ads_management atau catalog_management juga diperlukan.

Untuk kolom access_token, Anda dapat meneruskan token akses pengguna (user_access_token) atau Token Akses Pengguna Sistem Pengelola Bisnis Partner (partner_bm_admin_system_user_token). Pelajari selengkapnya tentang Token Akses Bisnis.

Webhooks

Untuk menerima pembaruan cepat tentang penginstalan, penghapusan penginstalan, dan konfigurasi ulang MBE, kami mengaktifkan peristiwa Webhooks setiap kali salah satu bisnis Anda menginstal, mengubah, atau menghapus penginstalan MBE.

Setiap kali pengguna menginstal atau mengubah MBE, aplikasi Anda harus memeriksa konfigurasi Webhooks untuk memahami aset apa yang telah diubah, ditambahkan, atau dihapus pengguna dari koneksi mereka dengan aplikasi Anda. Perilaku aplikasi Anda harus diperbarui berdasarkan aset terbaru yang terhubung.

Persyaratan Pengaturan

1. Buat endpoint pada server aman yang dapat memproses permintaan dari Facebook: Permintaan Verifikasi (GET) dan Notifikasi Peristiwa (POST).
2. Konfigurasikan langganan Webhooks MBE di Dasbor Aplikasi:
   • Di bagian Meta Business Extension pada Dasbor Aplikasi, buka tab Pengaturan, gulir ke bawah ke kartu Webhooks, lalu klik Edit URL Panggilan Balik.
   • Masukkan URL endpoint Anda di kolom URL Panggilan Balik dan masukkan string di kolom Verifikasikan Token. Kami akan menyertakan string ini di semua Permintaan Verifikasi.
   • Setelah Anda mengeklik Verifikasikan dan Simpan, kami akan mengirim permintaan verifikasi ke endpoint Anda yang harus Anda validasi.
   • Akan berlangganan Webhooks fbe_install secara otomatis. Kartu ini juga dilengkapi pengalih yang dapat digunakan untuk menonaktifkan berlangganan jika diperlukan.

Parsing peristiwa Webhooks

Setiap kali penginstalan Webhooks diterima, aplikasi Anda perlu melakukan tindakan berikut.

Untuk penginstalan baru

1. Simpan token akses dan jenis token, serta rekam aset yang aksesnya telah diberikan ke aplikasi Anda.
2. Aktifkan set fitur berdasarkan aset mana yang telah diberikan.
3. Jika aset wajib untuk fitur tertentu tidak ada, nonaktifkan fitur tersebut. Contoh: jika aplikasi Anda telah diberikan akses ke katalog, tetapi bukan pixel, hanya terapkan fitur yang didukung oleh katalog, bukan fitur yang didukung oleh pixel.
4. Beri tahu pengguna melalui pembaruan tentang perilaku aplikasi Anda berdasarkan aset yang dapat mereka akses.

Untuk penginstalan yang sudah ada

1. Perbarui token akses, jenis token, dan rekaman aset yang aksesnya telah diberikan ke aplikasi Anda.
2. Perbarui set fitur yang akan diterapkan aplikasi Anda untuk bisnis ini berdasarkan aset mana yang telah diberikan.
3. Beri tahu pengguna melalui pembaruan tentang perilaku aplikasi Anda berdasarkan aset yang dapat mereka akses.

Parsing Webhooks saat menghapus penginstalan

Lakukan langkah berikut saat menghapus penginstalan:

1. Nonaktifkan fitur yang diterapkan aplikasi Anda untuk bisnis ini.
2. Beri tahu bisnis tentang perubahan konfigurasinya.

Yang Disertakan bersama Payload Webhooks

Kolom Tanggapan

Contoh — Payload dengan kolom onsite_commerce_eligible Boolean

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            "feature_name" : string, 
            "feature_type": enum,
            "connected_assets": {
                "ad_account_id": "<ad_account_id>",
                "business_manager_id": "<business_manager_id>",
                "catalog_id": "<catalog_id>",
                "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
                "ig_profile_id": "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

API Penginstalan MBE

Untuk bisnis apa pun yang telah menginstal MBE, Anda dapat melakukan kueri informasi penginstalan dasar (pixel_id dan daftar profil dengan IG Business ID and/or Page ID) menggunakan endpoint berikut:

Contoh

CURL -X GET 'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Tanggapan

{
  "data": [{
    "token_type": "<token_type>"
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

Tanggapan mencakup kolom berikut. Ini sekarang merupakan sumber kebenaran dalam aset yang terhubung dengan daftar “installed_features”:

Tanggapan API Konfigurasi Fitur

Model yang diperbarui mencakup ID instance fitur untuk setiap fitur dan kolom yang terdiri dari array semua fitur dari jenis yang diinstal oleh bisnis tersebut (contoh: beberapa CTA halaman).

Untuk fitur yang tidak dapat disesuaikan, hanya ID instance fitur dan tampilan bendera yang diaktifkan. Anda hanya dapat memperbarui fitur yang dapat disesuaikan dengan permintaan POST.

Model ini berbeda dari API Penginstalan MBE karena model ini menyediakan informasi fitur tambahan di luar aset yang terhubung, termasuk status diaktifkan dan penyesuaian fitur tertentu. Setelah memanggil API Penginstalan MBE, gunakan API ini jika perlu informasi selengkapnya tentang status atau konfigurasi fitur yang diaktifkan.

Membaca

Anda dapat membaca status konfigurasi fitur saat ini dari bisnis apa pun dengan permintaan berikut:

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Memperbarui

Untuk memperbarui semua fitur, gunakan permintaan POST berikut:

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

Tanggapan

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

Langkah Berikutnya

• Mengonfigurasi Fitur Bisnis
• Memicu Peristiwa Pixel
• Memperbarui Katalog Anda