Gruppi di pubblico personalizzato dai file dei clienti

L'API Marketing consente di creare gruppi di pubblico personalizzato di destinatari partendo dalle informazioni sui clienti. Fra queste vi sono indirizzo e-mail, numero di telefono, nome, data di nascita, genere, posizione, ID utente dell'app, ID utente della singola Pagina, ID pubblicitario di Apple (IDFA) o ID pubblicitario Android.

Puoi aggiungere un numero illimitato di record al tuo pubblico, entro un massimo di 10 000 per volta. Le modifiche al pubblico personalizzato non vengono applicate immediatamente; di solito sono necessarie fino a 24 ore. Il numero di record che richiedi di rimuovere e/o il numero di gruppi di pubblico personalizzato contenuti nel tuo account aumenteranno il tempo necessario per elaborare la richiesta.

Per migliorare il modo in cui gli inserzionisti creano e gestiscono i propri gruppi di pubblico, i gruppi di pubblico personalizzato dal file clienti che non sono stati utilizzati in alcun gruppo di inserzioni attivo da oltre due anni verranno contrassegnati per l'eliminazione su base continuativa. Dovrai fornirci delle istruzioni prima che intraprendiamo qualsiasi azione. Una volta che i gruppi di pubblico vengono spostati nella fase "Pubblico in scadenza" e contrassegnati, dovrai fornirci delle istruzioni utilizzando il pubblico contrassegnato in un gruppo di inserzioni attivo (che interpreteremo come un'indicazione di mantenere il pubblico) oppure decidendo di non utilizzare il pubblico contrassegnato in un gruppo di inserzioni attivo (che interpreteremo come un'indicazione di eliminare il pubblico). Per ulteriori informazioni, consulta la documentazione relativa alla Panoramica dei gruppi di pubblico personalizzato.

Creazione di un pubblico personalizzato

Passaggio 1: creazione di un pubblico personalizzato vuoto

Specifica subtype=CUSTOM e customer_file_source nella chiamata 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/v19.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',
})

Parametri

Passaggio 2: definizione di una lista di utenti

Per specificare la lista di utenti che desideri aggiungere al tuo pubblico personalizzato, utilizza una chiamata API POST all'endpoint /{audience_id}/users.

Parametri

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

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

Opzioni di elaborazione dei dati per gli utenti negli Stati Uniti

{
   "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
            ]
        ]
    }
}

Campi session

Risposta

Una risposta corretta comprende un oggetto JSON con i campi seguenti:

Maggiori informazioni sulla condivisione del tuo pubblico personalizzato con gli oggetti aziendali.

Rimozione dei membri del pubblico

Usa una chiamata API DELETE all'endpoint /{audience_id}/users per specificare l'elenco di utenti che desideri rimuovere dal tuo pubblico personalizzato.

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

In alternativa, puoi aggiungere il parametro method e impostarlo su DELETE nella richiesta POST usata per aggiungere membri del pubblico.

Puoi rimuovere le persone da una lista con EXTERN_ID, se disponibile.

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

Puoi rimuovere una lista di persone da tutti i gruppi di pubblico personalizzato nel tuo account pubblicitario utilizzando questo endpoint.

Queste informazioni potrebbero non essere elaborate per diversi motivi. Ad esempio, se l'account pubblicitario non è di proprietà di un account business, non hai ancora accettato le Condizioni per il pubblico personalizzato oppure le informazioni non corrispondono a un utente.

Per rimuovere un account dal Centro gestione account, includi gli stessi campi di aggiornamento utente ed esegui una chiamata HTTP DELETE a:

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

Corrispondenza a più voci

Per aumentare il tasso di corrispondenza dei tuoi record, fornisci voci multiple in un array di voci individuali, ad esempio: [EXTERN_ID, LN, FN, EMAIL]. Sebbene tu non debba applicare l'algoritmo di hashing a EXTERN_ID, devi applicarlo a tutte le informazioni di identificazione personale, come e-mail e nomi. Per i dettagli, vedi Uso di algoritmi di hashing e normalizzazione dei dati.

Puoi fornire alcune voci o tutte le voci multiple in un record. Per i dettagli, vedi corrispondenza ID esterni a più voci.

Aggiunta di utenti con corrispondenza a più voci

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

Uso di PAGEUID

Se usi la voce PAGEUID, devi includere anche una lista di ID Pagina. Puoi inviarci solo un PAGEUID, che deve essere un array con un elemento.

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

Applicazione dell'algoritmo di hashing e normalizzazione per le voci multiple

Devi applicare un algoritmo di hashing ai dati secondo la modalità SHA256; non sono supportati altri meccanismi di applicazione dell'algoritmo di hashing. È necessario per tutti i dati tranne identificativi esterni, ID utente dell'app, ID utente per singola Pagina e ID degli inserzionisti mobili.

Prima di applicare l'algoritmo di hashing ai dati, normalizzali in modo che possiamo elaborarli. Solo nome (FN) e cognome (LN) supportano i caratteri speciali e l'alfabeto non romano. Per ottenere corrispondenze ottimali, fornisci la traduzione dell'alfabeto romano senza caratteri speciali.

Hashing

Fornisci valori SHA256 per le voci normalizzate e le rappresentazioni HEX di questo valore, usando le minuscole da A a F. La funzione hash in PHP converte e-mail e numeri di telefono normalizzati.

Identificativi esterni

Puoi combinare le persone con un pubblico utilizzando i tuoi identificativi, noti come identificativi esterni (EXTERN_ID). Può trattarsi di un qualsiasi ID unico dell'inserzionista, come ID del programma fedeltà, ID utente e ID cookie esterni.

