Obtenir des ID d’élément et un token d’accès

Une fois que l’utilisateur ou l’utilisatrice a installé l’extension Facebook Business et que vous disposez du token d’accès utilisateur·ice (utilisé pour réaliser des appels d’API pour l’utilisateur·ice), vous devez obtenir les ID du pixel, Instagram Business, de Page, Business Manager, du compte publicitaire, du catalogue (facultatif) ou le token d’accès de l’utilisateur·ice pour configurer les fonctionnalités appropriées. Ces ID seront utilisés pour les points de terminaison d’API et les configurations d’entreprise.

Avec la solution OBO, le client peut obtenir le token d’accès de l’utilisateur système admin du compte Business Manager du partenaire, en plus du token d’accès de l’admin de son Business Manager.

Recueillir des ID pour les points de terminaison d’API et les configurations d’entreprise

Voici comment obtenir ces informations :

Création d’un utilisateur système

Une fois qu’un utilisateur ou une utilisatrice a installé FBE, l’extension génère un utilisateur système sur le compte Business Manager du client. La dénomination de ce nouvel utilisateur système suit le schéma {App Name} System User (FBE).

Les utilisateurs système sont les serveurs ou logiciels qui effectuent des appels d’API vers les éléments détenus ou gérés par un compte Business Manager.

Cet utilisateur système dispose des autorisations par tâche suivantes pour tous les éléments FBE associés :

  1. Page : 'MANAGE'
  2. Compte publicitaire : 'MANAGE'
  3. Catalogue : 'MANAGE'
  4. Pixel : 'EDIT'

Obtenir un token d’utilisateur système via l’API

Si vous recevez un token d’accès utilisateur·ice via un webhook ou la connexion d’entreprise après une installation de FBE, vous pouvez utiliser ce token pour obtenir le token d’accès utilisateur système Business Manager. Pour ce faire, exécutez l’appel d’API suivant :

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

Pour le champ scope, utilisez l’autorisation manage_business_extension. Selon votre cas d’utilisation, il se peut que vous deviez également indiquer l’autorisation ads_management ou catalog_management.

Pour le champ access_token, vous pouvez transmettre un token d’accès utilisateur·ice (user_access_token) ou le token d’accès d’un utilisateur système admin du compte Business Manager du partenaire (partner_bm_admin_system_user_token). En savoir plus sur le token d’accès entreprise

Le champ token_type du webhook indique si la valeur access_token reçue est un token d’accès utilisateur·ice ou un token d’accès utilisateur système.

Si l’utilisateur ou l’utilisatrice installe FBE via Instagram, le webhook renverra le token de l’utilisateur système qui a été généré sur le compte Business Manager du client. Vous n’avez pas besoin d’appeler cette API.

Webhook

Pour recevoir des mises à jour rapides concernant les installations, désinstallations et reconfigurations de FBE, nous déclenchons des évènements webhook chaque fois que l’une de vos entreprises installe, modifie ou désinstalle l’extension.

Chaque fois qu’un utilisateur ou une utilisatrice installe ou modifie FBE, votre application doit inspecter la configuration Webhook pour comprendre quels éléments il ou elle a modifiés, ajoutés ou supprimés de sa connexion avec votre application. Le comportement de l’application devrait changer en fonction des derniers éléments connectés.

Conditions requises pour la configuration

  1. Créer un point de terminaison sur un serveur sécurisé capable de traiter les demandes de vérification (GET) et les notifications d’évènement (POST) provenant de Facebook.
  2. Configurer l’abonnement des webhooks FBE dans l’Espace App :
    • Dans la section Extension Facebook Business de l’Espace App, accédez à l’onglet Configuration, faites défiler la page vers le bas jusqu’à la fiche Webhooks, puis cliquez sur Modifier l’URL de rappel.
    • Saisissez l’URL de votre point de terminaison dans le champ URL de rappel et indiquez une chaîne dans le champ Vérifier le token. Nous ajouterons cette chaîne à toutes les demandes de vérification.
    • Lorsque vous aurez cliqué sur Vérifier et enregistrer, nous enverrons à votre point de terminaison une demande de vérification que vous devrez valider.
    • Vous êtes automatiquement abonné·e au webhook fbe_install. La fiche contient également un bouton bascule qui permet de désactiver l’abonnement si besoin.

Analyser les évènements webhook

Chaque fois qu’un webhook d’installation est reçu, votre application doit effectuer les actions suivantes.

