Audiencias personalizadas de archivos de clientes

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

Puedes añadir un número ilimitado de registros a una audiencia, pero solo un máximo de 10 000 a la vez. Los cambios en las audiencias personalizadas no se realizarán de forma inmediata, sino que normalmente tardarán un total de 24 horas en aplicarse. En función del número de registros que solicites eliminar o el número de audiencias personalizadas que contenga tu cuenta, se puede tardar más tiempo en procesar la solicitud.

Para mejorar la forma en que los anunciantes crean y administran sus audiencias, las audiencias personalizadas de archivos de clientes que no se han utilizado en ningún conjunto de anuncios activo durante más de dos años se marcarán para eliminarse de forma continuada. Deberás proporcionarnos instrucciones antes de que llevemos a cabo ninguna acción. Una vez que las audiencias se han movido a la fase “Audiencia a punto de caducar” y se han marcado, deberás proporcionarnos instrucciones mediante la audiencia marcada en un conjunto de anuncios activo, lo que se considerará una instrucción para conservar la audiencia, o bien mediante la decisión de no utilizar la audiencia marcada en un conjunto de anuncios activo, lo que se considerará una instrucción para eliminar la audiencia. Para obtener más información, consulta la documentación Información de audiencias personalizadas.

Crear una audiencia personalizada

Paso 1: Crear una audiencia personalizada vacía

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/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

Paso 2: Especificar una lista de usuarios

Utiliza una llamada a la API POST al extremo /{audience_id}/users para especificar la lista de usuarios que quieres añadir a tu audiencia personalizada.

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 tratamiento 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 campos siguientes:

Obtén más información sobre cómo compartir la audiencia personalizada con los objetos empresariales.

Eliminación de miembros de la audiencia

Utiliza una llamada a la API DELETE al extremo /{audience_id}/users para especificar la lista de usuarios que quieres eliminar de tu audiencia personalizada.

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

También puedes añadir el parámetro method y establecerlo en DELETE en la solicitud POST utilizada para añadir miembros de la audiencia.

Puedes eliminar usuarios de una lista con el valor de 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 usuarios de todas las audiencias personalizadas de tu cuenta publicitaria mediante este extremo.

Esta información puede no tratarse por varios motivos. Por ejemplo, si la cuenta publicitaria no pertenece a ninguna cuenta empresarial, si aún no has aceptado las condiciones de las audiencias personalizadas o si la información no coincide con la de ningún usuario.

Para eliminar una cuenta del Centro de cuentas, incluye los mismos campos que 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, especifica varias claves en una matriz de claves individuales; por ejemplo, [EXTERN_ID, LN, FN, EMAIL]. Aunque no necesitas aplicar algoritmos hash en EXTERN_ID, sí que debes aplicarlos en toda la información de identificación personal, como correos electrónicos y nombres. Para obtener más información, consulta Aplicación de algoritmos hash y normalización de los datos.

Puedes proporcionar algunas o todas las claves múltiples de un registro. Para obtener más información, consulta Coincidencia de identificadores externos de claves múltiples.

Añadir usuarios mediante 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

Uso de PAGEUID

Si utilizas la clave PAGEUID, también debes incluir una lista de identificadores de la página. Solo puedes enviarnos un valor de PAGEUID, que debe ser una matriz 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

Algoritmos hash y normalización de claves múltiples

Debes aplicar algoritmos hash a los datos como SHA256. No admitimos otros mecanismos de algoritmos hash. Esto se requiere para todos los datos, excepto los identificadores externos, identificadores de usuario de la aplicación, identificadores de usuario específicos de la página o identificadores de anunciante en móviles.

Antes de aplicar algoritmos hash a los datos, normalízalos para que los podamos gestionar. Solo el nombre (FN) y los apellidos (LN) admiten caracteres especiales y alfabetos no latinos. Para obtener los mejores resultados de coincidencia, proporciona la traducción del alfabeto latino sin caracteres especiales.

Algoritmos hash

Proporciona valores SHA256 para las claves normalizadas y representaciones HEX de este valor, con minúsculas de la A a la F. La función hash de PHP convierte números de teléfono y correos electrónicos normalizados.

Identificadores externos

Puedes establecer coincidencias entre personas y una audiencia con tus propios identificadores, conocidos como identificadores externos (EXTERN_ID). Puedes utilizar cualquier identificador único del anunciante, como los identificadores de solicitudes de miembros de fidelidad, de usuario y de cookies externas.

Para mejorar las coincidencias, también debes usar el mismo formato exacto cuando envíes los identificadores. Por ejemplo, si optas por aplicar un algoritmo hash con SHA256, asegúrate de utilizar el mismo valor al que lo has aplicado.

