Managed Partner Ads : références d’API

Les autres API Managed Partner Ads sont les suivantes :

• API de gestion des vendeurs ou vendeuses
• API de gestion des publicités de partenaires
• Guide d’utilisation de l’API asynchrone

API Lookup Seller Business

Utilisez cette API pour rechercher l’ID d’entreprise d’un vendeur ou d’une vendeuse en particulier (vendor_id).

Type de token d’accès

Pour appeler cette API, utilisez le token d’accès créé par un utilisateur ou une utilisatrice système admin qui appartient au Business Manager parent (le Business Manager du marketplace).

Exemple de requête GET

curl -X GET \
  -F "child_business_external_id=<VENDOR_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/owned_businesses?access_token=<ACCESS_TOKEN>"

Exemple de réponse

{
    "child_business_id": 3213232
}

API Access Seller Business Metadata

Utilisez cette API pour récupérer les métadonnées de l’entreprise enfant du vendeur ou de la vendeuse Managed Partner Ads. Les métadonnées de la réponse de l’API sont les suivantes :

• Éléments Managed Partner Ads : page, compte publicitaire, moyen de paiement
• Informations sur le modèle personnalisé du vendeur ou de la vendeuse
• Informations sur l’entreprise du vendeur ou de la vendeuse : nom

Type de token d’accès

Pour appeler cette API, utilisez le token d’accès créé par un utilisateur ou une utilisatrice système admin qui appartient au Business Manager parent (le Business Manager du marketplace).

Type d’ID d’entreprise

Utilisez l’ID du Business Manager enfant pour l’appel d’API.

Exemple de requête GET

curl -X GET \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/?fields=collaborative_ads_managed_partner_business_info&access_token=<ACCESS_TOKEN>"

Exemple de réponse

{
  "collaborative_ads_managed_partner_business_info": {
    "seller_business_status": "ready",
    "seller_business_info": {
      "seller_external_website_url": "https://www.website.com",
      "partner_facebook_page": {
        "id":"9999999"
      }
    },
    "ad_account": {
      "id": "act_11111111",
      "currency": "USD"
    },
    "page": {
      "id": "3333333"
    },
    "catalog_segment": {
      "id": "2222222"
    },
    "extended_credit": {
      "receiving_credit_allocation_config": {
        "partition_type": "FIXED",
        "id":"66666666"
      },
      "max_balance": {
        "amount":"5,000.00",
        "amount_in_hundredths":"500000",
        "currency":"USD",
        "offsetted_amount":"500000"
      },
      "id":"888888888"
    },
    "active_seller_campaign": {
      "status": "ACTIVE",
      "id": "1111111"
    },
    "template": [
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "4444444",
        "adgroup_template_ids": [
          "5555555"
        ],
        "targeting_type": "retargeting"      
      },
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "6666666",
        "adgroup_template_ids": [
          "7777777"
        ],
        "targeting_type": "prospecting"
      } 
    ]
  },
  "id": "<child_business_manager_id>"
}
    

Obtenir le token utilisateur·ice du système enfant

Pour un Business Manager enfant intégré, utilisez cet appel d’API pour partager l’application et obtenir son token d’accès. Ce token peut être utilisé pour tous les appels ultérieurs visant à créer ou à gérer des publicités.

Exemple de requête POST

curl \
  -F 'id=<CHILD_BUSINESS_MANAGER>' \
  -F 'app_id=<App_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<Parent BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  "https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token"

Exemple de réponse

{ 
  "access_token": "<CHILD_BM_ACCESS_TOKEN>"
}

API Update Seller Business Configuration

Utilisez cette API pour mettre à jour les informations de l’entreprise d’un vendeur ou d’une vendeuse. Vous pouvez mettre à jour les informations de l’entreprise d’un vendeur ou d’une vendeuse, comme l’URL d’un site Web externe ou l’adresse e-mail, et/ou ses éléments Managed Partner Ads, comme un compte publicitaire actif ou un modèle de campagne personnalisée pour la création de publicités. Pour plus d’informations, reportez-vous à Paramètres disponibles.

Pour créer et obtenir l’entreprise d’un vendeur ou d’une vendeuse, reportez-vous à API Seller Business Creation. Pour trouver l’ID de l’entreprise d’un·e vendeur·se existant·e, reportez-vous à API Lookup Seller Business.

Type de token d’accès

Pour appeler cette API, utilisez le token d’accès qui appartient à chaque Business Manager enfant (le Business Manager du vendeur ou de la vendeuse).

Paramètres disponibles

Exemple de requête POST

