Marketing API

Penetapan Versi

Versi Marketing API saat ini adalah v21.0.

Platform Facebook memiliki model penetapan versi core dan diperluas. Dengan penetapan versi Marketing API, semua perubahan yang dapat menyebabkan gangguan akan dilakukan di versi baru. Beberapa versi API atau SDK Marketing dapat hadir secara bersamaan dengan fungsi yang berbeda di setiap versi.

Developer harus memahami terlebih dahulu kapan API atau SDK Marketing akan berubah. Meskipun Anda memiliki waktu 90 hari untuk mengadopsi perubahan, cara dan waktu pemindahan ke versi baru adalah pilihan Anda.

Jadwal Versi

Ketika Marketing API versi baru dirilis, kami akan terus mendukung versi Marketing API sebelumnya selama setidaknya 90 hari. Anda memiliki masa tenggang setidaknya 90 hari untuk pindah ke versi baru. Selama masa tenggang 90 hari, Anda dapat memanggil versi saat ini dan versi yang dihentikan, dan Anda memiliki masa tenggang 90 hari tersebut untuk pindah ke versi baru. Setelah masa tenggang 90 hari berakhir, versi yang dihentikan akan berhenti berfungsi. Setelah suatu versi tidak tersedia, panggilan apa pun yang dilakukan ke nomor versi tersebut mungkin gagal atau ditingkatkan ke versi yang tersedia berikutnya.

Contoh, Marketing API versi v17.0 dirilis pada 23 Mei 2023, dan Marketing API versi v16.0 kedaluwarsa pada 6 Februari 2024, sehingga ada waktu setidaknya 90 hari untuk pindah ke versi baru.

Berikut adalah contoh linimasa. Perhatikan bahwa kami mungkin tidak selalu merilis versi baru pada akhir masa tenggang penghentian versi sebelumnya selama 90 hari tersebut. Dalam contoh ini, v16.0 telah dihentikan beberapa saat sebelum v18.0 dirilis:

Untuk SDK, suatu versi selalu tersedia karena merupakan paket yang dapat diunduh, tetapi setelah tanggal akhir masa pakainya, versi tersebut mungkin bergantung pada Marketing API atau metode yang tidak lagi berfungsi, jadi Anda harus berasumsi bahwa SDK yang sudah berakhir masa pakainya tidak lagi berfungsi.

Membuat Permintaan Berversi

Semua endpoint API Marketing tersedia melalui jalur berversi. Tambahkan versi di awal jalur permintaan. Contoh:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

Ini berfungsi untuk semua versi, dalam bentuk umum ini:

https://graph.facebook.com/v{n}/{request-path}

dengan n merupakan versi yang dibutuhkan. Lihat daftar lengkap versi yang tersedia di Catatan Perubahan kami. Semua Referensi Marketing API kami menyediakan informasi per versi.

Migrasi

Migrasi hanya untuk skenario khusus yang memerlukan perubahan yang tidak dapat dilakukan dalam penetapan versi. Biasanya, hal ini terjadi jika model data yang mendasarinya telah berubah. Migrasi berlaku di semua versi.

Migrasi yang saat ini masih berlangsung tercantum di halaman migrasi kami. Migrasi memiliki setidaknya jangka waktu 90 hari dan selama itu Anda harus memigrasikan aplikasi Anda. Setelah jangka waktu dimulai, perilaku pascamigrasi akan menjadi default untuk aplikasi baru. Kemudian, ketika jangka waktu migrasi selesai, perilaku pramigrasi sama sekali tidak tersedia.

Mengelola Migrasi melalui Graph API

Migrasi dapat dikelola melalui kolom migrasi di node /app:

Anda dapat melakukan panggilan pembaruan di edge untuk mengaktifkan dan menonaktifkan migrasi.

Mengelola Migrasi melalui Dasbor Aplikasi