Puedes utilizar estos identificadores como claves individuales para eliminar personas de las audiencias personalizadas o crear nuevas audiencias personalizadas. De este modo, no es necesario volver a subir ninguna otra clave coincidente. Si etiquetas a alguien con información personal cifrada con hash y EXTERN_ID, damos menos prioridad al valor EXTERN_ID cuando establecemos coincidencias entre este y los usuarios de Facebook.

Puedes volver a utilizar la asignación EXTERN_ID para crear audiencias personalizadas de archivos de clientes en una cuenta publicitaria única.

Si tienes una audiencia de los campos EXTERN_ID en tu cuenta publicitaria, crea una nueva solo con estos 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 añadir usuarios con la etiqueta EXTERN_ID y con la 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 extremo /<CUSTOM_AUDIENCE_ID>/usersreplace te permite realizar dos acciones con una llamada a la API:

• Eliminar por completo los usuarios existentes de una audiencia específica.
• Reemplazar a dichos usuarios por un nuevo conjunto de usuarios.

El uso del extremo /<CUSTOM_AUDIENCE_ID>/usersreplace te permite eliminar automáticamente todos los usuarios existentes en lugar de tener que subir una lista de usuarios que quieres eliminar. Este extremo no restablece la fase de aprendizaje del conjunto de anuncios cuando la audiencia forma parte de conjuntos de anuncios activos como llamadas POST o DELETE a la API para el extremo /<CUSTOM_AUDIENCE_ID>/users.

La API de reemplazo de usuarios solo funciona con audiencias que cumplen los requisitos siguientes:

• El número de usuarios disponibles antes de ejecutar un proceso de reemplazo debe ser inferior a 100 millones. Si tu audiencia supera los 100 millones, te sugerimos que utilices el extremo /<CUSTOM_AUDIENCE_ID>/users para añadir y eliminar usuarios.
• El subtipo debe establecerse en CUSTOM.
• No puedes reemplazar una audiencia personalizada de archivos de clientes basada en valores por otra que no se base en valores, ni viceversa.

Empezar

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

• Asegúrate de que el valor de operation_status de tu audiencia sea Normal.

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

• El periodo máximo de duración de una sesión de reemplazo es de 90 minutos. La API rechazará todos los lotes de una sesión que reciba 90 minutos después del inicio de dicha sesión. Si necesitas enviar lotes durante un periodo superior a 90 minutos, espera hasta que se complete la operación de reemplazo de dicha sesión y, a continuación, utiliza la operación de adición del extremo /<CUSTOM_AUDIENCE>/users para el resto de las subidas.

• Una vez que la audiencia esté lista, especifica la lista de usuarios que quieres reemplazar por la audiencia personalizada con una llamada POST a /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Una vez que inicies el proceso de reemplazo, el objeto operation_status de la audiencia cambiará a replace_in_progress.
  • Si la operación de reemplazo está incompleta, el objeto operation_status de la audiencia cambiará a replace_error.

Parámetros de llamada

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

Campos de la carga

Una vez que realices una solicitud POST, obtendrás una respuesta con los campos siguientes:

Errores comunes de la API de reemplazo

Todos los errores que se devuelven del extremo de reemplazo tienen el código de error 2650. A continuación, se indican algunos de los subcódigos de error que se devuelven con más frecuencia, así como instrucciones sobre cómo resolverlos.

Recursos

Existen otros tipos de audiencias que puedes crear y segmentar o compartir:

• Audiencias personalizadas del sitio web: crea una audiencia basada en usuarios que han visitado una página específica o que han realizado alguna acción en tu sitio web. Crea una audiencia basada en datos del píxel de Meta en tu sitio.

• Audiencias personalizadas de tu aplicación para móviles: crea una audiencia basada en usuarios que utilizan tu aplicación para móviles. Crea una audiencia basada en datos de los eventos de la aplicación.

• Audiencias similares: identifica a usuarios que ya conoces y muestra anuncios a usuarios similares en la aplicación de Facebook.

• Audiencias personalizadas offline: crea una audiencia basada en usuarios que han visitado tu tienda, que han hecho llamadas al servicio de atención al cliente o que han realizado alguna acción mediante otros medios fuera de internet.

• Audiencias de interacción de Canvas: crea una audiencia que contenga las personas que hayan interactuado con tu instancia de Canvas.

Más información

• Audiencia personalizada
• Usuarios de la audiencia personalizada
• Sesión de la audiencia personalizada
• Condiciones del servicio de la audiencia personalizada