Audiences personnalisées à partir d’un fichier clientèle

L’API Marketing permet de créer des audiences personnalisées cibles à partir d’informations clientèle. Celles-ci comprennent les adresses e-mail, les numéros de téléphone, les noms, les dates de naissance, le genre, les lieux, les ID utilisateur·ice de l’application, les ID utilisateur·ice spécifiques à la page, les IDFA (identifiants publicitaires d’Apple) ou encore les identifiants publicitaires d’Android.

Vous pouvez ajouter un nombre illimité d’enregistrements à une audience, avec toutefois un maximum de 10 000 entrées simultanées. Les modifications apportées à vos audiences personnalisées ne prennent pas effet immédiatement et sont généralement appliquées dans les 24 heures. Lorsque vous demandez la suppression de certaines entrées, le temps nécessaire au traitement de votre demande dépend du nombre d’entrées à supprimer et/ou d’audiences personnalisées contenues dans votre compte.

Afin d’améliorer la manière dont les annonceurs créent et gèrent leurs audiences, les audiences personnalisées créées à partir d’un fichier qui n’ont pas été utilisées dans des ensembles de publicités actifs pendant plus de deux ans seront automatiquement marquées pour suppression. Avant toute action de notre part, vous devrez nous communiquer vos instructions. Une fois les audiences placées dans la catégorie « Audiences arrivées à expiration » et marquées comme telles, vous devez soit les utiliser dans un ensemble de publicités actif pour nous indiquer que vous souhaitez les conserver, soit les laisser inutilisées, auquel cas, nous procéderons à leur suppression. Pour plus d’informations, consultez la documentation Vue d’ensemble des audiences personnalisées.

Création d’une audience personnalisée

Étape 1 : Créer une audience personnalisée vide

Indiquez subtype=CUSTOM et customer_file_source dans votre appel d’API.

curl -X POST \
  -F 'name="My new Custom Audience"' \
  -F 'subtype="CUSTOM"' \
  -F 'description="People who purchased on my website"' \
  -F 'customer_file_source="USER_PROVIDED_ONLY"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My new Custom Audience',
  'subtype' : 'CUSTOM',
  'description' : 'People who purchased on my website',
  'customer_file_source' : 'USER_PROVIDED_ONLY',
};
const customaudiences = (new AdAccount(id)).createCustomAudience(
  fields,
  params
);
logApiCallResult('customaudiences api call complete.', customaudiences);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My new Custom Audience',
  'subtype' => 'CUSTOM',
  'description' => 'People who purchased on my website',
  'customer_file_source' => 'USER_PROVIDED_ONLY',
);
echo json_encode((new AdAccount($id))->createCustomAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My new Custom Audience',
  'subtype': 'CUSTOM',
  'description': 'People who purchased on my website',
  'customer_file_source': 'USER_PROVIDED_ONLY',
}
print AdAccount(id).create_custom_audience(
  fields=fields,
  params=params,
)

import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCustomAudience()
      .setName(\"My new Custom Audience\")
      .setSubtype(CustomAudience.EnumSubtype.VALUE_CUSTOM)
      .setDescription(\"People who purchased on my website\")
      .setCustomerFileSource(CustomAudience.EnumCustomerFileSource.VALUE_USER_PROVIDED_ONLY)
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
customaudiences = ad_account.customaudiences.create({
    name: 'My new Custom Audience',
    subtype: 'CUSTOM',
    description: 'People who purchased on my website',
    customer_file_source: 'USER_PROVIDED_ONLY',
})

Paramètres

Étape 2 : Spécifier une liste d’utilisateurs ou d’utilisatrices

Utilisez un appel d’API POST au point de terminaison /{audience_id}/users pour spécifier la liste d’utilisateur·ices à ajouter dans votre audience personnalisée.

Paramètres

{
  "session_id":9778993, 
  "batch_seq":10, 
  "last_batch_flag":true, 
  "estimated_num_total":99996 
} 

{ 
  "schema":"EMAIL_SHA256", 
  "data":
    [
      ["<HASHED_DATA>"], 
      ["<HASHED_DATA>"], 
      ["<HASHED_DATA>"] 
    ]
}

Options de traitement des données pour les utilisateur·ices des États-Unis

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           []
           ]
       ]
   }
}

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           ["LDU"]
           ]
       ]
   }
}

{
    "customer_consent": true,
    "payload": {
        "schema": [
            "EMAIL",
            "DATA_PROCESSING_OPTIONS",
            "DATA_PROCESSING_OPTIONS_COUNTRY",
            "DATA_PROCESSING_OPTIONS_STATE"
        ],
        "data": [
            [
                "<HASHED_DATA>",
                ["LDU"],
                1,
                1000
            ]
        ]
    }
}

Champs session

Réponse

Une réponse positive inclut un objet JSON accompagné des champs suivants :

Découvrez comment partager votre audience personnalisée avec des objets d’entreprise.

Suppression de membres d’une audience

