Ottenimento di ID risorsa e token d'accesso

Dopo che l'utente ha installato l'estensione Facebook Business e tu disponi del token d'accesso dell'utente (utilizzato per effettuare chiamate API per l'utente), devi ottenere l'ID del pixel, l'ID Instagram Business, l'ID Pagina, l'ID Business Manager, l'ID account pubblicitario, l'ID catalogo (facoltativo) o il token d'accesso dell'utente per configurare le funzioni pertinenti. Questi ID saranno usati per gli endpoint dell'API e le configurazioni aziendali.

Con la soluzione OBO, il cliente può ottenere il token d'accesso, usando anche il token d'accesso dell'utente del sistema con funzioni di amministratore del Business Manager del partner invece del token d'accesso dell'amministratore del Business Manager del cliente.

Acquisizione degli ID per gli endpoint dell'API e le configurazioni aziendali

Ecco come ottenere queste informazioni:

• Webhook: obbligatorio per tutti i partner della piattaforma che vogliono essere riportati nell'App Store.
• Endpoint dell'API FBE Installs: consigliato per le aziende self-hosted.

Creazione dell'utente di sistema

Dopo che un utente installa l'estensione Facebook Business, quest'ultima genera un utente di sistema del dipendente sul Business Manager del cliente. La denominazione per questo nuovo utente di sistema segue lo schema {App Name} System User (FBE).

Gli utenti di sistema rappresentano server o software che effettuano chiamate API alle risorse di proprietà o gestite da un Business Manager.

Questo utente di sistema dispone delle autorizzazioni per tutte le risorse dell'estensione Facebook Business associate alle seguenti autorizzazioni di attività:

1. Pagina: 'MANAGE'
2. Account pubblicitario: 'MANAGE'
3. Catalogo: 'MANAGE'
4. Pixel: 'EDIT'

Ottenimento del token dell'utente di sistema tramite l'API

Se ricevi un token d'accesso dell'utente tramite un webhook o il Business Login dopo l'installazione dell'estensione Facebook Business, puoi usare lo stesso token per ottenere il token d'accesso dell'utente di sistema del Business Manager. Per farlo, effettua la seguente chiamata API:

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

Per il campo scope, usa l'autorizzazione manage_business_extension ma, in base al tuo caso d'uso, potrebbero essere necessari anche ads_management o catalog_management.

Per il campo access_token, puoi passare un token d'accesso dell'utente (user_access_token) o un token d'accesso dell'utente del sistema con funzioni di amministratore del Business Manager (partner_bm_admin_system_user_token). Ulteriori informazioni sul token d'accesso aziendale.

Webhook

Per ricevere aggiornamenti tempestivi su installazioni, disinstallazioni e riconfigurazioni dell'estensione Facebook Business, attiviamo eventi webhook ogni volta che una delle tue aziende installa, modifica o disinstalla l'estensione.

Ogni volta che un utente installa o modifica l'estensione Facebook Business, la tua app dovrebbe ispezionare la configurazione del webhook per capire quali risorse l'utente ha modificato, aggiunto o rimosso dalla propria connessione con la tua app. Il comportamento della tua app dovrebbe essere aggiornato sulla base delle risorse connesse più recenti.

Requisiti di configurazione

1. Crea un endpoint su un server sicuro in grado di elaborare le richieste da Facebook: richieste di verifica (GET) e notifiche degli eventi (POST).
2. Configura l'iscrizione ai webhook dell'estensione Facebook Business nella Dashboard gestione app:
   • Nella sezione Estensione Facebook Business della Dashboard gestione app, vai alla tab Configurazione, scorri verso il basso fino alla scheda Webhook, quindi clicca su Modifica l'URL di callback.
   • Inserisci l'URL del tuo endpoint nel campo URL di callback e inserisci una stringa nel campo Verifica il token. Includeremo questa stringa in tutte le Richieste di verifica.
   • Dopo aver cliccato su Verifica e salva, invieremo all'endpoint una richiesta di verifica che dovrai convalidare.
   • L'iscrizione al webhook fbe_install sarà automatica. La scheda presenta anche un pulsante che può essere usato per disattivare l'iscrizione se necessario.

Analisi degli eventi webhook

Ogni volta che viene ricevuto un webhook di installazione, l'app deve eseguire le seguenti azioni.

Per le nuove installazioni

1. Memorizza il token d'accesso e il relativo tipo e registra le risorse per cui è stato concesso l'accesso alla tua app.
2. Abilita l'insieme di funzioni in base alle risorse concesse.
3. Se manca una risorsa necessaria per una funzione specifica, disabilita solo quella funzione. Ad esempio, se alla tua app è stato concesso l'accesso a un catalogo, ma non a un pixel, implementa solo la funzione del catalogo e non quella del pixel.
4. Usa un aggiornamento per informare l'utente del comportamento della tua app in base alle risorse a cui ha accesso.

Per le installazioni esistenti

1. Aggiorna il token d'accesso, il relativo tipo e il record delle risorse per cui è stato concesso l'accesso alla tua app.
2. Aggiorna l'insieme di funzioni che la tua app implementerà per questa azienda in base alle risorse concesse.
3. Usa un aggiornamento per informare l'utente del comportamento della tua app in base alle risorse a cui ha accesso.

Analisi del webhook alla disinstallazione

Esegui i passaggi seguenti al momento della disinstallazione:

1. Disabilita le funzioni che la tua app implementa per questa azienda.
2. Informa l'azienda della modifica alla sua configurazione.

Cosa è incluso con il payload del webhook

Campi della risposta

Esempio: payload con campo onsite_commerce_eligible booleano

{
  "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 FBE Installation

Per un'azienda che ha installato l'estensione Facebook Business, puoi richiedere informazioni di base sull'installazione (pixel_id e una lista di profili con un IG Business ID and/or Page ID) utilizzando il seguente endpoint:

Esempio

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>'

Risposta

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

La risposta include i campi seguenti, che rappresentano la fonte di dati nelle risorse connesse della lista “installed_features”:

Risposta dell'API Feature Configuration

Il modello include l'ID istanza per ogni funzione e campi costituiti da un array di tutte le funzioni di quel tipo installate dall'azienda (esempio: CTA per più pagine).

Per le funzioni non personalizzabili, vengono visualizzati solo un ID istanza della funzione e il contrassegno che indica che la funzione è abilitata. Con una richiesta POST puoi aggiornare solo le funzioni personalizzabili.

Questo modello differisce dall'API FBE Installation perché fornisce informazioni aggiuntive sulle funzioni oltre alle risorse connesse, quali lo stato di abilitazione e personalizzazioni specifiche. Dopo aver chiamato l'API FBE Installation, usala se sono necessarie più informazioni sullo stato di abilitazione o sulle configurazioni della funzione.

Lettura

È possibile leggere lo stato di configurazione delle funzioni correnti di qualsiasi azienda con la seguente richiesta:

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

Aggiornamento

Per aggiornare tutte le funzioni, effettua la seguente richiesta POST:

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"

Risposta

{
  "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,
    },
  ],
  ...
}

Passaggi successivi

• Configurazione delle funzioni aziendali
• Attivazione degli eventi del pixel
• Aggiornamento del catalogo