Zielgruppen zum Kundenabgleich hochladen

Mit der Display & Video 360 API können Sie Zielgruppen für den Kundenabgleich mit hochgeladenen Kundenkontaktdaten oder IDs mobiler Geräte erstellen. Auf dieser Seite wird beschrieben, wie Sie eine erste Zielgruppe zum Kundenabgleich erstellen und der vorhandenen Zielgruppe mithilfe der Display & Video 360 API neue Kundendaten hinzufügen.

Nutzerdaten vorbereiten

Nutzerdaten, die zum Erstellen von Zielgruppen mit Kundenabgleich verwendet werden, sind vertraulich und müssen vor dem Hochladen ordnungsgemäß vorbereitet werden.

Vertrauliche Daten hashen

Einige Zielgruppen für den Kundenabgleich werden mit sensiblen Kundenkontaktdaten erstellt. In Display & Video 360 müssen sensible Daten vor dem Hochladen mit dem SHA256-Algorithmus gehasht werden. Die folgenden Datenfelder müssen vor dem Upload gehasht werden:

  • Vorname
  • Nachname
  • E‑Mail-Adressen
  • Telefonnummern

Postleitzahlen und Ländercodes dürfen vor dem Upload nicht gehasht werden. Der Versuch, nicht gehashte Kundendaten hochzuladen, führt zu einem Fehler.

Achten Sie vor dem Hashing der Daten auf Folgendes:

  • Alle Leerzeichen müssen aus den Werten für den Vornamen, den Nachnamen und die E-Mail-Adresse entfernt werden.
  • Alle Werte müssen in Kleinbuchstaben geschrieben werden.
  • Alle Telefonnummern müssen im E.164-Format formatiert sein und die Ländervorwahl enthalten.

Verwenden Sie beim Hochladen von Nutzerdaten die consent-Felder in den bereitgestellten ContactInfoList- oder MobileDeviceIdList-Objekten, um Signale zur Einwilligung der enthaltenen Nutzer zu übergeben.

Wenn Sie eines der Felder im Consent-Objekt auf CONSENT_STATUS_DENIED festlegen, wird ein Fehler ausgegeben.

Einwilligungssignale werden für alle Nutzer festgelegt, die in einer einzelnen firstAndThirdPartyAudiences.create- oder firstAndThirdPartyAudiences.editCustomerMatchMembers-Anfrage hinzugefügt werden. Nutzer mit unterschiedlichen Einwilligungssignalen müssen in separaten Anfragen hochgeladen werden.

Zielgruppe mit Kundenabgleich erstellen

Eine Zielgruppe mit Kundenabgleich kann mit der Methode firstAndThirdPartyAudiences.create erstellt werden. Die Zielgruppe muss als Zielgruppe mit selbst erhobenen Daten deklariert sein und eine audienceType von CUSTOMER_MATCH_CONTACT_INFO oder CUSTOMER_MATCH_DEVICE_ID haben. Kundenabgleichsdaten müssen über das entsprechende Feld im Union-Feld members bereitgestellt werden.

Hier ein Beispiel für die Erstellung einer neuen Zielgruppe mit Kundenabgleich für Kontaktdaten mit einer Mitgliedschaftsdauer von 540 Tagen anhand einer bereitgestellten Liste mit gehashten Telefonnummern:

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

Mitgliedschaft in einer Zielgruppe mit Kundenabgleich aktualisieren

Wenn Sie weitere Kunden gefunden haben, auf die Sie Ihre Anzeigen ausrichten möchten, die Zugehörigkeit von Kunden zu Zielgruppen erneuern oder Kunden aus einer Zielgruppe entfernen möchten, können Sie die Kundendaten einer vorhandenen Zielgruppe zum Kundenabgleich mit der Methode firstAndThirdPartyAudiences.editCustomerMatchMembers aktualisieren. Mit dem Union-Feld added_members können Sie Kunden einer Liste hinzufügen und mit dem Union-Feld removed_members Kunden aus einer Liste entfernen.

Mit einer einzelnen firstAndThirdPartyAudiences.editCustomerMatchMembers-Anfrage können Mitglieder nur einer Liste hinzugefügt oder daraus entfernt werden. Eine einzelne Anfrage, bei der beides versucht wird, führt zu einem Fehler INVALID_ARGUMENT.

Im folgenden Beispiel wird gezeigt, wie Sie einem vorhandenen Kundenabgleich mit Kontaktdaten einen einzelnen Kunden als Mitglied hinzufügen, indem Sie die angegebenen Postanschriftdaten verwenden:

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