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

É possível criar públicos-alvo segmentados por lista de clientes usando os dados de contato dos clientes ou os IDs de dispositivos móveis enviados por meio da API Display & Video 360. Nesta página, descrevemos como criar um público-alvo inicial segmentado por lista de clientes e anexar dados de novos clientes ao público-alvo atual usando a API Display & Video 360.

Aviso :tente criar um público-alvo segmentado por lista de clientes em um anunciante relevante na interface para verificar se os recursos de upload de dados foram aprovados para o parceiro principal do público-alvo proposto. Se o upload de dados não estiver ativado, as tentativas de criar ou atualizar públicos-alvo segmentados por lista de clientes retornarão um erro. Usuários com acesso de nível de parceiro podem solicitar aprovação usando este formulário de solicitação de acesso de parceiros.

Preparar dados do usuário

Os dados do usuário usados para preencher os públicos-alvo segmentados por lista de clientes são confidenciais e precisam ser preparados adequadamente antes do upload.

Gere hash para dados sensíveis

Alguns públicos-alvo segmentados por lista de clientes são criados usando dados de contato confidenciais de clientes. 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 criptografados com hash antes do upload:

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

Os CEPs e os códigos de países não podem ser criptografados com hash antes do upload. A tentativa de fazer upload de dados do cliente sem hash resulta em um erro.

Antes de fazer o hash dos dados, verifique as seguintes condições:

• Todos os espaços em branco precisam ser removidos 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 chamada do país.

Definir o consentimento do usuário

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

Definir 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 do Espaço Econômico Europeu (EEE) para obedecer à Política de consentimento de usuários da União Europeia e usar dados de usuários do EEE para preencher esses públicos-alvo.

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

Criar um público-alvo segmentado por lista de clientes

Para criar um público-alvo segmentado por lista de clientes, use o método firstAndThirdPartyAudiences.create. O público-alvo precisa ser declarado como um público-alvo 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 apropriado no campo de união members.

Observação :o campo membershipDurationDays é obrigatório ao criar públicos-alvo segmentados por lista de clientes. Uma duração de associação ilimitada pode ser ativada configurando o valor do campo como 10.000.

Confira um exemplo de como criar um novo público-alvo segmentado por lista de clientes com dados de contato de duração de associação ilimitada usando uma lista de números de telefone com hash:

Java

// Create Customer Match audience object.
FirstAndThirdPartyAudience customerMatchAudience =
    new FirstAndThirdPartyAudience()
        .setDisplayName(display-name)
        .setFirstAndThirdPartyAudienceType(
            "FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY"
        )
        .setAudienceType("CUSTOMER_MATCH_CONTACT_INFO")
        .setMembershipDurationDays(10000L);

// 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.
FirstAndThirdPartyAudience response =
    service
        .firstAndThirdPartyAudiences()
        .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,
    'firstAndThirdPartyAudienceType':
        'FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY',
    'audienceType': 'CUSTOMER_MATCH_CONTACT_INFO',
    'membershipDurationDays': 10000,
    'contactInfoList': {
        'contactInfos': [
            contact_infos
        ],
        'consent': {
            'adUserData': ad-user-data-consent,
            'adPersonalization': ad-personalization-consent
        }
    }
}

# Build and execute request.
audience = service.firstAndThirdPartyAudiences().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- and third-party audience object.
$audience = new Google_Service_DisplayVideo_FirstAndThirdPartyAudience();
$audience->setDisplayName(display-name);
$audience->setFirstAndThirdPartyAudienceType(
    'FIRST_AND_THIRD_PARTY_AUDIENCE_TYPE_FIRST_PARTY'
);
$audience->setAudienceType('CUSTOMER_MATCH_CONTACT_INFO');
$audience->setMembershipDurationDays(10000);

// 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->firstAndThirdPartyAudiences->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 segmentado por lista de clientes

Se você identificou outros clientes que gostaria de segmentar, precisa renovar as associações de públicos-alvo existentes 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 firstAndThirdPartyAudiences.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 firstAndThirdPartyAudiences.editCustomerMatchMembers só pode adicionar ou remover membros de uma lista. Se uma única solicitação tentar fazer os dois resultados, o erro INVALID_ARGUMENT será gerado.

Observação :é possível atualizar os campos de metadados dos dados de contato e dos públicos-alvo segmentados por lista de clientes do ID do dispositivo, como displayName ou membershipDurationDays, usando o método firstAndThirdPartyAudiences.patch.

Confira um exemplo de como adicionar um único cliente como membro de um público-alvo de Segmentação por lista de clientes de dados de contato usando os dados de endereço de correspondência 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
        .firstAndThirdPartyAudiences()
        .editCustomerMatchMembers(
            audience-id,
            editCustomerMatchMembersRequest
        )
        .execute();

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

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.firstAndThirdPartyAudiences().editCustomerMatchMembers(
    firstAndThirdPartyAudienceId=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["firstAndThirdPartyAudienceId"])

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
    ->firstAndThirdPartyAudiences
    ->editCustomerMatchMembers(
        audience-id,
        $editMemberRequest
    );

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