Загрузить аудитории списков электронных адресов

Вы можете создавать аудитории Customer Match, используя загруженную контактную информацию клиентов или идентификаторы мобильных устройств с помощью API Display & Video 360. На этой странице описывается, как создать первоначальную аудиторию Customer Match и добавить новые данные клиентов к существующей аудитории с помощью API Display & Video 360.

Внимание: Убедитесь, что ваш партнер соответствует требованиям к загрузке данных из списков клиентов, указанным в нашей политике . Если ваш партнер не соответствует этим требованиям, попытки создания или обновления аудиторий из списков клиентов приведут к ошибке.

Подготовка пользовательских данных

Пользовательские данные, используемые для заполнения аудиторий Customer Match, являются конфиденциальными и должны быть надлежащим образом подготовлены перед загрузкой.

Хеш-конфиденциальные данные

Некоторые аудитории Customer Match создаются с использованием конфиденциальной контактной информации клиентов. Display & Video 360 требует хеширования конфиденциальных данных с помощью алгоритма SHA256 перед загрузкой. Перед загрузкой необходимо хешировать следующие поля данных:

• Имя
• Фамилия
• Адреса электронной почты
• Номера телефонов

Почтовые индексы и коды стран не следует хешировать перед загрузкой. Попытка загрузить нехешированные данные о клиентах приводит к ошибке.

Перед хешированием данных убедитесь в соблюдении следующих условий:

• Все пробелы из значений имени, фамилии и адреса электронной почты должны быть удалены.
• Все значения должны быть указаны строчными буквами.
• Все номера телефонов должны быть отформатированы в формате E.164 и включать код страны.

Установить согласие пользователя

При загрузке данных пользователей используйте поля consent в предоставленных объектах ContactInfoList или MobileDeviceIdList для передачи сигналов согласия, предоставленных включенными пользователями.

Установка для любого из полей объекта Consent значения CONSENT_STATUS_DENIED приводит к ошибке.

Внимание: при загрузке участников аудитории Customer Match из Европейской экономической зоны (ЕЭЗ) необходимо отправлять сигналы согласия, чтобы соблюдать Политику согласия пользователей из ЕС и использовать данные пользователей из ЕЭЗ для заполнения аудиторий Customer Match.

Сигналы согласия устанавливаются для всех пользователей, добавленных в одном запросе firstPartyAndPartnerAudiences.create или firstPartyAndPartnerAudiences.editCustomerMatchMembers . Пользователи с разными сигналами согласия должны быть загружены в отдельных запросах.

Создайте аудиторию Customer Match

Аудиторию Customer Match можно создать с помощью метода firstPartyAndPartnerAudiences.create . Аудитория должна быть объявлена ​​как собственная аудитория и иметь тип audienceType CUSTOMER_MATCH_CONTACT_INFO или CUSTOMER_MATCH_DEVICE_ID . Данные Customer Match должны быть предоставлены в соответствующем поле в объединенном поле members .

Примечание: Поле membershipDurationDays обязательно для заполнения при создании аудиторий Customer Match. Срок действия индивидуальных членств истечёт по истечении этого срока, если они не будут повторно загружены в аудиторию с помощью firstPartyAndPartnerAudiences.editCustomerMatchMembers .

Вот пример того, как создать новую аудиторию Customer Match с контактной информацией и продолжительностью членства 540 дней, используя предоставленный список хешированных номеров телефонов:

Ява

// Create Customer Match audience object.
FirstPartyAndPartnerAudience customerMatchAudience =
    new FirstPartyAndPartnerAudience()
        .setDisplayName(display-name)
        .setFirstPartyAndPartnerAudienceType(
            "FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY"
        )
        .setAudienceType("CUSTOMER_MATCH_CONTACT_INFO")
        .setMembershipDurationDays(540L);

// Build list of contact information objects.
ContactInfoList contactInfoList = new ContactInfoList();
ArrayList<ContactInfo> contactInfos = new ArrayList<ContactInfo>();
for (String hashedPhoneNumber : list-of-hashed-phone-numbers) {
  ContactInfo contactInfo = new ContactInfo();
  ArrayList<String> phoneNumberList = new ArrayList<String>();
  phoneNumberList.add(hashedPhoneNumber);
  contactInfo.setHashedPhoneNumbers(phoneNumberList);
  contactInfos.add(contactInfo);
}
contactInfoList.setContactInfos(contactInfos);

