Prześlij listy odbiorców z kierowania na listę klientów

Listy odbiorców z kierowania na listę klientów możesz tworzyć na podstawie przesłanych informacji kontaktowych klientów lub identyfikatorów urządzeń mobilnych za pomocą interfejsu Display & Video 360 API. Z tego artykułu dowiesz się, jak za pomocą interfejsu Display & Video 360 API utworzyć początkową listę odbiorców z kierowania na listę klientów i dołączyć do niej nowe dane o klientach.

Ostrzeżenie: najpierw spróbuj utworzyć w interfejsie grupę odbiorców z kierowania na listę klientów dla odpowiedniego reklamodawcy, aby sprawdzić, czy funkcje przesyłania danych zostały zatwierdzone dla nadrzędnego partnera proponowanej grupy odbiorców. Jeśli przesyłanie danych nie jest włączone, próba utworzenia lub zaktualizowania odbiorców z kierowania na listę klientów spowoduje wyświetlenie błędu. Użytkownicy z dostępem na poziomie partnera mogą poprosić o zatwierdzenie, korzystając z tego formularza prośby o dostęp dla partnerów.

Przygotowywanie danych użytkowników

Dane użytkownika używane do wypełniania list odbiorców z kierowania na listę klientów są poufne i trzeba je odpowiednio przygotować przed przesłaniem.

Haszowanie danych wrażliwych

Niektóre grupy odbiorców z kierowania na listę klientów są tworzone z wykorzystaniem poufnych danych kontaktowych klientów. Display & Video 360 wymaga szyfrowania danych wrażliwych przed ich przesłaniem za pomocą algorytmu SHA256. Przed przesłaniem należy zaszyfrować te pola danych:

• Imię
• Nazwisko
• Adresy e-mail
• Numery telefonów

Kodów pocztowych i krajów nie należy szyfrować przed przesłaniem. Próba przesłania niezaszyfrowanych danych klientów kończy się błędem.

Przed zaszyfrowaniem danych upewnij się, że spełnione są te warunki:

• Z wartości imienia, nazwiska i adresu e-mail należy usunąć wszelkie odstępy.
• Wszystkie wartości muszą być zapisane małymi literami.
• Wszystkie numery telefonów muszą być sformatowane w formacie E.164 i zawierać kod kraju.

Konfigurowanie zgody użytkownika

Podczas przesyłania danych użytkownika używaj pól consent w dostarczonych obiektach ContactInfoList lub MobileDeviceIdList, aby przekazywać sygnały zgody udzielonej przez uwzględnionych użytkowników.

Ustawienie w jednym z tych pól w obiekcie Consent wartości CONSENT_STATUS_DENIED powoduje błąd.

Ostrzeżenie: przesyłając listę odbiorców z Europejskiego Obszaru Gospodarczego (EOG), musisz wysyłać sygnały dotyczące zgody użytkownika, aby zachować zgodność z polityką w zakresie zgody użytkownika z UE, oraz używać danych użytkowników z EOG do wypełniania list odbiorców z kierowania na listę klientów.

Sygnały dotyczące zgody są stosowane dla wszystkich użytkowników dodanych w jednym żądaniu firstAndThirdPartyAudiences.create lub firstAndThirdPartyAudiences.editCustomerMatchMembers. Użytkowników z różnymi sygnałami zgody należy przesyłać w osobnych żądaniach.

Tworzenie listy odbiorców z kierowania na listę klientów

Listę odbiorców z kierowania na listę klientów można utworzyć, korzystając z metody firstAndThirdPartyAudiences.create. Lista odbiorców musi być zadeklarowana jako własną listę odbiorców i musi zawierać w polu audienceType wartość CUSTOMER_MATCH_CONTACT_INFO lub CUSTOMER_MATCH_DEVICE_ID. Dane kierowania na listę klientów należy podać za pomocą odpowiedniego pola w polu „members”.

Uwaga: pole membershipDurationDays jest wymagane podczas tworzenia odbiorców z kierowania na listę klientów. Ustawienie nieograniczonego okresu członkostwa można włączyć, ustawiając wartość pola na 10 000.

Oto przykład tworzenia nowej listy odbiorców z danymi kontaktowymi kierowania na listę klientów z nieograniczonym okresem członkostwa za pomocą podanej listy zaszyfrowanych numerów telefonów:

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

Aktualizowanie członkostwa na liście odbiorców z kierowania na listę klientów

Jeśli masz nowych klientów, na których chcesz kierować reklamy, chcesz odnowić członkostwo na liście odbiorców klientów lub chcesz ich usunąć z listy odbiorców, możesz zaktualizować dane dotychczasowej listy odbiorców z kierowania na listę klientów za pomocą metody firstAndThirdPartyAudiences.editCustomerMatchMembers. Klientów możesz dodawać do listy, korzystając z pola „added_members”, a klientów z listy – usuwać za pomocą pola removed_members.

W ramach pojedynczego żądania firstAndThirdPartyAudiences.editCustomerMatchMembers można tylko dodawać użytkowników do listy i ich z niej usuwać. Wykonanie obu żądań spowoduje wystąpienie błędu INVALID_ARGUMENT.

Uwaga: pola metadanych z danymi kontaktowymi i identyfikatorami urządzeń z kierowania na listę klientów, np. displayName czy membershipDurationDays, można aktualizować, korzystając z metody firstAndThirdPartyAudiences.patch.

Oto przykład, jak dodać jednego klienta jako członka dotychczasowych informacji kontaktowych odbiorców kierowania na listę klientów za pomocą podanych adresów pocztowych:

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