Pour les nouvelles installations

  1. Stockez le token d’accès ainsi que son type, et enregistrez les éléments auxquels votre application a désormais accès.
  2. Activez l’ensemble de fonctionnalités qui convient en fonction des éléments auxquels vous avez accès.
  3. S’il vous manque un élément pour une fonctionnalité spécifique, désactivez uniquement cette fonctionnalité. Par exemple, si votre application peut accéder à un catalogue, mais pas à un pixel, implémentez uniquement la fonctionnalité ayant besoin d’accéder au catalogue, pas celle ayant besoin du pixel.
  4. Informez l’utilisateur ou l’utilisatrice du comportement de votre application en fonction des éléments auxquels elle a accès.

Pour les installations existantes

  1. Mettez à jour le token d’accès, son type et les éléments enregistrés auxquels votre application a accès.
  2. Actualisez l’ensemble de fonctionnalités implémenté par votre application pour cette entreprise en fonction des éléments auxquels elle a désormais accès.
  3. Informez l’utilisateur ou l’utilisatrice du comportement de votre application en fonction des éléments auxquels elle a accès.

Analyser le webhook lors de la désinstallation

Procédez comme suit lors de la désinstallation :

  1. Désactivez les fonctionnalités disponibles grâce à votre application.
  2. Informez l’entreprise des changements apportés à sa configuration.

Quels sont les éléments inclus avec la charge utile du webhook ?

Champs de réponse

ChampDescription
ad_account_id

type : chaîne

ID du compte publicitaire sélectionné par l’utilisateur ou l’utilisatrice dans FBE. Vous pouvez utiliser ce compte publicitaire pour gérer les publicités si votre application dispose d’autorisations ads_management. Consultez les éléments associés dans la liste installed_features.

business_manager_id

type : chaîne

ID Business Manager utilisé pour FBE. Consultez les éléments associés dans la liste installed_features.

catalog_id

type : chaîne

ID de catalogue sélectionné par un utilisateur ou une utilisatrice avec FBE. Cet ID peut servir à gérer leur catalogue produits. Consultez les éléments associés dans la liste installed_features.

fbe_event

type : chaîne

Évènement FBE qui indique si la notification d’évènement concerne une installation ou une désinstallation. Consultez les éléments associés dans la liste installed_features.

flow

type : chaîne

Flux auquel l’utilisateur ou l’utilisatrice est intégré·e (COMMERCE ou CREATIVE, par exemple). Consultez les éléments associés dans la liste installed_features.

commerce_merchant_settings_id

type : chaîne

ID des paramètres du commerçant ou de la commerçante utilisé pour permettre aux partenaires de lire les informations relatives aux paramètres du commerçant FBE sélectionnés. Consultez les éléments associés dans la liste installed_features.

onsite_eligible

type : booléen

Éligibilité au commerce sur site. Indique si les éléments sélectionnés sont éligibles au commerce sur site. Le commerçant ou la commerçante doit tout de même disposer d’une intention sur site et sélectionner les retours/expéditions/paiements sur le site du partenaire. Consultez les éléments associés dans la liste installed_features.

profiles

type : tableau

Liste des profils (ID de Page Facebook et/ou ID de profil professionnel Instagram). Utilisez ces ID pour créer des demandes de l’API Graph distinctes pour vos autres intégrations Facebook éventuelles. Consultez les éléments associés dans la liste installed_features.

pages

type : tableau

Liste des ID de Page Facebook. Utilisez ces ID pour créer des demandes de l’API Graph distinctes pour vos autres intégrations de Page Facebook éventuelles. Consultez les éléments associés dans la liste installed_features.

instagram_profiles

type : tableau

Liste des ID de profil professionnel Instagram. Utilisez ces ID pour créer des demandes de l’API Graph distinctes pour vos autres intégrations Facebook/Instagram éventuelles. Si ce champ n’est pas inclus, cela signifie que le périmètre concerne Instagram uniquement. Par exemple, instagram_basic ne figure pas dans le token d’accès et/ou l’entreprise n’a connecté aucun profil professionnel Instagram avec FBE. Consultez les éléments associés dans la liste installed_features.

pixel_id

type : chaîne

ID du pixel unique pour cette entreprise que nous vous recommandons de stocker et d’utiliser pour déclencher des évènements de pixel. Consultez les éléments associés dans la liste installed_features.

token_type

type : chaîne

Type de token. Indique si la valeur access_token reçue est un token d’accès utilisateur·ice par défaut ou un token d’accès utilisateur système.

installed_features

type : tableau

