API Control Plane du gateway API Conversions pour plusieurs comptes

Intégration de partenaires

Présentation

L’API Control Plane du gateway API Conversions pour plusieurs comptes regroupe plusieurs API GraphQL exposées à partir de l’instance du Gateway. Cette API permet aux équipes de développement de gérer par programmation les comptes, les sources de données et d’autres configurations d’une instance du gateway. Les partenaires peuvent intégrer l’API dans l’interface qu’ils présentent à leurs annonceurs, afin de leur offrir un processus fluide d’intégration et de gestion.

Cas d’utilisation envisagés :

Les annonceurs intègrent le gateway grâce à l’interface de leur partenaire et réalisent les actions de suivi dans les paramètres admin du gateway. Ce scénario implique une intégration partielle de l’API Control Plane.
Les annonceurs réalisent toutes les actions dans l’interface de leur partenaire, y compris l’intégration du gateway et les actions de suivi. Ce scénario peut convenir aux partenaires qui ne souhaitent pas exposer l’interface du gateway, mais proposer tout de même ce service à leurs annonceurs. Il implique une intégration complète de l’API Control Plane.

Consultez la section ci-dessous pour connaître les étapes de l’intégration.

Les expressions API Control Plane du gateway API Conversions pour plusieurs comptes ou tout simplement gateway sont interchangeables et désignent le même concept dans ce document.

Guide d’intégration

Deux méthodes d’intégration sont disponibles, en fonction du cas d’utilisation (comme illustré dans le schéma ci-dessous) :

Intégration partielle de l’API Control Plane. Les annonceurs n’ont pas besoin de s’authentifier.
Intégration complète de l’API Control Plane. Les annonceurs doivent s’authentifier, soit via l’Extension Meta Business (MBE), soit en générant manuellement des tokens.

Conditions requises

Dans les deux cas, le partenaire doit préalablement réaliser les étapes suivantes :

Étape 1 : intégrer l’instance du gateway en tant qu’hôte

Étape 2 : générer le nom du compte et la clé secrète de l’API

Accédez à :

https://<Conversions API Gateway Endpoint>/hub/

Accédez à l’onglet Host settings (Paramètres de l’hôte), sélectionnez la page Manage API accounts (Gérer les comptes de l’API), puis cliquez sur le bouton Add API account (Ajouter un compte d’API).

Saisissez à nouveau votre mot de passe. Cliquez sur Continuer.

Renseignez le nom du compte de l’API. Cliquez sur Continuer.

Le nom du compte peut contenir uniquement des lettres et des chiffres, sans espaces. La limite est de 20 caractères.

Copiez et enregistrez la clé secrète générée. Elle ne sera plus jamais affichée.

Pour supprimer un compte de l’API, cliquez sur Delete API account (Supprimer le compte de l’API). Cette action est irréversible et peut entraîner des interruptions des applications ou services des annonceurs utilisant l’API.

Intégration partielle

Voici un exemple d’intégration partielle :

L’annonceur veut utiliser le service de gateway avec l’interface du partenaire.
Celui-ci génère un lien d’invitation que l’annonceur utilise ensuite pour configurer un mot de passe et finaliser la création de son compte de gateway.
L’annonceur exploite les fonctionnalités de l’interface du gateway pour réaliser des actions, notamment la gestion des sources de données, des utilisateur·ices de compte, des domaines et du routage.
Le partenaire récupère les informations concernant l’utilisation du compte par l’annonceur et lui adresse la facture correspondante.

Parcours d’utilisation classique :

Pour faciliter ce parcours, le partenaire peut intégrer un sous-ensemble de l’API Control Plane, notamment pour réaliser les actions suivantes :

Obtenir un token d’accès de l’API
Créer un compte pour les annonceurs
Obtenir les informations sur l’utilisation du compte (par exemple, pour la facturation)

Intégration complète

Voici un exemple d’intégration complète :

L’annonceur veut utiliser le service de gateway avec l’interface du partenaire.
Le partenaire intègre le compte de gateway de l’annonceur et reçoit par ce dernier l’autorisation de gérer ce compte, soit en utilisant l’extension Meta Business (MBE), soit avec un token généré manuellement.
L’annonceur peut gérer les sources de données, mais aussi les utilisateur·ices de compte, les domaines et le routage dans l’interface du partenaire.
Le partenaire récupère les informations concernant l’utilisation du compte par l’annonceur et lui adresse la facture correspondante.

Parcours d’utilisation classique :

Afin de réaliser ce type d’intégration, les partenaires doivent demander une autorisation et obtenir les tokens d’accès utilisateur·ice système via une authentification pour pouvoir envoyer des évènements au nom des annonceurs.

Authentification

Deux méthodes d’authentification sont disponibles aux partenaires pour les Pixel Meta dont ils ne contrôlent pas la gestion :

Option 1 : extension Meta Business (MBE)

Avant de commencer, vous devez réaliser les actions suivantes :

Respecter tous les critères d’implémentation de MBE
Contacter votre représentant Meta pour ajouter votre application à la liste d’éléments autorisés pour une autorisation privée : open_bridge_configuration_management

MBE fournit un point de terminaison pour récupérer les tokens d’accès d’utilisateur·ice système créés dans le Business Manager de l’annonceur. Les partenaires peuvent suivre le guide d’intégration de MBE jusqu’à l’étape 4. Assurez-vous de suivre les étapes ci-dessous :

Définissez la valeur du paramètre de canal dans l’objet de configuration sur CONVERSIONS_API_GATEWAY_ADVERTISER.
Vérifiez que vous êtes en mesure de recevoir la réponse du webhook à la fin de l’intégration.
Utilisez le token d’accès renvoyé par MBE et convertissez-le en un token d’accès utilisateur·ice système en effectuant un appel d’API supplémentaire.
Enregistrez une copie des identifiants external_business_id, pixel_id et business_id, ainsi que du token d’accès utilisateur·ice dans votre système.

Option 2 : token d’accès utilisateur·ice système de l’annonceur

Pour appliquer cette option, les partenaires doivent demander aux annonceurs de réaliser les actions suivantes :

Créer manuellement un token d’accès utilisateur·ice système via l’API Conversions dans les réglages du Gestionnaire d’évènements.
Partager avec eux les identifiants pixel_id et business_id, ainsi que le token d’accès utilisateur·ice système, et en enregistrer une copie.

Intégration

Les partenaires peuvent intégrer l’ensemble des API Control Plane. Pour en savoir plus, consultez la référence sur les API.

Parité API/interface

Nous appliquons la parité entre l’API et l’interface en exposant les mêmes points de terminaison de l’API utilisés dans l’interface du gateway. Toutefois, les points de terminaison non mentionnés dans la référence sur les API peuvent être modifiés à l’avenir. Afin de limiter au maximum les futures déconvenues, ces points de terminaison non mentionnés renvoient le code d’erreur 418. Vous pouvez toujours l’API, mais à vos propres risques.