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 :

• Webhook : obligatoire pour tous les partenaires de la plateforme qui souhaitent figurer dans l’App Store
• Point de terminaison d’API pour les installations de FBE : recommandé pour les entreprises auto-hébergées

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

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

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 » :

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

Étapes suivantes

• Configurer les fonctionnalités d’entreprise
• Déclencher des évènements suivis par le pixel
• Mettre à jour votre catalogue