curl \
  -F "seller_external_website_url='http://shop.com'" \
  -F "ad_account=<SELLER_ACTIVE_AD_ACCOUNT_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Child_Business_id>/managed_partner_business_setup?access_token=<ACCESS_TOKEN>"

Exemple de réponse

{
    "id": 3213232, // id of child business
    "meta_data": {
        "seller_business_info": {
            "seller_email_address": "goodseller@fb.com"
            "seller_external_website_url": "www.website.com"
        },
        "ad_account": {
            "id": "434343",
            "spend_limit": "500",
        },
        "page": {
            "id": "123412341",
        },
        "template": [
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "4444444",
            "adgroup_template_ids": [
              "5555555"
            ],
            "targeting_type": "retargeting"      
          },
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "6666666",
            "adgroup_template_ids": [
              "7777777"
            ],
            "targeting_type": "prospecting"
          } 
        ]     
    }
}

Codes d’erreur

Utiliser les modèles

Un modèle est un élément configuré et utilisé par le marketplace dans le service Managed Partner Ads. Les modèles contiennent des détails et des paramètres, ou « composants », qui pilotent les campagnes de vente diffusées par le marketplace pour le compte du vendeur ou de la vendeuse.

Les composants du modèle comprennent les ensembles de publicités et les publicités, qui comprennent des informations telles que le ciblage, le contenu publicitaire, les formats, etc. Quatre composants sont nécessaires pour chaque modèle de campagne :

• Composant ensemble de publicités pour la prospection
• Composant publicité
• Composant ensemble de publicités pour le reciblage
• Composant publicité

Types de modèles

Il existe deux types de modèles : les modèles par défaut et les modèles personnalisés.

Conditions requises pour les modèles personnalisés

Avant de créer un modèle personnalisé, le marketplace doit d’abord créer un Business Manager producteur. Ainsi, les campagnes utilisées pour créer des modèles sont conformes aux personnalisations des Publicités collaboratives et aux conditions requises pour les campagnes des vendeur·ses. En tant que producteur, le Business Manager peut être utilisé pour créer des publicités sources pour la création de modèles.

Les composants publicité et ensembles de publicités de reciblage et de prospection doivent être disponibles pour ajouter et/ou configurer un modèle de campagne personnalisé pour un·e vendeur·se.

Les campagnes utilisées pour la création de modèles doivent être associées à un compte publicitaire Publicités collaboratives, et être paramétrées comme suit :

• L’objectif de la campagne doit être la vente de catalogues.
• Dans le Gestionnaire de publicités, l’optimisation du budget doit être activée au niveau de la campagne, avec la stratégie d’enchère « coût le plus bas ».
• Le format publicitaire doit être un carrousel sans vidéos, images ou superpositions statiques.

Flux de modèle personnalisé

Étape 1 : créer un modèle de campagne personnalisé

1. Accédez à l’onglet Éléments dans l’Espace de collaboration. Dans cet onglet, la section Inventaire des modèles affiche une collection de modèles et de composants de modèles qui peuvent être utilisés pour les campagnes des vendeur·ses.
2. Cliquez sur Créer un modèle pour ouvrir une carte pas à pas.
3. Recherchez une campagne source valide existante en indiquant l’ID de la publicité ou de l’ensemble de publicités.
4. Pour créer votre composant de modèle, sélectionnez une publicité et/ou un ensemble de publicités provenant de l’ID source. Vous devez créer les quatre composants (deux publicités et deux ensembles de publicités) pour un modèle personnalisé.
5. Enregistrez le modèle en lui donnant un nom et une description.

Les détails spécifiques du vendeur ou de la vendeuse, tels que le segment de catalogue, l’ensemble de produits, la Page Facebook et l’URL de destination, sont supprimés de la campagne source lors de la création du modèle. La campagne finale créée à l’aide du modèle contient les informations spécifiques du vendeur ou de la vendeuse pour ces champs, ainsi qu’un budget de campagne à vie et la stratégie d’enchère « coût le plus bas ».

Étape 2 : appliquer le modèle personnalisé à un·e vendeur·se

Les modèles personnalisés peuvent être utilisés comme suit :

• Utilisez un modèle personnalisé au moment de l’intégration du vendeur ou de la vendeuse pour affecter des modèles spécifiques à ses campagnes.
• Modifiez le modèle pour un·e vendeur·se afin de lancer une campagne de fêtes de fin d’année ou une autre campagne spéciale.

