Públicos personalizados a partir de um arquivo de cliente

A API de Marketing permite criar públicos-alvo personalizados a partir das informações do cliente. Isso inclui endereços de email, telefones, nomes, datas de nascimento, gênero, localizações, números de identificação do usuário do app, números de identificação do usuário no escopo da Página, Identificador de Anunciante da Apple (IDFA, pelas iniciais em inglês) ou ID de publicidade do Android.

Você pode adicionar um número ilimitado de registros a um público, com o máximo de 10 mil por vez. As alterações nos públicos personalizados não são aplicadas de maneira automática. Geralmente, isso leva até 24 horas. O número de registros cuja remoção for solicitada e/ou o número de públicos personalizados na sua conta aumentará o tempo necessário para processar a solicitação.

Para melhorar a forma como os anunciantes criam e gerenciam públicos, os públicos personalizados de arquivo de cliente que não são usados em nenhum conjunto de anúncios ativo por mais de dois anos são sinalizados para exclusão periodicamente. Forneça instruções para que possamos realizar as ações necessárias. Assim que um público for sinalizado e movido para o estágio "Público prestes a expirar", você poderá usá-lo em um conjunto de anúncios ativos, e isso será entendido como uma instrução para que ele seja retido. Caso você decida não usar o público, isso será considerado uma instrução para que ele seja excluído. Para mais informações, consulte a documentação Custom Audiences Overview.

Criar um público personalizado

Etapa 1: criar um público personalizado vazio

Especifique subtype=CUSTOM e customer_file_source na sua chamada de 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',
})

Parâmetros

Etapa 2: especificar uma lista de usuários

Use uma chamada de API POST ao ponto de extremidade /{audience_id}/users para especificar a lista de usuários que você quer adicionar ao público personalizado.

Parâmetros

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

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

Opções de processamento de dados para usuários nos EUA

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

Campos de session

Resposta

Se for bem-sucedida, a resposta incluirá um objeto JSON com os seguintes campos:

Saiba mais sobre como compartilhar o público personalizado com objetos para empresas.

Remova membros do público

Use uma chamada de API DELETE ao ponto de extremidade /{audience_id}/users para especificar a lista de usuários que você quer remover do público personalizado.

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

Outra possibilidade é adicionar o parâmetro method e defini-lo como DELETE na solicitação POST usada para adicionar membros do público.

Você pode remover pessoas de uma lista com EXTERN_ID, se disponível.

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

Você pode remover uma lista de pessoas de todos os públicos personalizados na conta de anúncios por meio desse ponto de extremidade.

Pode haver motivos para as informações não serem processadas. Por exemplo, se a conta de anúncios não pertencer a uma conta empresarial, se você não tiver aceitado os Termos de Público Personalizado ou se as informações não corresponderem a um usuário.

Para remover uma conta da Central de Contas, inclua os mesmos campos necessários na atualização de usuário e faça uma chamada HTTP DELETE a:

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

Correspondência com várias chaves

Para aumentar a taxa de correspondência dos seus registros, forneça diversas chaves em uma matriz de chaves individuais, por exemplo, [EXTERN_ID, LN, FN, EMAIL]. Embora não seja necessário aplicar hash a EXTERN_ID, esse processo deverá ser feito com todas as informações de identificação pessoal, como emails e nomes. Consulte Hashing e normalização para várias chaves para ver mais informações.

Você pode fornecer algumas chaves ou todas elas para um registro. Para mais detalhes, consulte Correspondência com várias chaves de ID externo.

Adicionar usuários com correspondências de várias chaves

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 de PAGEUID

Se você usar a chave PAGEUID, será necessário incluir uma lista de identificações de Página. Você pode enviar somente um PAGEUID, que deve ser uma matriz com um 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

Hashing e normalização para várias chaves

É necessário aplicar hash aos dados como SHA256. Não aceitamos outros mecanismos de hashing. Isso é obrigatório para todos os dados, exceto Identificadores Externos, números de identificação do usuário do app, IDs do usuário no escopo da Página e identificações dos anunciantes da plataforma móvel.

Antes de aplicar hash, normalize seus dados para que possamos lidar com eles. Apenas Nome (FN) e Sobrenome (LN) aceitam caracteres especiais e alfabetos não romanos. Para melhores resultados de correspondência, forneça a transliteração no alfabeto romano sem caracteres especiais.

Uso de hash

Forneça valores SHA256 para as chaves normalizadas e representações HEX desse valor em letras minúsculas de A a F. A função hash em PHP converte emails e telefones normalizados.

Identificadores Externos

Você pode fazer a correspondência de pessoas para um público com os seus próprios identificadores, conhecidos como Identificadores Externos (EXTERN_ID). Pode ser qualquer identificação única do anunciante, como IDs de membro de programa de fidelidade, números de identificação do usuário e IDs de cookie externo.

