Menginstal Aplikasi, Membuat, Memuat Ulang, dan Membatalkan Token

Karena pengguna sistem mewakili panggilan server, ia tidak memiliki Facebook Login dan tidak dapat menginstal aplikasi atau melalui alur oAuth Facebook standar untuk membuat token. Anda perlu melakukan ini melalui panggilan API.

Jenis Token Akses Sistem

Jenis Token Akses yang Tidak Kedaluwarsa Saran Token Akses yang Akan Kedaluwarsa

Sepanjang masa

Tidak pernah kedaluwarsa

Berlaku selama 60 hari

Perlu muat ulang?

Tidak

Ya

Rekomendasi berdasarkan kasus penggunaan

Anda dapat menoleransi risiko token akses bisa dibocorkan dan ingin aplikasi pihak ketiga Anda memiliki akses offline ke data.

Anda ingin membatasi risiko token akses dibocorkan.

Menginstal Aplikasi

Pengguna sistem atau pengguna sistem admin harus menginstal aplikasi yang akan digunakan untuk membuat token akses. Artinya, mengizinkan aplikasi memanggil API atas nama pengguna sistem ini atau pengguna sistem admin.

Baik pengguna sistem dan aplikasi harus dimiliki oleh Pengelola Bisnis yang sama. Hanya aplikasi dengan Ads Management API akses standar ke atas yang dapat diinstal.

Untuk menginstal aplikasi bagi pengguna sistem, Anda memerlukan:

  • access_token: dari pengguna admin, pengguna sistem admin, atau pengguna sistem lain
  • business_app: ID dari aplikasi yang diinstal.

Untuk menginstal aplikasi untuk pengguna sistem, buat permintaan POST:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

Panggilan ini menampilkan hasil Boolean, jika penginstalan berhasil. Jika salah satu batasan tidak terpenuhi, Anda akan melihat pesan kesalahan yang sesuai.

Membuat Token Akses

Setelah pengguna sistem menginstal aplikasi, itu dapat membuat token akses yang bertahan. Beberapa batasan berlaku:

  • Pengguna sistem harus menginstal aplikasi yang diteruskan dalam parameter, seperti yang terlihat pada langkah di atas.
  • Aplikasi hanya dapat menargetkan bisnis (atau anak bisnis dari bisnis tersebut) yang telah mengeklaimnya.
  • Pengguna sistem dan pemilik token akses yang digunakan selama panggilan API pembuatan token ini harus dimiliki oleh Pengelola Bisnis yang sama.
  • Aplikasi dapat dimiliki oleh Pengelola Bisnis yang sama, atau tidak. Jika tidak, ada beberapa batasan. Lihat bagian di bawah.

Inilah parameter untuk panggilan API:

  • business_app: aplikasi yang dimiliki oleh Pengelola Bisnis yang memiliki pengguna sistem.
  • appsecret_proof: kolom yang dihitung untuk aplikasi. Ini diperlukan untuk memastikan bahwa server yang benar melakukan panggilan API. Untuk detail selengkapnya, baca Keamanan Login.
  • scope: string yang dipisahkan koma, berisi izin yang diperluas.
  • access_token: token milik admin Pengelola Bisnis, pengguna sistem admin, atau pengguna sistem biasa.
  • set_token_expires_in_60_days: diatur ke true untuk membuat token akses pengguna sistem yang akan kedaluwarsa. Opsional.

Lingkup yang didukung untuk pengguna sistem:

  • ads_management
  • ads_read
  • attribution_read
  • business_management
  • catalog_management
  • commerce_account_manage_orders
  • commerce_account_read_orders
  • commerce_account_read_settings
  • instagram_basic
  • instagram_branded_content_ads_brand
  • instagram_branded_content_brand
  • instagram_content_publish
  • instagram_manage_comments
  • instagram_manage_insights
  • instagram_manage_messages
  • instagram_shopping_tag_products
  • leads_retrieval
  • page_events
  • pages_manage_ads
  • pages_manage_cta
  • pages_manage_engagement
  • pages_manage_instant_articles
  • pages_manage_metadata
  • pages_manage_posts
  • pages_messaging
  • pages_read_engagement
  • pages_read_user_content
  • pages_show_list
  • private_computation_access
  • publish_video
  • read_audience_network_insights
  • read_insights
  • read_page_mailboxes
  • whatsapp_business_management
  • whatsapp_business_messaging

Izin yang Tidak Berlaku Lagi, hanya bisa dilihat di aplikasi yang dibuat sebelum 24 April 2018