Si vous souhaitez modifier le modèle de campagne pour les vendeur·ses, assurez-vous de disposer des composants de modèle que vous souhaitez utiliser pour remplacer ceux du modèle de campagne existant (vous pouvez en remplacer un seul ou tous). Si vous créez un nouveau modèle pour les vendeur·ses qui n’ont pas de modèle personnalisé, vous devez avoir les quatre composants (deux publicités et deux ensembles de publicités) prêts à l’emploi.

Un modèle peut être appliqué aux vendeur·ses de l’une des manières suivantes :

Flux de l’UI pour l’application du modèle à un·e vendeur·se unique

1. Accédez à l’onglet Vendeurs de l’Espace de collaboration et sélectionnez le vendeur ou la vendeuse à qui appliquer le modèle personnalisé.
2. Ouvrez l’onglet Éléments partagés pour ce vendeur ou cette vendeuse. Au début, les vendeur·ses n’ont pas de modèle de campagne personnalisé configuré.
3. Cliquez sur Ajouter personnalisé. Une fenêtre modale apparaît ; vous pouvez y sélectionner les composants du modèle créés lors de l’étape de création du modèle à appliquer au vendeur ou à la vendeuse sélectionné·e.
4. Vous pouvez spécifier les limites de dépense maximales pour l’ensemble de publicités de prospection et l’ensemble de publicités de reciblage, exprimées en pourcentage de votre budget total de campagne. Le budget sera continuellement réparti en temps réel sur les deux ensembles de publicités en fonction des performances. Cela signifie que le pourcentage du budget consacré à chaque ensemble de publicités à la fin de la campagne peut être inférieur au montant maximal que vous avez défini. Par défaut, la limite de dépense maximale est répartie à parts égales entre les deux ensembles de publicités, mais vous pouvez la modifier.
5. Cliquez sur Enregistrer pour appliquer au vendeur ou à la vendeuse les composants du modèle sélectionnés.

Flux de l’UI pour l’application groupée du modèle

Cette fonctionnalité vise à assurer l’évolutivité en permettant aux marketplaces d’appliquer des composants de modèles à plusieurs vendeur·ses en même temps.

1. Accédez à l’onglet Vendeurs de l’Espace de collaboration et sélectionnez l’ensemble de vendeur·ses auquel appliquer le modèle en cochant les cases correspondantes dans la colonne appropriée.
2. Cliquez sur Appliquer les modèles pour poursuivre le processus d’application des modèles.
3. Une fenêtre modale apparaît selon la sélection de vendeur·ses.

• Si les vendeur·ses sélectionné·es n’ont pas de modèle personnalisé existant, sélectionnez les quatre composants du modèle et indiquez le pourcentage limite de dépense pour la prospection et le reciblage. Par défaut, la limite de dépense est répartie à parts égales entre les deux ensembles de publicités.
• Si les vendeur·ses sélectionné·es ont déjà eu des modèles personnalisés appliqués, sélectionnez tous les composants du modèle, un seul ou certains d’entre eux, à remplacer pour les vendeur·ses sélectionné·es. Le pourcentage de limite de dépense pour les ensembles de publicités peut être remplacé pour les vendeur·ses en activant le bouton approprié.
• Si la sélection des vendeur·ses est un mélange de vendeur·ses avec et sans modèles personnalisés, une fenêtre modale apparaît pour vous permettre de sélectionner soit « Vendeurs sans modèles personnalisés » soit « Vendeurs avec modèles personnalisés » pour l’étape suivante. En fonction de la sélection, une fenêtre modale apparaît parmi les deux options précédentes.

Finalisez la procédure en cliquant sur Enregistrer. Les composants du modèle sélectionnés seront appliqués aux vendeur·ses sélectionné·es.

API Update Seller Business Configuration

Utilisez l’API Update Seller Business Configuration pour appliquer un modèle personnalisé à un·e vendeur·se avec le paramètre d’entrée suivant : template.

"template":[
  {
    "budget_percentage":0.5,
    "campaign_template_id":"160235235998069",
    "adgroup_template_ids":[
      "447963739637509"
    ],
    "targeting_type":"retargeting"
  },
  {
    "budget_percentage":0.5,
    "campaign_template_id":"278452090413983",
    "adgroup_template_ids":[
      "458654975391261"
    ],
    "targeting_type":"prospecting"
  }
]

Étape 3 : créer votre campagne

Utilisez les instructions principales de création de campagne pour créer et diffuser des annonces de vendeur·ses avec les paramètres indiqués et le modèle personnalisé précédemment appliqué. Pour utiliser le modèle de campagne personnalisé appliqué à ce vendeur ou à cette vendeuse, définissez use_seller_template sur true.