Públicos personalizados creados a partir de un archivo de clientes

La API de marketing te permite crear públicos objetivo personalizados a partir de la información de los clientes. Esta incluye direcciones de correo electrónico, números de teléfono, nombres, fechas de nacimiento, género, ubicaciones, identificadores de usuario de la app, identificadores de usuarios específicos de la página, identificadores de publicidad de Apple (IDFA) o identificadores de publicidad de Android.

Puedes agregar una cantidad ilimitada de registros a un público, pero solo un máximo de 10.000 a la vez. Los cambios en tus públicos personalizados no se aplican de inmediato y generalmente demoran hasta 24 horas. La cantidad de registros que solicites eliminar y/o la cantidad de públicos personalizados que contenga tu cuenta aumentará el tiempo de procesamiento de esta solicitud.

Para mejorar la forma en que los anunciantes crean y administran los públicos, se marcarán de forma continua para su eliminación los públicos personalizados de un archivo de clientes que no se usaron en ningún conjunto de anuncios activo durante dos años. Es necesario que nos proporciones tus instrucciones antes de que realicemos cualquier acción. Cuando se mueven los públicos al estado "Expiring Audience" y se marca, es necesario que brindes instrucciones, ya sea que utilices los públicos marcados en un conjunto de anuncios activos, que se considerará como la instrucción de conservar el público, o que decidas no usarlos, lo que se interpretará como la instrucción de eliminar el público. Para obtener más información, consulta la documentación de información general sobre los públicos personalizados.

Crear un público personalizado

Paso 1: Crear un público personalizado vacío

Especifica subtype=CUSTOM y customer_file_source en tu llamada a la 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',
})

Parámetros

Paso 2: Especifica una lista de usuarios

Usa una llamada a la API POST al punto de conexión /{audience_id}/users para especificar la lista de usuarios que quieres agregar a tu 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>"] 
    ]
}

Opciones de procesamiento de datos para usuarios de EE. UU.