Per una migliore corrispondenza, dovresti anche usare il formato esatto quando invii gli ID. Ad esempio, se scegli di applicare un algoritmo di hashing usando SHA256, assicurati di utilizzare lo stesso valore in formato hash.

Puoi usare questi ID come voci singole per eliminare le persone dal pubblico personalizzato o creare un nuovo pubblico personalizzato. In questo modo non dovrai ricaricare altre voci corrispondenti. Se tagghi qualcuno con informazioni personali con hash e EXTERN_ID, all'EXTERN_ID viene assegnata una precedenza minore quando viene eseguita la corrispondenza con gli utenti presenti su Facebook.

Puoi riutilizzare la mappatura EXTERN_ID per la creazione di pubblico personalizzato dai file dei clienti in un unico account pubblicitario.

Se hai un pubblico di campi EXTERN_ID nel tuo account pubblicitario, crea un nuovo pubblico usando solo questi identificativi.

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

Puoi anche aggiungere persone taggate con EXTERN_ID e con la corrispondenza di più voci.

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

L'endpoint /<CUSTOM_AUDIENCE_ID>/usersreplace permette di eseguire 2 azioni con una chiamata API:

• Rimuovere completamente gli utenti esistenti da un pubblico specifico
• Sostituire quegli utenti con un nuovo insieme di utenti.

Utilizzando l'endpoint /<CUSTOM_AUDIENCE_ID>/usersreplace puoi eliminare automaticamente tutti gli utenti esistenti, così da non dover caricare una lista di utenti da eliminare. Questo endpoint non reimposta la fase di apprendimento del gruppo di inserzioni quando un pubblico è parte dei gruppi di inserzioni attivi a differenza delle chiamate API POST o DELETE all'endpoint /<CUSTOM_AUDIENCE_ID>/users.

L'API Replace Users funziona solo con i gruppi di pubblico che soddisfano i seguenti requisiti:

• Il numero di utenti impostato prima di eseguire un processo di sostituzione deve essere inferiore a 100 milioni. Se il pubblico supera i 100 milioni, ti suggeriamo di ricorrere all'endpoint /<CUSTOM_AUDIENCE_ID>/users per aggiungere e rimuovere utenti.
• Il sottotipo deve essere impostato su CUSTOM.
• Non è possibile sostituire un gruppo di pubblico personalizzato del file cliente basato sul valore con un gruppo di pubblico personalizzato del file cliente non basato sul valore o viceversa.

Primi passi

Prima di avviare un processo di sostituzione, consigliamo di fare quanto segue:

• Verifica che, per il pubblico, operation_status sia Normal.

• Non aggiungere o rimuovere utenti con /<CUSTOM_AUDIENCE_ID>/users durante un'operazione di sostituzione in corso con /<CUSTOM_AUDIENCE_ID>/usersreplace. Se tenti di eseguire una seconda operazione di sostituzione prima che la prima sia stata completata, riceverai un messaggio indicante che è già in corso un'operazione di sostituzione.

• La finestra di durata massima di 1 sessione di sostituzione è di 90 minuti. L'API rifiuterà qualsiasi batch per una sessione ricevuta dopo 90 minuti dall'inizio di quella sessione. Se hai bisogno di inviare batch per un periodo superiore a 90 minuti, attendi il completamento dell'operazione di sostituzione per quella sessione, quindi usa l'operazione di aggiunta dell'endpoint /<CUSTOM_AUDIENCE>/users per il resto dei caricamenti.

• Quando il pubblico sarà pronto, specifica la lista di utenti da sostituire con il tuo pubblico personalizzato mediante una chiamata POST a /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Una volta iniziata l'operazione di sostituzione, lo stato operation_status del pubblico cambia in replace_in_progress.
  • Se l'operazione di sostituzione non va a buon fine, lo stato operation_status del pubblico cambia in replace_error.

Parametri chiamata

Puoi includere i parametri seguenti nella chiamata POST a /<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>" ]
}

Campi della sessione

Campi del payload

Una volta effettuata la richiesta POST, riceverai una risposta con i seguenti campi:

Errori comuni dell'API Replace

Tutti gli errori restituiti dall'endpoint Replace hanno il codice 2650. Ecco alcuni dei sottocodici di errore più comuni restituiti e indicazioni su come risolverli.

Risorse

È possibile creare e targetizzare o condividere altri tipi di pubblico:

• Pubblico personalizzato dal sito web: crea un pubblico basato sulle persone che hanno visitato una pagina specifica o effettuato un'azione sul tuo sito web. Crea un pubblico in base ai dati ricevuti dal pixel di Meta sul tuo sito.

• Pubblico personalizzato dall'app mobile: crea un pubblico personalizzato basato sulle persone che usano la tua app mobile. Crea un pubblico in base ai dati ricevuti da App Events.

• Pubblico simile: identifica le persone già note e invia la pubblicità a persone simili sull'app Facebook.

• Pubblico personalizzato offline: crea un pubblico basato sulle persone che hanno visitato il tuo punto vendita, effettuato chiamate al tuo servizio clienti o effettuato un'azione tramite altri mezzi offline.

• Pubblico personalizzato in base alle interazioni canvas: crea un pubblico che contiene le persone che hanno interagito con le tue unità canvas.

Altri contenuti da consultare

• Pubblico personalizzato
• Utenti di pubblico personalizzato
• Sessione pubblico personalizzato
• Condizioni d'uso del pubblico personalizzato