Fazer upload de públicos-alvo segmentados por lista de clientes

É possível criar públicos-alvo segmentados por lista de clientes usando informações de contato do cliente enviadas ou IDs de dispositivo móvel com a API do Display & Video 360. Esta página descreve como criar um público-alvo inicial de Segmentação por lista de clientes e anexar novos dados de clientes ao público-alvo atual usando a API do Display & Video 360.

Aviso: verifique se os recursos de upload de dados foram aprovados para o parceiro pai do público-alvo proposto tentando criar um público-alvo da Segmentação por lista de clientes com um anunciante relevante na interface. Se o upload de dados não tiver sido ativado, as tentativas de criar ou atualizar públicos-alvo de segmentação por lista de clientes vão retornar um erro. Os usuários com acesso ao nível do parceiro podem solicitar aprovação usando este formulário de solicitação de acesso do parceiro.

Preparar dados do usuário

Os dados do usuário usados para preencher os públicos-alvo da Segmentação por lista de clientes são sensíveis e precisam ser preparados corretamente antes do upload.

Gerar hash de dados sensíveis

Alguns públicos-alvo segmentado por lista de clientes são criados usando informações de contato sensíveis do cliente. O Display & Video 360 exige que os dados sensíveis sejam criptografados com hash usando o algoritmo SHA256 antes do upload. Os campos de dados a seguir precisam ser codificados antes do upload:

• Nome
• Sobrenome
• Endereços de e-mail
• Números de telefone

Os códigos postais e de país não devem ser criptografados com hash antes do upload. A tentativa de enviar dados de clientes não criptografados resulta em um erro.

Antes de gerar o hash dos dados, verifique se as seguintes condições são atendidas:

• Remova todos os espaços em branco dos valores de nome, sobrenome e endereço de e-mail.
• Todos os valores precisam estar em letras minúsculas.
• Todos os números de telefone precisam estar no formato E.164 e incluir o código de discagem do país.

Definir o consentimento do usuário

Ao fazer o upload de dados do usuário, use os campos consent nos objetos ContactInfoList ou MobileDeviceIdList fornecidos para transmitir sinais de consentimento concedidos pelos usuários incluídos.

A configuração de qualquer campo no objeto Consent como CONSENT_STATUS_DENIED resulta em um erro.

Aviso: é necessário enviar indicadores de consentimento ao fazer o upload de membros do público-alvo da Segmentação por lista de clientes no Espaço Econômico Europeu (EEE) para obedecer à Política de consentimento de usuários da União Europeia e usar os dados de usuários do EEE para preencher os públicos-alvo da Segmentação por lista de clientes.

Os indicadores de consentimento são definidos para todos os usuários adicionados em uma única solicitação de firstPartyAndPartnerAudiences.create ou firstPartyAndPartnerAudiences.editCustomerMatchMembers. Os usuários com indicadores de consentimento diferentes precisam ser enviados em solicitações separadas.

Criar um público-alvo de correspondência de clientes

É possível criar um público-alvo de Segmentação por lista de clientes usando o método firstPartyAndPartnerAudiences.create. O público-alvo precisa ser declarado como próprio e ter um audienceType de CUSTOMER_MATCH_CONTACT_INFO ou CUSTOMER_MATCH_DEVICE_ID. Os dados da Segmentação por lista de clientes precisam ser fornecidos usando o campo adequado no campo de união members.

Observação: o campo membershipDurationDays é obrigatório ao criar públicos-alvo com a segmentação por lista de clientes. As assinaturas individuais vão expirar após o período se não forem reenviadas para o público-alvo usando firstPartyAndPartnerAudiences.editCustomerMatchMembers.

Confira um exemplo de como criar um novo público-alvo de informações de contato do Customer Match com uma duração de associação de 540 dias usando uma lista de números de telefone com hash:

Java

// 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()
);

Python

# 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']);

Atualizar a associação de um público-alvo por lista de clientes

Se você identificou outros clientes que gostaria de segmentar, precisa renovar as assinaturas de público-alvo dos clientes ou quer remover clientes de um público-alvo, atualize os dados de um público-alvo segmentado por lista de clientes com o método firstPartyAndPartnerAudiences.editCustomerMatchMembers. É possível adicionar clientes a uma lista usando o campo de união added_members e remover clientes de uma lista com o campo de união removed_members.

Uma única solicitação firstPartyAndPartnerAudiences.editCustomerMatchMembers só pode adicionar ou remover membros de uma lista. Uma única solicitação que tenta fazer isso resulta em um erro INVALID_ARGUMENT.

Observação: os campos de metadados de informações de contato e públicos-alvo da correspondência do ID do dispositivo do recurso de correspondência do cliente, como displayName ou membershipDurationDays, podem ser atualizados usando o método firstPartyAndPartnerAudiences.patch.

Confira um exemplo de como adicionar um único cliente como membro de um público-alvo segmentado por lista de clientes com informações de contato usando os dados de endereço fornecidos:

Java

// 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()
);

Python

# 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']
);