Zielgruppen zum Kundenabgleich hochladen

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

Achtung :Prüfen Sie, ob Ihr Partner die Anforderungen für die Verwendung von Kundenabgleichsdaten-Uploads gemäß unserer Richtlinie erfüllt. Wenn Ihr Partner die Anforderungen nicht erfüllt, wird bei Versuchen, Zielgruppen für den Kundenabgleich zu erstellen oder zu aktualisieren, ein Fehler zurückgegeben.

Nutzerdaten vorbereiten

Nutzerdaten, die zum Erstellen von Kundenabgleichslisten verwendet werden, sind vertraulich und müssen vor dem Hochladen richtig vorbereitet werden.

Sensible Daten hashen

Einige Zielgruppen zum Kundenabgleich werden mit sensiblen Kundenkontaktdaten erstellt. In Display & Video 360 müssen vertrauliche Daten mit dem SHA256-Algorithmus gehasht werden, bevor sie hochgeladen werden. Die folgenden Datenfelder müssen vor dem Hochladen gehasht werden:

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

Postleitzahlen und Ländercodes dürfen vor dem Hochladen nicht gehasht werden. Beim Versuch, nicht gehashte Kundendaten hochzuladen, tritt ein Fehler auf.

Achten Sie vor dem Hashen der Daten auf Folgendes:

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

Nutzereinwilligung festlegen

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

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

Warnung :Wenn Sie Zielgruppenmitglieder für den Kundenabgleich im Europäischen Wirtschaftsraum (EWR) hochladen, müssen Sie Einwilligungssignale senden, um die Richtlinie zur Einwilligung der Nutzer in der EU einzuhalten und EWR-Nutzerdaten zum Erstellen von Kundenabgleichszielgruppen zu verwenden.

Einwilligungssignale werden für alle Nutzer festgelegt, die in einer einzelnen firstPartyAndPartnerAudiences.create- oder firstPartyAndPartnerAudiences.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 firstPartyAndPartnerAudiences.create erstellt werden. Die Zielgruppe muss als Zielgruppe mit selbst erhobenen Daten deklariert werden und einen audienceType von CUSTOMER_MATCH_CONTACT_INFO oder CUSTOMER_MATCH_DEVICE_ID haben. Daten zum Kundenabgleich müssen über das entsprechende Feld im Union-Feld members bereitgestellt werden.

Hinweis: Das Feld membershipDurationDays ist erforderlich, wenn Sie Zielgruppen zum Kundenabgleich erstellen. Einzelne Mitgliedschaften laufen nach Ablauf des Zeitraums ab, wenn sie nicht mit firstPartyAndPartnerAudiences.editCustomerMatchMembers

noch einmal in die Zielgruppe hochgeladen werden.

Hier sehen Sie ein Beispiel dafür, wie Sie eine neue Zielgruppe zum Kundenabgleich mit Kontaktdaten mit einer Gültigkeitsdauer von 540 Tagen erstellen. Dazu verwenden Sie eine Liste mit gehashten Telefonnummern:

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

Mitgliedschaft einer Zielgruppe zum Kundenabgleich aktualisieren

Wenn Sie zusätzliche Kunden ermittelt haben, auf die Sie die Ausrichtung vornehmen möchten, die vorhandenen Zielgruppenmitgliedschaften von Kunden erneuern oder Kunden aus einer Zielgruppe entfernen möchten, können Sie die Kundendaten einer vorhandenen Zielgruppe zum Kundenabgleich mit der Methode firstPartyAndPartnerAudiences.editCustomerMatchMembers aktualisieren. Sie können Kunden einer Liste mit dem Feld added_members hinzufügen und mit dem Feld removed_members aus einer Liste entfernen.

Mit einer einzelnen firstPartyAndPartnerAudiences.editCustomerMatchMembers-Anfrage können nur Mitglieder einer Liste hinzugefügt oder daraus entfernt werden. Wenn Sie versuchen, beides in einer einzigen Anfrage zu tun, wird der Fehler INVALID_ARGUMENT ausgegeben.

Hinweis :Metadatenfelder von Kontaktinformationen und Geräte-ID-Zielgruppen für den Kundenabgleich, z. B. displayName oder membershipDurationDays, können mit der Methode firstPartyAndPartnerAudiences.patch aktualisiert werden.

Hier sehen Sie ein Beispiel dafür, wie Sie einen einzelnen Kunden als Mitglied einer vorhandenen Zielgruppe zum Kundenabgleich mit Kontaktdaten hinzufügen. Dazu werden die angegebenen Daten zur Postanschrift verwendet:

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