{
   "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 session

Respuesta

Una respuesta satisfactoria incluye un objeto JSON con los siguientes campos:

Obtén más información sobre cómo compartir tu público personalizado con objetos del negocio.

Eliminación de miembros del público

Usa una llamada a la API DELETE al punto de conexión /{audience_id}/users para especificar la lista de usuarios que quieres eliminar de tu 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

O bien, puedes agregar el parámetro method y configurarlo como DELETE en la solicitud POST que se usa para agregar miembros del público.

También puedes excluir a personas de una lista con EXTERN_ID, si está 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

Puedes eliminar una lista de personas de todos los públicos personalizados en tu cuenta publicitaria con este punto de conexión.

Esta información podría no procesarse por varios motivos. Por ejemplo, si la cuenta publicitaria no pertenece a un portfolio comercial, todavía no aceptaste las Condiciones de los públicos personalizados o la información no coincide con un usuario.

Para eliminar una cuenta del centro de cuentas, incluye los mismos campos que se usan en la actualización de usuario y haz una llamada HTTP DELETE a:

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

Coincidencia de claves múltiples

Para aumentar la proporción de coincidencias de tus registros, proporciona claves múltiples en una matriz de claves individuales; por ejemplo, [EXTERN_ID, LN, FN, EMAIL]. Si bien no es necesario que cifres EXTERN_ID, sí debes cifrar toda la información de identificación personal de los miembros del público, como correos electrónicos y nombres. Consulta información detallada en Cifrado y normalización de datos.

Puedes especificar algunas o todas las claves múltiples de un registro. Para obtener más detalles, consulta la información sobre la coincidencia de identificadores externos de claves múltiples.

Agregar usuarios con coincidencias de claves múltiples

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

Mediante PAGEUID

Si usas la clave PAGEUID, también debes incluir una lista de los identificadores de la página. Solo puedes enviarnos un PAGEUID, que debería ser una matriz con un solo 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

Cifrado y normalización para claves múltiples

Debes cifrar los datos como SHA256; no admitimos otros mecanismos de cifrado. Esto es obligatorio para todos los datos, excepto los identificadores externos, los identificadores de usuario de app, los identificadores de usuario específicos de la página y los identificadores de anunciantes en celulares.

Antes de cifrar tus datos, normalízalos para que podamos procesar la acción. Solo el nombre (FN) y el apellido (LN) admiten caracteres especiales y alfabetos no romanos. Para obtener los mejores resultados de coincidencia, proporciona la traducción al alfabeto romano sin caracteres especiales.

Cifrado

Proporciona valores SHA256 para las claves normalizadas y las representaciones HEX de este valor; utiliza minúscula para las letras de la A a la F. La función hash en PHP convierte el correo electrónico y el número de teléfono normalizados.

Identificadores externos

Puedes hacer coincidir personas para un público con tus propios identificadores, conocidos como identificadores externos (EXTERN_ID). Puede ser cualquier identificador único del anunciante, como identificadores de membresías de fidelidad, identificadores de usuarios e identificadores de cookies externas.

Para que las coincidencias funcionen mejor, también deberías usar el mismo formato cuando envíes los identificadores. Por ejemplo, si eliges utilizar la función de cifrado mediante SHA256, asegúrate de usar el mismo valor de cifrado.

Puedes utilizar estos identificadores como claves individuales para eliminar personas de públicos personalizados o crear nuevos públicos personalizados. De este modo, no es necesario que vuelvas a subir ninguna otra clave que coincida. Si etiquetas a alguien con información personal cifrada y EXTERN_ID, asignamos una prioridad menor a EXTERN_ID cuando buscamos coincidencias con personas en Facebook.

Puedes volver a usar la asignación de EXTERN_ID para crear públicos personalizados de un archivo personalizado en una misma cuenta publicitaria.

Si tienes un público creado a partir de los campos EXTERN_ID en tu cuenta publicitaria, crea un nuevo público únicamente con los siguientes identificadores:

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

También puedes agregar a personas etiquetadas con EXTERN_ID y con coincidencia de claves múltiples.

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 reemplazo de usuarios

El punto de conexión /<CUSTOM_AUDIENCE_ID>/usersreplace te permite realizar 2 acciones con una llamada a la API:

• Eliminar por completo los usuarios actuales de un público específico
• Reemplazar esos usuarios por un nuevo grupo de usuarios

Usar el punto de conexión /<CUSTOM_AUDIENCE_ID>/usersreplace te permite eliminar automáticamente todos los usuarios preexistentes, en lugar de tener que subir una lista de los usuarios que deseas eliminar. Este punto de conexión tampoco restablece la fase de aprendizaje del conjunto de anuncios cuando un público es parte de los conjuntos de anuncios activos, lo que se diferencia de las llamadas a la API "POST" o "DELETE" al punto de conexión /<CUSTOM_AUDIENCE_ID>/users.

La API de reemplazo de usuarios solo funciona con públicos que cumplen con los siguientes requisitos:

• La cantidad final de usuarios antes de ejecutar el proceso de reemplazo debe ser inferior a 100 millones. Si el público es mayor a 100 millones, te sugerimos aprovechar el punto de conexión /<CUSTOM_AUDIENCE_ID>/users para agregar o eliminar usuarios.
• El subtipo se debe fijar en CUSTOM.
• No se puede reemplazar un público personalizado de archivo de cliente basado en valores por un público personalizado de archivo de cliente no basado en valores o viceversa.

Primeros pasos

Antes de empezar el proceso de reemplazo, te recomendamos lo siguiente:

• Asegúrate de que el operation_status de tu público sea Normal.

• No agregues ni elimines usuarios mediante /<CUSTOM_AUDIENCE_ID>/users durante una operación de reemplazo en curso a través de /<CUSTOM_AUDIENCE_ID>/usersreplace. Si intentas ejecutar una segunda operación de reemplazo antes de que finalice la primera, recibirás un mensaje en el que se te indicará que ya hay una operación de reemplazo en curso.

• El intervalo de duración máximo de una sesión de reemplazo es de 90 minutos. La API rechazará los lotes de una sesión que se hayan recibido 90 minutos después de iniciada la sesión. Si necesitas enviar lotes por más de 90 minutos, espera hasta que finalice la operación de reemplazo de dicha sesión y luego utilizar la operación de adición del punto de conexión /<CUSTOM_AUDIENCE>/users para el resto de las subidas.

• Una vez que esté listo tu público, especifica la lista de usuarios que deseas reemplazar por tu público personalizado con una llamada POST al /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Una vez que inicies el proceso de reemplazo, el operation_status de tu público cambiará a replace_in_progress.
  • Si la operación de reemplazo no se completó, el operation_status cambiará a replace_error.

Parámetros de llamadas

Puedes incluir los siguientes parámetros en tu llamada 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 sesión

Campos de carga

Una vez que hagas tu solicitud POST, recibirás una respuesta con los siguientes campos:

Errores comunes de la API de reemplazo

Todos los errores que se devuelven del punto de conexión de reemplazo tienen el código de error 2650. Aquí, te mostramos algunos de los subcódigos de error más comunes, además de proporcionarte orientación sobre cómo resolverlos.

Recursos

Hay otros tipos de públicos que puedes desarrollar y a los que puedes dirigirte, o que puedes compartir:

• Públicos personalizados de tu sitio web: crea un público en función de las personas que visitaron una página específica o realizaron una acción en tu sitio web. Crea un público en función de los datos del píxel de Facebook en tu sitio.

• Públicos personalizados de tu app para celulares: crea un público en función de las personas que utilizan tu app para celulares. Crea un público en función de los datos de eventos de la app.

• Públicos similares: identifica a las personas que ya conoces y muestra anuncios a personas similares en la app de Facebook.

• Públicos personalizados offline: crea un público en función de las personas que visitaron tu tienda, realizaron llamadas a tu servicio de atención al cliente o realizaron acciones con otros medios offline.

• Públicos de interacción de Canvas: crea un público que incluya a todas las personas que interactuaron con tu Canvas.

Más información

• Público personalizado
• Usuarios de público personalizado
• Sesión de público personalizado
• Condiciones del servicio de públicos personalizados