Пользовательские аудитории на основе файла с данными о клиентах

API Marketing позволяет создавать целевые пользовательские аудитории на основании информации о клиентах. Это могут быть электронные адреса, номера телефонов, имена, даты рождения, пол, местоположение, ID пользователей внутри приложений, ID пользователей внутри страниц, рекламные идентификаторы Apple (IDFA) или рекламные идентификаторы Android.

В аудиторию можно добавлять неограниченное количество записей, но не более 10 000 за раз. Изменения пользовательской аудитории применяются не сразу. Обычно это занимает до 24 часов. Чем больше записей вы удаляете и (или) чем больше пользовательских аудиторий содержит ваш аккаунт, тем больше времени нужно для обработки запроса.

Чтобы повысить для рекламодателей удобство создания и администрирования аудиторий, мы ввели следующее правило: пользовательские аудитории на основе файлов с данными о клиентах, не применявшиеся в активных группах объявлений более двух лет, будут помечаться для удаления. Дальнейшие действия с такой аудиторией будут зависеть от ваших инструкций. После того как к аудитории будет добавлена пометка об истечении срока действия, вы должны будете использовать ее в активной группе объявлений (мы расцениваем это как инструкцию по сохранению аудитории) либо не делать этого (это будет воспринято как инструкция по ее удалению). Дополнительные сведения см. в документации с обзором пользовательских аудиторий.

Создание пользовательской аудитории

1. Создайте пустую пользовательскую аудиторию.

В вызове API укажите параметры subtype=CUSTOM и customer_file_source.

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',
})

Параметры

2. Задайте список пользователей.

Отправьте вызов API POST к конечной точке /{audience_id}/users и укажите список пользователей для аудитории.

Параметры

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

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

Параметры обработки данных для пользователей в США

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

Поля session

Ответ

В случае успеха возвращается объект JSON со следующими полями:

Подробнее об отправке пользовательских аудиторий бизнес-объектам.

Удаление участников из аудитории

Чтобы задать список пользователей, которых нужно удалить из пользовательской аудитории, выполните вызов API DELETE к конечной точке /{audience_id}/users.

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

Кроме того, можно использовать тот же запрос POST, что и для добавления участников аудитории, задав для параметра method значение DELETE.

Для удаления людей из списка можно использовать идентификатор EXTERN_ID (при его наличии).

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

Эта конечная точка позволяет удалить набор участников из всех пользовательских аудиторий рекламного аккаунта.

Причин, по которым эта информация не обрабатывается, может быть несколько. Например, рекламный аккаунт не принадлежит бизнес-аккаунту, вы ещё не приняли Соглашение о пользовательских аудиториях либо данные не соответствуют пользователю.

Чтобы удалить аккаунт, добавьте те же поля, что и при обновлении данных пользователя, и выполните вызов HTTP DELETE к следующей конечной точке:

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

Сопоставление по нескольким ключам

Чтобы увеличить долю совпадения в своих данных, укажите массив из нескольких отдельных ключей, например [EXTERN_ID, LN, FN, EMAIL]. Все персональные данные, позволяющие установить личность (в том числе электронные адреса и имена), необходимо хэшировать. Для EXTERN_ID хэширование не требуется. Подробные сведения см. в разделе о хэшировании и нормализации данных.

Для записей можно указывать все или только некоторые ключи. Подробные сведения см. в разделе о сопоставлении внешнего ID по нескольким ключам.

Добавление пользователей с сопоставлением по нескольким ключам

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

Использование PAGEUID

При использовании ключа PAGEUID также необходимо указывать список ID Страниц. Можно отправить только один ключ PAGEUID. Он должен быть представлен в виде массива с одним элементом.

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

Хэширование и нормализация для нескольких ключей

Используйте для хэширования данных алгоритм SHA256. Мы не поддерживаем другие механизмы хэширования. Это требование действует для всех данных, кроме внешних идентификаторов, ID пользователей приложений, ID пользователей в пределах страниц и ID рекламодателей на мобильных устройствах.

Перед хэшированием данные необходимо нормализовать, иначе мы не сможем их обработать. Использовать специальные символы и буквы, которых нет в латинице, можно только в полях FN (имя) и LN (фамилия). Для максимально точного сопоставления транслитерируйте имена латиницей, не используя специальные символы.

Хэширование

Указывайте значения в формате SHA256 для нормализованных ключей и шестнадцатеричное представление HEX этих значений. Используйте буквы с A по F в нижнем регистре. Функция hash в PHP преобразует нормализованные значения электронных адресов и номеров телефонов.

Внешние идентификаторы

Для добавления людей в аудиторию можно использовать собственные ID. Это так называемые внешние идентификаторы, или EXTERN_ID. Это могут быть любые уникальные идентификаторы, регистрируемые рекламодателем: ID участников программы лояльности, ID пользователей, ID внешних файлов cookie и т. д.

