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 IDs de dispositivos móveis enviados com a API Display & Video 360. Esta página descreve como criar um público-alvo inicial de Segmentação por lista de clientes e adicionar novos dados de clientes ao público-alvo atual usando a API Display & Video 360.

Aviso: verifique se o parceiro atende aos requisitos para usar uploads de dados de Segmentação por lista de clientes, conforme declarado na nossa política. Se o parceiro não atender aos requisitos, as tentativas de criar ou atualizar públicos-alvo por lista de clientes vão retornar um erro.

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 adequadamente antes do upload.

Usar hash em dados sensíveis

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

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

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

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

• 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 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.

Definir qualquer um dos campos no objeto Consent como CONSENT_STATUS_DENIED resulta em um erro.

Aviso: você precisa enviar indicadores de consentimento ao fazer 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 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 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 por lista de clientes

É possível criar um público-alvo 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 apropriado 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 associações individuais vão expirar após o período se não forem enviadas novamente ao público-alvo usando firstPartyAndPartnerAudiences.editCustomerMatchMembers.

Confira um exemplo de como criar um público-alvo por lista de clientes de informações de contato com uma duração de associação de 540 dias usando uma lista fornecida 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 quer segmentar, precisa renovar as associações de público-alvo atuais ou quer remover clientes de um público-alvo, atualize os dados de clientes de um público-alvo segmentado por lista de clientes usando 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 as duas coisas resulta em um erro INVALID_ARGUMENT.

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

Confira um exemplo de como adicionar um único cliente como membro a um público-alvo segmentado por lista de clientes com informações 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
        .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']
);