Anda dapat mengaktifkan dan menonaktifkan migrasi yang tersedia di Dasbor Aplikasi di bagian Pengaturan > Migrasi. Perhatikan bahwa daftar migrasi mungkin tidak sama seperti pada gambar di bawah, karena migrasi yang tersedia berbeda untuk aplikasi yang berbeda, pada saat yang berbeda. Dan jika Anda melihat migrasi Use Graph API v2.0 by default, migrasi ini hanya untuk Graph API, bukan API Pemasaran.

Aktivasi Migrasi Sisi Klien Sementara

Daripada mengaktifkan migrasi di Dasbor Aplikasi Anda, atau melalui Marketing API, Anda dapat menambahkan tanda khusus ke panggilan Marketing API Anda yang mengatur migrasi. Tanda ini disebut migrations_override dan mengharuskan Anda menentukan blob JSON yang menjelaskan migrasi apa yang ingin Anda aktifkan atau nonaktifkan. Contohnya, jika Anda melakukan panggilan mentah, Anda dapat menyampaikan:

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

Dengan menggunakan ini, Anda dapat memanggil API Pemasaran baru melalui pembaruan klien alih-alih harus membuat semua penelepon melakukan pembaruan untuk memanggil API Pemasaran baru secara bersamaan. Cara ini juga sangat berguna untuk debugging.

Nama-nama migrasi ini dapat ditemukan di node /app yang disebutkan di atas.

Peningkatan versi otomatis

Mengingat cepatnya rotasi versi Marketing API yang terjadi sekitar empat bulan sekali, kami merampingkan proses peningkatan. Mulai Mei 2024, kami akan mengaktifkan fitur peningkatan versi otomatis untuk endpoint Marketing API yang tidak terpengaruh antarversi. Hal ini berarti antara versi yang akan dihentikan dan versi yang tersedia berikutnya, jika endpoint tidak terpengaruh, platform akan meningkatkan panggilan ke versi yang tersedia berikutnya, alih-alih langsung menggagalkan permintaan. Perubahan ini dirancang untuk memastikan pengalaman API yang lebih lancar dan lebih efisien.

Contoh, pada 14 Mei 2024, v17.0 akan dihentikan. Menurut catatan perubahan v18.0, endpoint berikut ini akan terpengaruh:

  • POST /act_{ad-account-id}/reachfrequencypredictions
  • GET /act_{ad-account-id}/reachestimate
  • GET /act_{ad-account-id}/delivery_estimate
  • POST /act_{ad-account-id}/adsets
  • POST /{adset-id}
  • POST /act_{ad-account-id}/saved_audiences
  • POST /{saved-audience-id}
  • POST /act_{ad-account-id}/credit_cards

Jika aplikasi Anda memanggil POST /{adset-id} dengan v17.0 setelah versi tersebut dihentikan pada 14 Mei 2024, permintaan API ini akan gagal karena peningkatan otomatis tidak diterapkan pada endpoint yang terpengaruh oleh versi yang tersedia berikutnya (v18.0).

Jika aplikasi Anda memanggil GET /{ad-account-id}/insights dengan v17.0 setelah penghentian, platform akan meningkatkan panggilan Anda ke versi yang tersedia berikutnya (v18.0).

Catatan: Jika aplikasi Anda sudah melakukan panggilan dengan versi yang lebih tinggi dari v17.0, seharusnya tidak ada perubahan pada tanggal penghentian versi.

Untuk memeriksa endpoint yang terpengaruh pada setiap versi, lihat Catatan Perubahan Marketing API.

Pertanyaan Umum

Jadwal Versi

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

Tautan Permanen

You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.

Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.

For example:

  • If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
  • If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
  • Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.

If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:

  • If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
  • If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
Tautan Permanen

There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
Tautan Permanen

Membuat Permintaan Berversi

With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:

https://graph.facebook.com/v{n}/{request-path}

You can know what behavior to expect out without having to manually visit your app's migration panel.

Tautan Permanen

Peningkatan versi otomatis

The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.

Tautan Permanen

No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons

  • You may still need to manually upgrade endpoints being impacted by next version.
  • You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
Tautan Permanen

You can look up affected endpoints from Marketing API Changelog.

Tautan Permanen

You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.

Tautan Permanen

If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.

Example notification header

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''
Tautan Permanen