Para melhorar a correspondência, use exatamente o mesmo formato ao enviar os IDs. Por exemplo, se escolher aplicar hash usando SHA256, use o mesmo valor com hash.

Você pode usar esses IDs como chaves pessoais para criar públicos personalizados ou excluir pessoas deles. Dessa forma, você não precisa carregar novamente nenhuma outra chave correspondente. Se você marcar alguém com informações pessoais convertidas em hash e EXTERN_ID, o EXTERN_ID terá prioridade menor na correspondência com pessoas no Facebook.

É possível reutilizar o mapeamento de EXTERN_ID para gerar públicos personalizados a partir de arquivos de clientes em uma mesma conta de anúncios.

Se você tiver um público com campos EXTERN_ID na sua conta de anúncios, crie um novo público somente com esses identificadores.

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

Você também pode adicionar pessoas com marcações de EXTERN_ID e correspondência com várias chaves.

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 de Substituição de Usuários

O ponto de extremidade /<CUSTOM_AUDIENCE_ID>/usersreplace permite que você realize duas ações com uma chamada de API:

• Remover completamente os usuários existentes de um público específico;
• Substituí-los por um novo conjunto de usuários.

O ponto de extremidade /<CUSTOM_AUDIENCE_ID>/usersreplace permite que você remova automaticamente todos os usuários existentes em vez de carregar uma lista com todos os usuários a serem excluídos. Ele não redefinirá a fase de aprendizado do seu conjunto de anúncios quando um público estiver em conjuntos ativos, ao contrário das chamadas de API POST ou DELETE ao ponto de extremidade /<CUSTOM_AUDIENCE_ID>/users.

A API de Substituição de Usuários funciona apenas com públicos que atendem aos requisitos a seguir:

• O número de usuários no local antes da execução do processo de substituição deve ser menor que 100 milhões. Se o público for maior que esse valor, sugerimos usar o ponto de extremidade /<CUSTOM_AUDIENCE_ID>/users para adicionar e remover usuários.
• O subtipo deve ser definido como CUSTOM.
• Não é possível substituir um público personalizado de arquivo de cliente baseado em valor por outro que não tenha como base um valor e vice-versa.

Começar

Antes de você começar o processo de substituição, recomendamos o seguinte:

• Verifique se o operation_status do público é Normal.

• Não adicione nem remova usuários usando /<CUSTOM_AUDIENCE_ID>/users durante uma operação de substituição por meio de /<CUSTOM_AUDIENCE_ID>/usersreplace. Caso tente fazer uma segunda operação de substituição antes que a primeira seja concluída, você receberá uma mensagem indicando que já existe uma operação em andamento.

• A janela de duração máxima de uma sessão de substituição é de 90 minutos. A API rejeitará os lotes da sessão recebidos após esse período. Se for necessário enviar lotes durante mais de 90 minutos, recomendamos esperar até que a operação de substituição da sessão tenha sido finalizada e, depois, usar a operação de adição do ponto de extremidade /<CUSTOM_AUDIENCE>/users para os carregamentos restantes.

• Assim que seu público estiver pronto, especifique a lista de usuários que você quer substituir pelo público personalizado por meio de uma chamada POST a /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Após iniciar o processo de substituição, o operation_status do seu público mudará para replace_in_progress.
  • Caso a operação de substituição não tenha sido concluída, o operation_status do público mudará para replace_error.

Parâmetros de chamada

Os seguintes parâmetros podem ser incluídos na sua chamada 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>" ]
}

Campos de sessão

Campos de carga

Ao fazer a solicitação POST, você receberá uma resposta com os seguintes campos:

Erros comuns da API de Substituição

Todos os erros retornados do ponto de extremidade de substituição têm o código de erro 2650. Veja alguns dos subcódigos de erro mais comuns, além de orientações sobre como corrigi-los.

Recursos

Você pode criar e direcionar ou compartilhar outros tipos de público:

• Públicos Personalizados do site: crie um público com base nas pessoas que visitaram uma página específica ou realizaram ações no site. Crie um público com base em dados do Pixel da Meta no seu site.

• Públicos Personalizados do aplicativo para celular: crie um público com base nas pessoas que usam o seu app para celular. Gere um público com base em dados de eventos do app.

• Públicos semelhantes: identifique pessoas que você já conhece e anuncie para usuários semelhantes no app do Facebook.

• Públicos Personalizados offline: crie um público com base nas pessoas que visitaram sua loja, ligaram para o atendimento ao cliente ou fizeram outras ações offline.

• Anúncios de coleção: crie um público com todas as pessoas que tiveram engajamento com o seu Canvas.

Veja também

• Custom Audience
• Custom Audience Users
• Custom Audience Session
• Custom Audience Terms Of Service