Utilisez un appel d’API DELETE au point de terminaison /{audience_id}/users pour spécifier la liste d’utilisateur·ices à supprimer de votre audience personnalisée.

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EMAIL_SHA256", 
    "data": [ 
      "<HASHED_DATA>", 
      "<HASHED_DATA>", 
      "<HASHED_DATA>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Vous pouvez également ajouter le paramètre method et le définir sur DELETE dans la demande POST utilisée pour ajouter des membres à l’audience.

Vous pouvez supprimer des personnes d’une liste à l’aide de EXTERN_ID (si disponible).

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EXTERN_ID", 
    "data": [ 
      "<ID>", 
      "<ID>", 
      "<ID>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Vous pouvez supprimer une liste de personnes de toutes les audiences personnalisées de votre compte publicitaire à l’aide de ce point de terminaison.

Ces informations peuvent ne pas être traitées pour différentes raisons, par exemple, si le compte publicitaire n’est pas détenu par un portefeuille business, si vous n’avez pas encore accepté les conditions applicables aux audiences personnalisées ou si les informations ne correspondent pas à un utilisateur ou une utilisatrice.

Pour supprimer un compte de l’Espace Comptes, renseignez tous les champs, comme pour la mise à jour d’un·e utilisateur·ice, et envoyez un appel HTTP DELETE à :

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/usersofanyaudience

Correspondance à clés multiples

Pour augmenter le taux de correspondance de vos entrées, fournissez plusieurs clés dans un tableau de clés individuelles ; par exemple [EXTERN_ID, LN, FN, EMAIL]. Si vous n’avez pas besoin de hacher EXTERN_ID, vous devez néanmoins hacher toutes les informations d’identification personnelle, comme les adresses e-mail et les noms. Pour plus de détails, consultez la section Hachage et normalisation des données.

Vous pouvez indiquer une partie ou l’ensemble des clés multiples pour un enregistrement. Pour plus de détails, consultez la section Correspondance d’ID externes à clés multiples.

Ajout d’utilisateur·ices avec des correspondances à clés multiples

curl \
  -F 'payload={ 
    "schema": [ 
      "FN", 
      "LN", 
      "EMAIL" 
    ], 
    "data": [ 
      [ 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ] 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Utilisation de PAGEUID

Si vous utilisez la clé PAGEUID, vous devez également inclure une liste d’ID de Page. Vous ne pouvez nous envoyer qu’un seul PAGEUID, qui doit se présenter sous la forme d’un tableau comportant un élément.

curl -X POST \
  -F 'payload={
       "schema": [
         "PAGEUID"
       ],
       "is_raw": "true",
       "page_ids": [
            "<PAGE_IDs>"
            ],
       "data": [
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ],
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ],
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ]
       ]
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Hachage et normalisation pour clés multiples

Vous devez hacher vos données au format SHA256 ; les autres mécanismes de hachage ne sont pas pris en charge. Cette opération est obligatoire pour toutes les données, à l’exception des identifiants externes, des ID utilisateur·ice de l’application, des ID utilisateur·ice au niveau de la page (Page Scoped User ID) et des ID d’annonceur mobile.

Avant de hacher vos données, normalisez-les afin que nous puissions les traiter. La saisie de caractères spéciaux et non latins n’est possible que pour le prénom (FN) et le nom (LN). Pour optimiser les résultats de la correspondance, veuillez indiquer la traduction en caractères latins, sans caractère spécial.

Hachage

Indiquez des valeurs au format SHA256 pour les clés normalisées et les représentations HEX de ces valeurs, en utilisant des minuscules pour les lettres de A à F. La fonction de hachage de PHP convertit les adresses e-mail et les numéros de téléphone normalisés.

Identifiants externes

Vous pouvez faire correspondre les membres d’une audience à vos propres identifiants, connus sous le nom d’identifiants externes (EXTERN_ID). Il peut s’agir de tout ID unique émanant de l’annonceur, tel que des ID de programme de fidélité, des ID d’utilisateur·ice et des ID de cookie externe.

Pour une meilleure correspondance, vous devez également utiliser le même format que celui que vous utilisez pour envoyer les ID. Par exemple, si vous choisissez d’utiliser le format SHA-256, assurez-vous d’utiliser la même valeur hachée.

Ces identifiants peuvent ensuite être utilisés comme clés individuelles pour supprimer des personnes des audiences personnalisées ou créer d’autres audiences de ce type. Cela vous évite de devoir réimporter d’autres clés de correspondance. Si vous identifiez une personne à l’aide d’informations personnelles hachées et d’un EXTERN_ID, nous attribuons à l’élément EXTERN_ID une priorité inférieure pour la mise en correspondance avec d’autres personnes sur Facebook.

Vous pouvez réutiliser la mise en correspondance de EXTERN_ID pour créer les audiences personnalisées au sein d’un compte publicitaire.

Si votre compte publicitaire comporte une audience de champs EXTERN_ID, créez une audience composée uniquement de ces identifiants.

curl \
  -F 'payload={"schema":"EXTERN_ID","data":["<ID>","<ID>"]}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Vous pouvez également ajouter des personnes identifiées avec EXTERN_ID et avec une correspondance à clés multiples.