// Build consent object for passing consent if granted by the end user.
Consent consent =
    new Consent()
        .setAdUserData(ad-user-data-consent)
        .setAdPersonalization(ad-personalization-consent);
ContactInfoList.setConsent(consent);

// Assign contact info list to Customer Match audience.
customerMatchAudience.setContactInfoList(contactInfoList);

// Create Customer Match audience.
FirstPartyAndPartnerAudience response =
    service
        .firstPartyAndPartnerAudiences()
        .create(customerMatchAudience)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display name of new audience.
System.out.printf(
    "Customer Match audience %s was created.",
    response.getName()
);

Питон

# Build list of Contact Info objects
contact_infos = []
for hashed_phone_number in list-of-hashed-phone-numbers:
  contact_infos.append({'hashedPhoneNumbers': [hashed_phone_number]})

# Create a Customer Match first- and third-party audience object.
audience_obj = {
    'displayName': display-name,
    'firstPartyAndPartnerAudienceType':
        'FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY',
    'audienceType': 'CUSTOMER_MATCH_CONTACT_INFO',
    'membershipDurationDays': 540,
    'contactInfoList': {
        'contactInfos': [
            contact_infos
        ],
        'consent': {
            'adUserData': ad-user-data-consent,
            'adPersonalization': ad-personalization-consent
        }
    }
}

# Build and execute request.
audience = service.firstPartyAndPartnerAudiences().create(
    advertiserId=advertiser-id,
    body=audience_obj
).execute()

# Display name of new audience.
print('Customer Match audience %s was created.' % audience["name"])

PHP

// Create a Customer Match first-party and partner audience object.
$audience = new Google_Service_DisplayVideo_FirstPartyAndPartnerAudience();
$audience->setDisplayName(display-name);
$audience->setFirstPartyAndPartnerAudienceType(
    'FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY'
);
$audience->setAudienceType('CUSTOMER_MATCH_CONTACT_INFO');
$audience->setMembershipDurationDays(540);

// Build list of contact information objects.
$contactInfoList = new Google_Service_DisplayVideo_ContactInfoList();
$contactInfos = array();
foreach (list-of-hashed-phone-numbers as $hashedPhoneNumber) {
    $contactInfo = new Google_Service_DisplayVideo_ContactInfo();
    $contactInfo->setHashedPhoneNumbers(array($hashedPhoneNumber));
    $contactInfos[] = $contactInfo;
}
$contactInfoList->setContactInfos($contactInfos);

// Build consent object for passing consent if granted by the end user.
$consent = new Google_Service_DisplayVideo_Consent();
$consent->setAdUserData(ad-user-data-consent);
$consent->setAdPersonalization(ad-personalization-consent);
$contactInfoList->setConsent($consent);

// Assign contactInfoList to audience object.
$audience->setContactInfoList($contactInfoList);

// Call the API, creating the audience.
$result = $this->service->firstPartyAndPartnerAudiences->create(
    $audience,
    array('advertiserId' => advertiser-id)
);

// Display name of new audience.
printf('Customer Match audience %s was created.', $result['name']);

Обновление состава аудитории Customer Match

Если вы определили дополнительных клиентов, на которых хотели бы нацелиться, хотите продлить членство существующих аудиторий клиентов или удалить клиентов из аудитории, вы можете обновить данные клиентов существующей аудитории Customer Match с помощью метода firstPartyAndPartnerAudiences.editCustomerMatchMembers . Вы можете добавлять клиентов в список, используя поле объединения added_members и удалять клиентов из списка, используя поле объединения removed_members .

Один запрос firstPartyAndPartnerAudiences.editCustomerMatchMembers может только добавлять или удалять участников из списка. Попытка сделать и то, и другое одним запросом приводит к ошибке INVALID_ARGUMENT .

Примечание: Поля метаданных контактной информации и идентификатора устройства для аудиторий Customer Match, такие как displayName или membershipDurationDays , можно обновить с помощью метода firstPartyAndPartnerAudiences.patch .

