Installazione di app e generazione, aggiornamento e revoca di token

Poiché un utente di sistema rappresenta le chiamate al server, non dispone di Facebook Login e non può installare un'app o seguire il flusso oAuth di Facebook standard per generare un token. Devi eseguire queste operazioni tramite chiamate API.

Tipi di token d'accesso di sistema

Tipi	Token d'accesso senza scadenza	Token d'accesso con scadenza suggeriti
Durata	Non scade mai	Valido per 60 giorni
Aggiornamento necessario?	No	Sì
Consiglio basato sui casi d'uso	Puoi tollerare il rischio che i token d'accesso vengano divulgati e vuoi che le tue applicazioni di terzi abbiano accesso offline ai dati.	Vuoi limitare il rischio che i token d'accesso vengano divulgati.

Installazione di app

Un utente di sistema o un utente di sistema con funzioni avanzate deve installare l'app che verrà usata per generare un token d'accesso. Ciò significa consentire all'app di effettuare chiamate alle API per conto di questo utente di sistema o utente di sistema con funzioni avanzate.

L'utente di sistema e l'app devono appartenere allo stesso Business Manager. È possibile installare solo app almeno con livello di accesso Standard all'API Ads Management.

Ecco di cosa hai bisogno per installare un'app per un utente di sistema:

access_token: di un utente amministratore, un utente di sistema con funzioni avanzate o un altro utente di sistema
business_app: l'ID dell'app da installare

Per installare un'app per l'utente di sistema, effettua una richiesta POST:

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

Se l'installazione avviene correttamente, la chiamata restituisce un risultato booleano. Se una qualsiasi delle limitazioni non viene soddisfatta, visualizzerai un messaggio di errore appropriato.

Generazione di un token d'accesso

Dopo che l'utente di sistema ha installato l'app, può generare un token d'accesso permanente. Sono previste alcune restrizioni:

L'utente di sistema deve aver installato l'app che viene passata nel parametro, come nel passaggio illustrato in precedenza.
Le app possono targetizzare solo le aziende (o le attività secondarie di tali aziende) che le hanno rivendicate.
L'utente di sistema e il proprietario del token d'accesso usato durante questa chiamata API di generazione del token devono appartenere allo stesso Business Manager.
L'app può essere di proprietà dello stesso Business Manager o meno. Se non lo è, si applicano alcune limitazioni. Consulta la sezione qui sotto.

Ecco i parametri per la chiamata API:

business_app: l'app di proprietà del Business Manager a cui appartiene l'utente di sistema.
appsecret_proof: campo calcolato per l'app. Questo parametro è necessario per assicurare che sia il server corretto a effettuare la chiamata API. Per maggiori dettagli, consulta Protezione degli accessi.
scope: stringa separata da virgole contenente le autorizzazioni estese.
access_token: token che appartiene all'amministratore, all'utente di sistema con funzioni avanzate o all'utente di sistema standard di Business Manager.
set_token_expires_in_60_days: impostato su true per generare un token d'accesso dell'utente di sistema con scadenza. Opzionale.

Ambiti supportati per gli utenti di sistema:

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

Autorizzazione obsoleta, visibile soltanto per le app create prima del 24 aprile 2018

publish_actions

Autorizzazioni limitate per funzionalità

Funzionalità	Autorizzazione
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`

Per generare una appsecret_proof, puoi usare il codice PHP:

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

Nell'esempio di codice qui sopra, app_secret_for_the_app_used_in_the_call fa riferimento alla chiave segreta per l'app usata per la generazione del token d'accesso. La chiave segreta è disponibile nella Dashboard gestione app.

appsecret_proof in formato hash deve essere una stringa come "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Per generare un token d'accesso permanente dell'utente di sistema, effettua una richiesta 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"

Per generare un token d'accesso dell'utente di sistema, effettua una richiesta 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"

In precedenza l'endpoint era denominato /APP-SCOPED-SYSTEM-USER-ID/ads_access_token. Le chiamate a quel nome non funzionano più.

La risposta restituisce la stringa del token d'accesso. Se una qualsiasi delle limitazioni non viene soddisfatta, vengono restituiti i codici di errore appropriati. Risposta:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Puoi anche generare un token d'accesso dell'utente di sistema usando l'interfaccia utente di Business Manager.

Aggiornamento del token d'accesso

Un token dell'utente di sistema con scadenza è valido per 60 giorni dal momento in cui viene generato o aggiornato. Per creare continuità, lo sviluppatore deve aggiornare il token d'accesso entro 60 giorni. Se non viene aggiornato, il token d'accesso non è più valido e lo sviluppatore deve generarne uno nuovo per riottenere l'accesso all'API.

Per aggiornare un token d'accesso dell'utente di sistema con scadenza, hai bisogno di:

fb_exchange_token: un token d'accesso dell'utente di sistema valido
client_id: ID dell'app
client_secret: chiave segreta
set_token_expires_in_60_days: impostato su true per aggiornare un token d'accesso dell'utente di sistema con scadenza

Interroga l'endpoint GET oauth/access_token.

Esempio di richiesta

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}"

Esempio di risposta

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

Revoca del token d'accesso

Per proteggere il sistema, questo endpoint esegue regolarmente la rotazione dei token o la revoca dei token d'accesso per gli utenti del sistema compromessi.

Per revocare un token d'accesso dell'utente di sistema, hai bisogno di:

revoke_token: il token d'accesso da revocare
client_id: ID dell'app
client_secret: chiave segreta
access_token: token d'accesso per identificare il chiamante

I requisiti sono i seguenti:

Il client_id deve corrispondere all'app reale e devi assicurarti che l'app non sia in throttling, disabilitata o eliminata.
Il client_id insieme all'app installata di revoke_token, all'app installata di access_token e al client_secret devono essere tutti uguali.

Interroga l'endpoint GET oauth/revoke.

Esempio di richiesta

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}"

Esempio di risposta

{
  "success":"true",
}

Rotazione dei token d'accesso

La rotazione dei token è una misura di sicurezza che può consentire di ridurre i rischi, ad esempio limitando i danni provocati da token divulgati. Modificando regolarmente i token di accesso, è possibile limitare il potenziale danno causato da un token divulgato o smarrito, in modo molto simile alla modifica delle password. Attualmente, il nostro sistema supporta la rotazione dell'utente di sistema senza tempi di inattività. Per farlo, segui queste istruzioni:

Aggiorna il token d'accesso dell'utente di sistema tramite l'API SUAT Refresh. L'API SUAT Refresh restituirà un nuovo token d'accesso dell'utente di sistema e il nuovo token è valido per 60 giorni dalla data di aggiornamento. Il token precedente continua a funzionare fino alla scadenza (data di creazione + 60).
Distribuisci il nuovo token d'accesso dell'utente di sistema.
Revoca il token d'accesso dell'utente di sistema precedente tramite l'API SUAT Revocation. L'invalidazione avviene immediatamente e il token non può essere più utilizzato dopo la revoca.