curl \
  -F 'payload={ 
    "schema": [ 
      "EXTERN_ID", 
      "FN", 
      "EMAIL", 
      "LN" 
    ], 
    "data": [ 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ] 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

API Replace Users

Le point de terminaison /<CUSTOM_AUDIENCE_ID>/usersreplace permet de réaliser deux actions avec un seul appel d’API :

• Supprimer définitivement les utilisateur·ices existant·es d’une audience spécifique
• Les remplacer par un nouvel ensemble d’utilisateur·ices

Le point de terminaison /<CUSTOM_AUDIENCE_ID>/usersreplace permet de supprimer automatiquement tous les utilisateur·ices existant·es au lieu d’importer une liste des utilisateur·ices à supprimer. Ce point de terminaison ne réinitialise pas la phase d’apprentissage de votre ensemble de publicités quand une audience fait partie d’ensembles de publicités actifs, comme le font les appels d’API POST ou DELETE au point de terminaison /<CUSTOM_AUDIENCE_ID>/users.

L’API Replace Users fonctionne uniquement avec les audiences qui satisfont aux exigences suivantes :

• Le nombre d’utilisateur·ices avant le processus de remplacement doit être inférieur à 100 millions. Si votre audience est supérieure à 100 millions, nous vous suggérons d’utiliser le point de terminaison /<CUSTOM_AUDIENCE_ID>/users pour ajouter et supprimer des utilisateur·ices.
• Le sous-type doit être défini sur CUSTOM.
• Vous ne pouvez pas remplacer une audience personnalisée à partir d’un fichier clientèle qui est basée sur la valeur par une audience non basée sur la valeur et inversement.

Démarrer

Avant de lancer le processus de remplacement, nous recommandons les actions suivantes :

• Vérifiez que le statut operation_status de votre audience est bien Normal.

• Vous ne pouvez non plus ajouter ou supprimer des utilisateur·ices via /<CUSTOM_AUDIENCE_ID>/users lorsqu’un remplacement est en cours via /<CUSTOM_AUDIENCE_ID>/usersreplace. Si vous essayez de lancer une autre opération de remplacement avant que le remplacement en cours soit terminé, vous recevez un message vous informant qu’un remplacement est déjà en cours.

• La durée maximale d’une session de remplacement est de 90 minutes. L’API refuse tout lot d’une session reçu 90 minutes après le début de la session. Si vous devez envoyer des lots au-delà de ces 90 minutes, attendez la fin de l’opération de remplacement pour la session en cours, puis utilisez le point de terminaison /<CUSTOM_AUDIENCE>/users pour ajouter vos autres lots.

• Lorsque votre audience est prête, spécifiez la liste des utilisateur·ices à remplacer dans votre audience personnalisée en effectuant un appel POST à /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Une fois le processus de remplacement démarré, l’operation_status de votre audience passe à replace_in_progress.
  • Si le remplacement est incomplet, l’operation_status de votre audience passe à replace_error.

Paramètres d’appel

Vous pouvez inclure les paramètres suivants dans votre appel POST à /<CUSTOM_AUDIENCE_ID>/usersreplace :

{
  'session_id':9778993, 
  'batch_seq':10, 
  'last_batch_flag':true, 
  'estimated_num_total':99996 
}

{ 
  "schema":"EMAIL", 
  "data":["<HASHED_EMAIL>", "<HASHED_EMAIL>", "<HASHED_EMAIL>" ]
}

Champs Session

Champs Charge utile

Une fois votre requête POST envoyée, vous recevez une réponse avec les champs suivants :

Erreurs courantes de l’API Replace

Toutes les erreurs renvoyées par le point de terminaison Replace affichent le code d’erreur 2650. Voici les sous-codes d’erreur les plus couramment renvoyés, ainsi que des conseils pour résoudre ces problèmes.

Ressources

Voici les autres types d’audience que vous pouvez créer, cibler ou partager :

• Audiences personnalisées à partir de votre site web : créez une audience sur la base des personnes qui ont visité une page spécifique ou effectué des actions sur votre site Web. Créez une audience sur la base des données issues d’un pixel Meta sur votre site.

• Audiences personnalisées à partir de votre application mobile : créez une audience sur la base des personnes qui utilisent votre application mobile. Créez une audience sur la base des données provenant d’évènements d’application.

• Audiences similaires : identifiez les personnes que vous connaissez déjà et diffusez vos publicités auprès des personnes présentant des caractéristiques similaires sur Facebook.

• Audiences personnalisées hors ligne : créez une audience sur la base des personnes qui ont visité votre boutique, qui ont contacté votre service clientèle ou qui ont effectué des actions par le biais d’autres canaux hors ligne.

• Audiences d’interactions Canvas : créez une audience composée de toute personne ayant interagi avec votre Canvas.

Voir aussi

• Audience personnalisée
• Utilisateur·ices d’audience personnalisée
• Session d’audience personnalisée
• Conditions d’utilisation d’une audience personnalisée