Liste des fonctionnalités que cette entreprise a intégrées ou installées au moyen des flux d’intégration. Consultez la liste des fonctionnalités.

feature_instance_id

type : tableau

ID représentant de manière unique chaque fonctionnalité installée. Peut servir à l’avenir à modifier ou désinstaller une instance en particulier. Est identique à l’ID feature_instance_id référencé dans l’API Feature Configuration et le webhook.

feature_type

type : chaîne

Type de fonctionnalité installée. Le tableau présentant la liste des fonctionnalités propose l’ensemble des fonctionnalités disponibles. Vous ne devez suivre que les fonctionnalités que vous avez activées.

connected_assets

type : tableau

Liste des éléments spécifiques et pertinents à chaque fonctionnalité. Les descriptions de ces éléments correspondent à celles mentionnées en haut de ce tableau.

additional_info

type : tableau

Informations supplémentaires au sujet de la fonctionnalité associée.


Lorsque vous recevez un évènement webhook pour une nouvelle installation, vous devez : 1) assurer une mise en correspondance de business_id vers son pixel_id puisque l’ID du pixel est propre à l’entreprise et que vous devez l’utiliser pour déclencher des évènements de pixel standards ; 2) mettre à jour l’inventaire pour cette entreprise à l’aide de l’une des API Push du catalogue, si elles sont activées.


Exemple : charge utile avec champ onsite_commerce_eligible booléen

{
  "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 d’installation de FBE

Pour toutes les entreprises ayant installé FBE, vous pouvez envoyer une requête d’informations d’installation de base (pixel_id et une liste de profils avec un IG Business ID and/or Page ID) en utilisant le point de terminaison suivant :

Exemple

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

Réponse

{
  "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 réponse contient les champs suivants, qui sont désormais la seule source fiable dans les éléments associés de la liste « installed_features » :

ChampDescription

token_type

type : chaîne

Type de token qui indique si la valeur access_token reçue est un token d’accès utilisateur·ice par défaut ou un token d’accès utilisateur système.

installed_features

type : tableau

Liste des fonctionnalités que cette entreprise a intégrées ou installées au moyen des flux d’intégration.

feature_instance_id

type : chaîne

ID unique représentant chaque fonctionnalité installée. Peut servir à l’avenir pour modifier ou désinstaller une instance particulière. Est identique à l’ID feature_instance_id référencé dans l’API Feature Configuration et le webhook.

feature_name

type : chaîne

Nom de fonctionnalité unique.

feature_type

type : chaîne

Type de fonctionnalité installée. Vous ne devez suivre que les fonctionnalités que vous avez activées.

connected_assets

type : tableau

Liste des éléments propres à chaque fonctionnalité.

additional_info

type : chaîne

Informations supplémentaires au sujet de la fonctionnalité associée, notamment shop_status et shop_status_info, qui indiquent si une boutique sera concernée par les modifications prévues. Valeurs disponibles pour shop_status : « inactive_other », « inactive_offsite », « active » ou « no_longer_available ».

« Active » indique que la boutique est visible. « Inactive_offsite » signifie que la boutique n’est pas visible, car elle n’utilise pas le paiement sur site. « Inactive_other » indique que la boutique n’est pas visible pour une raison autre que le type de paiement. « No_longer_available » signifie que la boutique se trouve en dehors des États-Unis ou d’un marché stratégique et n’est plus disponible.

Réponse de l’API Feature Configuration


Le modèle comprend l’ID d’instance de chaque fonctionnalité et les champs correspondant à toutes les fonctionnalités de ce type installées par l’entreprise (par exemple, plusieurs CTA de Page).

En ce qui concerne les fonctionnalités non personnalisables, seuls l’ID d’instance des fonctionnalités et un indicateur activé s’affichent. Une requête POST permet uniquement de mettre à jour les fonctionnalités personnalisables.

Ce modèle diffère de celui de l’API d’installation de FBE, car il fournit des informations supplémentaires sur les fonctionnalités au-delà des éléments associés, y compris le statut activé et les personnalisations de fonctionnalités spécifiques. Après avoir appelé l’API d’installation de FBE, utilisez cette API si vous avez besoin de davantage d’informations sur le statut activé ou les configurations de la fonctionnalité.

Consultation

Pour consulter le statut actuel de configuration des fonctionnalités d’une entreprise, exécutez la requête suivante :

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

Mise à jour

Pour mettre à jour toutes les fonctionnalités, exécutez la requête POST suivante :

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"

Réponse

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