Carica segmenti di pubblico Customer Match

Puoi creare segmenti di pubblico Customer Match utilizzando i dati di contatto dei clienti caricati o gli ID dei dispositivi mobili tramite l'API Display & Video 360. Questa pagina descrive come creare un segmento di pubblico Customer Match iniziale e aggiungere nuovi dati dei clienti al segmento di pubblico esistente utilizzando l'API Display & Video 360.

Avviso: verifica che le funzionalità di caricamento dei dati siano state approvate per il partner principale del segmento di pubblico proposto provando prima a creare un segmento di pubblico Customer Match per un inserzionista pertinente nell'interfaccia utente. Se il caricamento dei dati non è stato attivato, i tentativi di creare o aggiornare i segmenti di pubblico Customer Match restituiranno un errore. Gli utenti con accesso a livello di partner possono richiedere l'approvazione utilizzando questo modulo di richiesta di accesso partner.

Preparare i dati utente

I dati utente utilizzati per compilare i segmenti di pubblico Customer Match sono sensibili e devono essere preparati correttamente prima di essere caricati.

Eseguire l'hashing dei dati sensibili

Alcuni segmenti di pubblico Customer Match vengono creati utilizzando informazioni di contatto dei clienti sensibili. Display & Video 360 richiede che i dati sensibili vengano sottoposti ad hashing utilizzando l'algoritmo SHA256 prima di essere caricati. I seguenti campi di dati devono essere sottoposti ad hashing prima del caricamento:

• Nome
• Cognome
• Indirizzi email
• Numeri di telefono

I codici postali e i codici paese non devono essere sottoposti ad hashing prima del caricamento. Il tentativo di caricare dati dei clienti non sottoposti ad hashing genera un errore.

Prima di sottoporre i dati ad hashing, assicurati che siano soddisfatte le seguenti condizioni:

• Eventuali spazi vuoti devono essere rimossi dai valori di nome, cognome e indirizzo email.
• Tutti i valori devono essere in minuscolo.
• Tutti i numeri di telefono devono essere formattati utilizzando il formato E.164 e includere il codice paese.

Impostare il consenso degli utenti

Quando carichi i dati utente, utilizza i campi consent negli oggetti ContactInfoList o MobileDeviceIdList forniti per trasmettere gli indicatori del consenso accordato dagli utenti inclusi.

L'impostazione di uno dei campi dell'oggetto Consent su CONSENT_STATUS_DENIED genera un errore.

Avviso: per rispettare le Norme relative al consenso degli utenti dell'UE, devi inviare indicatori di consenso durante il caricamento dei membri dei segmenti di pubblico Customer Match nello Spazio economico europeo (SEE) e utilizzare i dati utente del SEE per compilare i segmenti di pubblico Customer Match.

Gli indicatori di consenso vengono impostati per tutti gli utenti aggiunti in una singola richiesta firstAndThirdPartyAudiences.create o firstAndThirdPartyAudiences.editCustomerMatchMembers. Gli utenti con indicatori di consenso diversi devono essere caricati in richieste separate.

Creare un segmento di pubblico Customer Match

Un segmento di pubblico Customer Match può essere creato utilizzando il metodo firstAndThirdPartyAudiences.create. Il segmento di pubblico deve essere dichiarato un segmento di pubblico proprietario e deve avere un valore audienceType di CUSTOMER_MATCH_CONTACT_INFO o CUSTOMER_MATCH_DEVICE_ID. I dati di Customer Match devono essere forniti utilizzando il campo appropriato all'interno del campo di unione members.

Nota: il campo membershipDurationDays è obbligatorio per la creazione di segmenti di pubblico Customer Match. I singoli abbonamenti scadranno al termine della durata se non vengono ricaricati nel segmento di pubblico utilizzando firstAndThirdPartyAudiences.editCustomerMatchMembers.

Ecco un esempio di come creare un nuovo segmento di pubblico Customer Match con dati di contatto e una durata dell'appartenenza di 540 giorni utilizzando un elenco fornito di numeri di telefono sottoposti ad hashing:

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(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.
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': 540,
    '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(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->firstAndThirdPartyAudiences->create(
    $audience,
    array('advertiserId' => advertiser-id)
);

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

Aggiornare l'appartenenza a un segmento di pubblico Customer Match

Se hai identificato altri clienti da scegliere come target, devi rinnovare l'appartenenza dei clienti ai segmenti di pubblico esistenti o vuoi rimuovere clienti da un segmento di pubblico, puoi aggiornare i dati dei clienti di un segmento di pubblico Customer Match esistente con il metodo firstAndThirdPartyAudiences.editCustomerMatchMembers. Puoi aggiungere clienti a un elenco utilizzando il campo unione added_members e rimuovere clienti da un elenco con il campo unione removed_members.

Una singola richiesta firstAndThirdPartyAudiences.editCustomerMatchMembers può aggiungere o rimuovere membri da un elenco. Una singola richiesta che tenta di eseguire entrambe le operazioni genera un errore INVALID_ARGUMENT.

Nota: i campi dei metadati dei segmenti di pubblico Customer Match per i dati di contatto e gli ID dispositivo, come displayName o membershipDurationDays, possono essere aggiornati utilizzando il metodo firstAndThirdPartyAudiences.patch.

Di seguito è riportato un esempio di come aggiungere un singolo cliente come membro a un segmento di pubblico Customer Match con dati di contatto esistenti utilizzando i dati dell'indirizzo postale fornito:

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