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

Za pomocą interfejsu Display & Video 360 API możesz tworzyć listy odbiorców z kierowania na listę klientów, używając przesłanych danych kontaktowych klientów lub identyfikatorów urządzeń mobilnych. Na tej stronie znajdziesz informacje o tym, jak utworzyć początkową listę odbiorców z kierowania na listę klientów i dodać do niej nowe dane klientów za pomocą interfejsu Display & Video 360 API.

Ostrzeżenie: sprawdź, czy Twój partner spełnia wymagania dotyczące korzystania z przesyłania danych na potrzeby kierowania na listę klientów, które są określone w naszych zasadach. Jeśli partner nie spełnia wymagań, próby utworzenia lub zaktualizowania list klientów zwrócą błąd.

Przygotowywanie danych użytkowników

Dane użytkowników używane do wypełniania list odbiorców kierowania na listę klientów są danymi wrażliwymi i przed przesłaniem należy je odpowiednio przygotować.

Haszowanie danych wrażliwych

Niektóre listy odbiorców z kierowania na listę klientów są tworzone na podstawie informacji kontaktowych klientów, które mają charakter poufny. Display & Video 360 wymaga, aby przed przesłaniem dane wrażliwe były szyfrowane przy użyciu algorytmu SHA256. Przed przesłaniem musisz zaszyfrować te pola danych:

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

Kodów pocztowych i kodów krajów nie należy szyfrować przed przesłaniem. Próba przesłania niezaszyfrowanych danych klientów powoduje błąd.

Przed zaszyfrowaniem danych sprawdź, czy spełnione są te warunki:

• Wartości imienia, nazwiska i adresu e-mail nie mogą zawierać spacji.
• Wszystkie wartości muszą być zapisane małymi literami.
• Wszystkie numery telefonów muszą być sformatowane zgodnie z formatem E.164 i zawierać kod kraju.

Ustawianie zgody użytkownika

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

Ustawienie dowolnego pola w obiekcie Consent na wartość CONSENT_STATUS_DENIED powoduje błąd.

Ostrzeżenie: podczas przesyłania danych o użytkownikach z Europejskiego Obszaru Gospodarczego (EOG) należących do odbiorców kierowanych na listę klientów musisz wysyłać sygnały dotyczące zgody, aby zachować zgodność z polityką w zakresie zgody użytkownika z UE i używać danych użytkowników z EOG do wypełniania list odbiorców kierowanych na listę klientów.

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

Tworzenie listy odbiorców na podstawie informacji o klientach

Listę odbiorców kierowania na listę klientów można utworzyć za pomocą metody firstPartyAndPartnerAudiences.create. Lista odbiorców musi być zadeklarowana jako własna lista odbiorców i musi mieć audienceType CUSTOMER_MATCH_CONTACT_INFO lub CUSTOMER_MATCH_DEVICE_ID. Dane kierowania na listę klientów muszą być podawane w odpowiednim polu w polu unii members.

Uwaga: pole membershipDurationDays jest wymagane podczas tworzenia list odbiorców kierowania na listę klientów. Członkostwo indywidualne wygaśnie po upływie okresu ważności, jeśli nie zostanie ponownie przesłane na listę odbiorców za pomocą funkcji firstPartyAndPartnerAudiences.editCustomerMatchMembers.

Oto przykład tworzenia nowej listy odbiorców z kierowania na listę klientów na podstawie danych kontaktowych z okresem członkostwa wynoszącym 540 dni przy użyciu podanej listy zaszyfrowanych numerów telefonów:

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

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

Jeśli udało Ci się zidentyfikować dodatkowych klientów, do których chcesz kierować reklamy, musisz odnowić istniejące członkostwo klientów w grupach odbiorców lub chcesz usunąć klientów z grupy odbiorców, możesz zaktualizować dane klientów w istniejącej grupie odbiorców kierowania na listę klientów za pomocą metody firstPartyAndPartnerAudiences.editCustomerMatchMembers. Klientów możesz dodawać do listy za pomocą pola unii added_members, a usuwać ich z listy za pomocą pola unii removed_members.

Pojedyncza firstPartyAndPartnerAudiences.editCustomerMatchMembers prośba może tylko dodawać lub usuwać członków z listy. Pojedyncze żądanie, które próbuje wykonać obie te czynności, powoduje błąd INVALID_ARGUMENT.

Uwaga: pola metadanych informacji kontaktowych i identyfikatora urządzenia na listach klientów na potrzeby kierowania na listę klientów, takie jak displayName lub membershipDurationDays, można aktualizować za pomocą metody firstPartyAndPartnerAudiences.patch.

Oto przykład dodawania pojedynczego klienta jako członka do istniejącej listy odbiorców kierowania na listę klientów na podstawie podanych danych adresowych:

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