Вот пример того, как добавить одного клиента в качестве участника в существующую контактную информацию аудитории Customer Match, используя предоставленные данные о почтовом адресе:

Ява

// Create an edit members request object.
EditCustomerMatchMembersRequest editCustomerMatchMembersRequest =
    new EditCustomerMatchMembersRequest()
        .setAdvertiserId(advertiser-id);

// Build contact information object to add to audience.
ContactInfoList contactInfoList = new ContactInfoList();
ArrayList<ContactInfo> contactInfos = new ArrayList<ContactInfo>();
ContactInfo contactInfo =
    new ContactInfo()
        .setHashedFirstName(hashed-customer-first-name)
        .setHashedLastName(hashed-customer-last-name)
        .setZipCodes(customer-zip-codes-list)
        .setCountryCode(customer-country-code);
contactInfos.add(contactInfo);
contactInfoList.setContactInfos(contactInfos);

// Build consent object for passing consent if granted by the end user.
Consent consent =
    new Consent()
        .setAdUserData(ad-user-data-consent)
        .setAdPersonalization(ad-personalization-consent);
ContactInfoList.setConsent(consent);

// Assign contact info list to request body.
editCustomerMatchMembersRequest.setAddedContactInfoList(contactInfoList);

// Edit Customer Match audience membership.
EditCustomerMatchMembersResponse response =
    service
        .firstPartyAndPartnerAudiences()
        .editCustomerMatchMembers(
            audience-id,
            editCustomerMatchMembersRequest
        )
        .execute();

// Display ID of updated audience.
System.out.printf(
    "The membership of Customer Match audience ID %s was edited.",
    response.getFirstPartyAndPartnerAudienceId()
);

Питон

# Create an edit members request object.
edit_member_request_obj = {
    'advertiserId': advertiser-id,
    'addedContactInfoList': {
        'contactInfos': [
            {
                'hashedFirstName': hashed-customer-first-name,
                'hashedLastName': hashed-customer-last-name,
                'countryCode': customer-country-code,
                'zipCodes': customer-zip-codes-list
            }
        ],
        'consent': {
          'adUserData': ad-user-data-consent,
          'adPersonalization': ad-personalization-consent
        }
    }
}

# Build and execute request.
response = service.firstPartyAndPartnerAudiences().editCustomerMatchMembers(
    firstPartyAndPartnerAudienceId=audience-id,
    body=edit_member_request_obj
).execute()

# Display ID of updated audience.
print('The membership of the Customer Match audience ID %s was updated.'
      % response["firstPartyAndPartnerAudienceId"])

PHP

// Create an edit members request object.
$editMemberRequest =
    new Google_Service_DisplayVideo_EditCustomerMatchMembersRequest();
$editMemberRequest->setAdvertiserId(advertiser-id);

// Build contact information object to add to audience.
$contactInfoList = new Google_Service_DisplayVideo_ContactInfoList();
$contactInfos = array();
$contactInfo = new Google_Service_DisplayVideo_ContactInfo();
$contactInfo->setHashedFirstName(hashed-customer-first-name);
$contactInfo->setHashedLastName(hashed-customer-last-name);
$contactInfo->setCountryCode(customer-country-code);
$contactInfo->setZipCodes(array(customer-zip-codes-list));
$contactInfos[] = $contactInfo;
$contactInfoList->setContactInfos($contactInfos);

// Build consent object for passing consent if granted by the end user.
$consent = new Google_Service_DisplayVideo_Consent();
$consent->setAdUserData(ad-user-data-consent);
$consent->setAdPersonalization(ad-personalization-consent);
$contactInfoList->setConsent($consent);

// Assign contactInfoList to edit members request body.
$editMemberRequest->setAddedContactInfoList($contactInfoList);

// Call the API, editing the audience membership.
$response = $this
    ->service
    ->firstPartyAndPartnerAudiences
    ->editCustomerMatchMembers(
        audience-id,
        $editMemberRequest
    );

// Display ID of updated audience.
printf(
    'The membership of Customer Match audience ID %s was edited',
    $result['firstPartyAndPartnerAudienceId']
);