Zielgruppen zum Kundenabgleich hochladen

Mithilfe der Display & Video 360 API können Sie Zielgruppen zum Kundenabgleich anhand hochgeladener Kontaktdaten oder von Mobilgeräte-IDs erstellen. Auf dieser Seite wird beschrieben, wie Sie mithilfe der Display & Video 360 API eine erste Zielgruppe zum Kundenabgleich erstellen und der vorhandenen Zielgruppe neue Kundendaten hinzufügen.

Warnung :Prüfen Sie, ob Funktionen zum Hochladen von Daten für den übergeordneten Partner der vorgeschlagenen Zielgruppe genehmigt wurden. Erstellen Sie dazu zuerst auf der Benutzeroberfläche unter einem relevanten Werbetreibenden eine Zielgruppe zum Kundenabgleich. Wenn der Datenupload nicht aktiviert ist, wird beim Versuch, Zielgruppen zum Kundenabgleich zu erstellen oder zu aktualisieren, ein Fehler zurückgegeben. Nutzer mit Zugriff auf Partnerebene können über dieses Antragsformular für den Partnerzugriff eine Genehmigung anfordern.

Nutzerdaten vorbereiten

Nutzerdaten, die zum Ausfüllen von Zielgruppen zum Kundenabgleich verwendet werden, sind sensibel und müssen vor dem Hochladen entsprechend vorbereitet werden.

Sensible Daten hashen

Einige Zielgruppen zum Kundenabgleich werden mit vertraulichen 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.

Prüfen Sie vor dem Hashen der Daten, ob die folgenden Bedingungen erfüllt sind:

• Alle Leerzeichen müssen aus den Werten für Vor-, Nachname und 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 Landesvorwahl enthalten.

Nutzereinwilligung festlegen

Verwenden Sie beim Hochladen von Nutzerdaten die consent-Felder im bereitgestellten ContactInfoList- oder MobileDeviceIdList-Objekt, um die Einwilligungssignale der enthaltenen Nutzer zu übergeben.

Wenn eines der Felder im Objekt Consent auf CONSENT_STATUS_DENIED festgelegt wird, wird ein Fehler ausgegeben.

Warnung :Sie müssen Einwilligungssignale senden, wenn Sie Zielgruppen zum Kundenabgleich im Europäischen Wirtschaftsraum (EWR) hochladen, um die Richtlinie zur Einwilligung der Nutzer in der EU einzuhalten und Zielgruppen aus dem EWR anhand von Nutzerdaten zum Kundenabgleich zu füllen.

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 zum Kundenabgleich erstellen

Eine Zielgruppe zum Kundenabgleich kann mit der Methode firstAndThirdPartyAudiences.create erstellt werden. Die Zielgruppe muss als Zielgruppe mit selbst erhobenen Daten deklariert sein und für audienceType den Wert CUSTOMER_MATCH_CONTACT_INFO oder CUSTOMER_MATCH_DEVICE_ID haben. Daten zum Kundenabgleich müssen über das entsprechende Feld im Union-Feld members angegeben werden.

Hinweis :Beim Erstellen von Zielgruppen zum Kundenabgleich ist das Feld membershipDurationDays erforderlich. Eine unbegrenzte Gültigkeitsdauer kann durch Setzen des Feldwerts auf 10.000 aktiviert werden.

Das folgende Beispiel zeigt, wie Sie mithilfe einer bereitgestellten Liste gehashter Telefonnummern eine neue Zielgruppe für den Kundenabgleich mit unbegrenzter Gültigkeitsdauer erstellen:

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

Mitgliedschaft einer Zielgruppe zum Kundenabgleich aktualisieren

Wenn Sie zusätzliche Kunden für die Ausrichtung ermittelt haben, die bestehenden Zielgruppenmitgliedschaften von Kunden verlängern oder Kunden aus einer Zielgruppe entfernen möchten, können Sie die Kundendaten einer vorhandenen Zielgruppe zum Kundenabgleich mit der Methode firstAndThirdPartyAudiences.editCustomerMatchMembers aktualisieren. Sie können Kunden mit dem Union-Feld added_members in eine Liste aufnehmen und mit dem Union-Feld removed_members aus einer Liste entfernen.

Mit einer einzigen firstAndThirdPartyAudiences.editCustomerMatchMembers-Anfrage können nur Mitglieder einer Liste hinzugefügt oder daraus entfernt werden. Wenn eine Anfrage beides erfüllt, wird der Fehler INVALID_ARGUMENT ausgegeben.

Hinweis: Metadatenfelder mit Kontaktdaten und Zielgruppen für den Kundenabgleich mit Geräte-IDs wie displayName oder membershipDurationDays können mit der Methode firstAndThirdPartyAudiences.patch aktualisiert werden.

Hier ein Beispiel, wie Sie einen einzelnen Kunden als Mitglied einer vorhandenen Zielgruppe für den Kundenabgleich mit Kontaktdaten hinzufügen, indem Sie die angegebenen Adressdaten 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']
);