Чтобы поиск совпадений был эффективнее, используйте при отправке ID точно такой же формат. Например, если для хэширования применяется алгоритм SHA256, указывайте одно и то же хэшированное значение.

Эти ID можно использовать в качестве индивидуальных ключей для создания пользовательских аудиторий и удаления их участников. Так вам не понадобится заново загружать другие ключи сопоставления. Если для одного человека задана хэшированная личная информация и EXTERN_ID, при сопоставлении пользователя с другими людьми на Facebook EXTERN_ID имеет второстепенное значение.

EXTERN_ID можно использовать для разных пользовательских аудиторий на основе файла в одном рекламном аккаунте.

Если в вашем рекламном аккаунте есть аудитория с полями EXTERN_ID, создайте новую аудиторию на основе только этих идентификаторов.

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

Кроме того, можно добавить людей с меткой EXTERN_ID и сопоставлением по нескольким ключам.

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

Конечная точка /<CUSTOM_AUDIENCE_ID>/usersreplace позволяет выполнить 2 действия в одном вызове:

• полностью удалить существующих пользователей из определенной аудитории;
• заменить их новой группой пользователей.

Конечная точка /<CUSTOM_AUDIENCE_ID>/usersreplace позволяет автоматически удалить всех существующих пользователей, не загружая список пользователей для удаления. При использовании этой конечной точки этап обучения группы объявлений, когда аудитория входит в активные группы объявлений, не сбрасывается, как это происходит при использовании вызовов API POST и DELETE к конечной точке /<CUSTOM_AUDIENCE_ID>/users.

API Replace Users работает только с аудиториями, которые отвечают следующим требованиям:

• Количество имеющихся пользователей перед запуском процесса замены должно быть меньше 100 миллионов. Если размер аудитории превышает 100 миллионов, рекомендуем применять для добавления и удаления пользователей конечную точку /<CUSTOM_AUDIENCE_ID>/users.
• Должен быть выбран подтип CUSTOM.
• Заменить пользовательскую аудиторию на основе файла с данными о клиентах на базе ценности аудиторией не на базе ценности или наоборот невозможно.

Начало замены

Перед началом процесса замены учтите следующие рекомендации:

• аудитория operation_status должна иметь статус Normal.

• Кроме того, во время замены через конечную точку /<CUSTOM_AUDIENCE_ID>/usersreplace добавлять и удалять пользователей через /<CUSTOM_AUDIENCE_ID>/users также нельзя. Если вы попытаетесь выполнить вторую операцию замены до завершения первой, то получите сообщение о том, что замена уже выполняется.

• Максимальная продолжительность одного сеанса замены составляет 90 минут. API отклоняет все пакеты в рамках сеанса, полученные по истечении 90 минут с момента его начала. Если вам нужно отправлять пакеты в течение интервала, превышающего 90 минут, дождитесь, пока завершится операция замены для этого сеанса, а затем добавьте оставшихся пользователей, используя конечную точку /<CUSTOM_AUDIENCE>/users.

• Когда аудитория будет готова, укажите список пользователей, которых вы хотите заменить своей пользовательской аудиторией, выполнив вызов POST к /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • После запуска операции замены параметр operation_status аудитории принимает значение replace_in_progress.
  • Если полностью выполнить замену не удалось, параметр operation_status аудитории принимает значение replace_error.

Параметры вызова

В вызове 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>" ]
}

Поля сеанса

Поля полезных данных

Запрос POST должен вернуть ответ со следующими полями:

Распространенные ошибки при использовании API Replace

Все ошибки, возвращаемые конечной точкой замены, имеют код 2650. Ниже перечислены некоторые подкоды наиболее распространенных возвращаемых ошибок и способы их устранения.

Дополнительная информация

Существуют и другие типы аудиторий, которые можно создавать, использовать для таргетинга и предоставлять другим компаниям:

• Пользовательские аудитории с сайта — аудитории из людей, посетивших определенную страницу либо выполнивших на сайте то или иное действие. Используйте для создания таких аудиторий данные пикселя Meta на своем сайте.

• Пользовательские аудитории из мобильного приложения — создавайте аудитории из людей, которые пользуются вашим мобильным приложением. Используйте для создания таких аудиторий данные о событиях в приложении.

• Похожие аудитории — находите людей, которых вы уже знаете, и демонстрируйте объявления похожим пользователям приложения Facebook.

• Пользовательские аудитории в офлайне — создавайте аудитории из людей, которые посетили ваш магазин, позвонили в вашу службу поддержки клиентов или совершили другие офлайн-действия.

• Аудитории на основе вовлеченности для холста — аудитории из людей, которые взаимодействовали с вашим холстом.

См. также

• Пользовательская аудитория
• Участники пользовательской аудитории
• Сеанс загрузки данных для пользовательской аудитории
• Пользовательские аудитории: пользовательское соглашение