Business Management APIs

Premiers pas

Découvrez comment implémenter la gestion des éléments de contenu publicitaire.

L’API de gestion des éléments de contenu publicitaire n’est disponible que pour certains partenaires. N’hésitez pas à contacter votre partenaire Meta pour plus d’informations.

Conditions requises

Pour utiliser cette API, vous avez besoin des éléments suivants :

Autorisations

Lorsque vos utilisateur·ices se connectent à votre application, vous devrez leur demander les autorisations suivantes :

  • business_creative_management : permet de gérer les dossiers créatifs professionnels et les contenus publicitaires professionnels. Obligatoire pour tous les points de terminaison de l’API Business Creative Asset Manager.
  • business_creative_insights : permet d’accéder aux statistiques sur les éléments de contenu publicitaire professionnel.
  • business_management : permet de gérer les utilisateur·ices professionnel·les et d’accepter les demandes d’accord de partenariat.

Limites

  • L’utilisateur·ice de l’application (annonceur) doit être admin de l’entreprise et disposer de l’ID Business Manager.

Étape 1 : Créer un dossier créatif professionnel

Créez un dossier créatif professionnel au nom de l’entreprise de l’annonceur en envoyant une requête POST au point de terminaison {business-id}/creative_folders. Dans ce cas précis, {business-id} est l’ID de l’entreprise de l’annonceur.

Cette action requiert l’autorisation business_creative_management.

Exemple de requête

curl -X POST \
  -F 'name={folder-name}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Exemple de réponse

{ “id”: “{business-creative-folder-id}” }

Vous pouvez également créer des sous-dossiers.

Étape 2 : Ajouter du contenu publicitaire à ce dossier

Ajoutez des éléments de contenu publicitaire existants à un dossier en envoyant une requête POST à {business-id}/images ou à {business-id}/videos. Pour effectuer cette action, vous devez disposer de l’autorisation business_creative_management.

Ajouter des images

Exemple : ajouter une image

curl -X POST \
  -F 'bytes={image-content-in-bytes-format}' \
  -F 'name={image-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph.facebook.com/{version}/{business-id}/images

Réponse

{
  "images":{
    "{image-name}":{
      "id":"{business-image-id}",
      "hash":"{hash}",
      "url":"{image-url}"
    }
  }
}

Importer des vidéos

Importez une vidéo en une seule fois si elle fait moins de quelques mégaoctets. Sinon, importez-la par segments. Effectuez votre appel d’API pour l’importation de la vidéo à graph-video.facebook.com au lieu de graph.facebook.com.

Exemple : envoyer une requête POST à {business-id}/video en indiquant le nom de votre vidéo, la source et l’ID du dossier créatif professionnel

curl -X POST \
  -F 'name={video-name}' \
  -F 'source='@{video-path}'' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

Réponse

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

Importer des vidéos par segments

Pour les vidéos plus volumineuses, envoyez une requête start, une ou plusieurs requêtes transfer et une requête finish.

Pour effectuer une requête start et créer une session d’importation de vidéo, envoyez une requête POST à /{business-id}/videos, définissez le champ upload_phase sur start et spécifiez la valeur file_size en octets.

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={access-token}' \
  -F 'upload_phase=start' \
  -F 'file_size={video_file_size_in_bytes}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Exemple de réponse

{
  "upload_session_id": "{session-id}",
  "business_video_id": "{business-video-id}",
  "video_id": "{video-id}",
  "start_offset": "0",
  "end_offset": "52428800"
}

Pour importer la plage [0, 52428800] de votre vidéo, découpez le fichier en segments en fonction des décalages de début et de fin, puis envoyez ces segments avec des requêtes transfer. Nous vous envoyons de nouveaux décalages pour chaque segment. Utilisez ces nouveaux décalages pour importer chacun des segments.

Exemple : envoyer votre premier segment

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'upload_session_id={session-id}' \
  -F 'start_offset=0' \
  -F 'video_file_chunk=@{binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

En cas de réussite, nous répondons par les décalages de votre segment suivant :

{
 "start_offset": "52428800",    //Start byte position of the next file chunk.
 "end_offset": "104857601"      //End byte position of the next file chunk.
}

Coupez et importez le deuxième segment avec la plage [52428800, 104857601] de votre fichier et envoyez-le :

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'start_offset=52428801' \
  -F 'upload_session_id={your-upload-sesson-id}' \
  -F 'video_file_chunk={binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Envoyez tous les segments supplémentaires jusqu’à ce que start_offset soit égal à end_offset :

{
  "start_offset": "152043520",
  "end_offset": "152043520"
}

Cela signifie que vous avez importé le fichier dans son intégralité. Vous devez maintenant publier cette vidéo et terminer la session d’importation.

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=finish' \
  -F 'upload_session_id={session-id}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Si vous obtenez des erreurs lors d’une importation, vous pouvez réessayer d’importer le segment concerné. En général, les erreurs sont dues à des problèmes de réponse. Recommencez votre importation pour le segment ayant échoué. Pour en savoir plus sur les erreurs, consultez :

Une fois que vous avez importé un contenu publicitaire dans un dossier, les annonceurs qui ont accès à ce dossier peuvent créer des publicités sur le Gestionnaire de publicités ou avec l’API Marketing.

Tous les contenus publicitaires importés apparaissent dans l’UI Gestionnaire de publicités > outil de sélection de contenus multimédias. Vous pouvez les utiliser dans les outils de création de publicités et de modification de publicités. En outre, les dossiers et les éléments de contenu publicitaire sont disponibles dans l’outil Médiathèque de Business Manager accessible via Business Manager > Médiathèque.

Étape 3 : Obtenir l’URL de lien profond d’un élément et créer une publicité ou une publication

Pour obtenir l’URL de lien profond d’un élément spécifique, interrogez le champ media_library_url de l’élément d’image ou de vidéo importé :

curl -X GET \  
  -F 'access_token={partner-access-token}' \
https://graph.facebook.com/v<API_VERSION>/<asset_id>?fields=media_library_url

Pour utiliser votre lien profond afin de créer une publicité ou une publication de Page, ajoutez &action=CREATE_AD ou &action=CREATE_POST à la fin du lien :

https://business.facebook.com/asset_library/business_creatives/?object_id=<OBJECT_ID>&action=CREATE_AD