publish_actions

Izin yang Dibatasi oleh Kemampuan

Kemampuan Izin

business_creative_asset_management

business_creative_managementbusiness_creative_insights
business_creative_insights_sharebusiness_data_management

commerce_public_api_beta_testing

commerce_manage_accountscommerce_account_read_reports

Untuk membuat appsecret_proof, Anda bisa menggunakan kode PHP:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

Dalam contoh kode di atas, app_secret_for_the_app_used_in_the_call merujuk pada rahasia aplikasi untuk aplikasi yang digunakan untuk membuat token akses. Rahasia aplikasi Anda dapat ditemukan di Dasbor Aplikasi Anda.

appsecret_proof yang di-hash haruslah string seperti "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Untuk membuat token akses pengguna sistem permanen, buat permintaan POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Untuk membuat token akses pengguna sistem yang akan kedaluwarsa, buat permintaan POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Endpoint tersebut sebelumnya dinamai /SYSTEM-USER-ID/ads_access_token. Panggilan untuk nama itu tidak berfungsi lagi.

Tanggapan mengembalikan string token akses. Jika salah satu batasan tidak terpenuhi, kode kesalahan yang sesuai akan diberikan. Tanggapan:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Anda juga dapat membuat Token Akses Pengguna Sistem menggunakan UI Pengelola Bisnis.

Memuat Ulang Akses Token

Sistem token pengguna yang akan kedaluwarsa berlaku selama 60 hari sejak dibuat atau dimuat ulang. Untuk menciptakan keberlanjutan, developer harus memuat ulang token akses dalam 60 hari. - Gagal melakukannya akan berakibat kehilangan token akses dan developer perlu mendapatkan token akses baru untuk mendapatkan kembali akses API.

Untuk memuat ulang token akses pengguna sistem yang akan kedaluwarsa, Anda perlu:

  • fb_exchange_token: Token akses pengguna sistem yang valid
  • client_id: ID Aplikasi
  • client_secret: Rahasia Aplikasi
  • set_token_expires_in_60_days: diatur ke true untuk memuat ulang token akses pengguna sistem yang akan kedaluwarsa.

Kuerilah endpoint GET oauth/access_token

Contoh Permintaan

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

Contoh Tanggapan

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

Membatalkan Token Akses

Endpoint ini dimaksudkan untuk melakukan rotasi token reguler atau membatalkan token akses bagi pengguna sistem yang disusupi sebagai sarana untuk melindungi sistem Anda.

Untuk membatalkan token akses pengguna sistem, Anda perlu:

  • revoke_token: Token akses yang akan dibatalkan

  • client_id: ID Aplikasi

  • client_secret: Rahasia Aplikasi

  • access_token: Token akses untuk mengidentifikasi pemanggil

Persyaratannya adalah sebagai berikut:

  • client_id harus sesuai dengan aplikasi yang sebenarnya dan memastikan bahwa aplikasi tidak terhambat, dinonaktifkan, atau dihapus.

  • client_id, bersama dengan aplikasi terinstal dari revoke_token, aplikasi terinstal dari access_token, dan client_secret, semuanya harus sama.

Kuerilah endpoint GET oauth/revoke.

Contoh Permintaan

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

Contoh Tanggapan

{
  "success":"true",
}

Rotasi Token Akses

Rotasi token adalah tindakan keamanan yang dapat membantu memitigasi risiko, misalnya: membatasi kerugian akibat bocornya token akses. Dengan mengubah token akses secara teratur, potensi kerugian yang disebabkan oleh bocornya token akses atau token salah letak dapat dibatasi, seperti halnya mengubah kata sandi. Saat ini, sistem kami mendukung rotasi pengguna sistem tanpa waktu henti. Untuk melakukannya, ikuti petunjuk ini:

  1. Muat Ulang Token Akses Pengguna Sistem melalui API Muat Ulang SUAT. API Muat Ulang SUAT akan menampilkan token akses pengguna sistem yang baru dan token baru berlaku selama 60 hari sejak tanggal token dimuat ulang. Token lama masih bisa berfungsi sampai kedaluwarsa (tanggal pembuatan + 60 hari).

  2. Terapkan Token Akses Pengguna Sistem yang baru.

  3. Batalkan Token Akses Pengguna Sistem lama melalui API Pembatalan SUAT. Invalidasi terjadi segera, dan token tidak dapat digunakan lagi setelah pembatalan.