Mit dem Kundenabgleich können Sie Ihre Online- und Offlinedaten nutzen, um Kaufinteressierte in der Google Suche, auf dem Shopping-Tab, in Gmail, auf YouTube und im Displaynetzwerk zu erreichen und noch einmal anzusprechen. Dabei werden die von Ihren Kunden für Sie freigegebenen Daten verwendet, um Anzeigen auf diese und ähnliche Kunden auszurichten. Sie können CRM-Daten (Customer-Relationship-Management) im Bulk hochladen, Daten anhängen oder entfernen oder diese Nutzerlisten verwenden, um eine logical_user_list zu erstellen.
In der Übersicht zur Zielgruppenverwaltung finden Sie eine Liste der verschiedenen Typen von Zielgruppensegmenten, mit denen Sie den Kundenabgleich mit anderen Optionen für Nutzerlisten vergleichen können.
Weitere Informationen zum Kundenabgleich und zur Ausrichtung auf Zielgruppen
Voraussetzungen
Der Kundenabgleich kann nicht für jedes Konto genutzt werden. Damit Sie den Kundenabgleich nutzen können, muss Ihr Konto folgende Voraussetzungen erfüllen:
- Es gab keine Verstöße gegen unsere Richtlinien.
- Es gab keine Probleme mit Zahlungen.
Je nachdem, welche Anforderungen Ihr Konto erfüllt, stehen unterschiedliche Funktionen zur Verfügung. Weitere Informationen zu den Voraussetzungen und Einschränkungen finden Sie in der Richtlinie zum Kundenabgleich.
Integration entwerfen
Nutzungsablauf
Der folgende Ablauf wird für die Erstellung und Ausrichtung einer Kundenliste empfohlen:
Erstellen Sie eine leere Kundenliste.
Erstellen Sie ein
OfflineUserDataJob. Ein einzelner großer Job ist wesentlich effizienter als mehrere kleinere Jobs.Ab Version 15 der Google Ads API muss das Feld
consentvoncustomer_match_user_list_metadatain IhrenOfflineUserDataJobcreate-Anfragen ausgefüllt werden. Fürremove-Anfragen ist keine Einwilligung erforderlich. Die API gibtOfflineUserDataJobError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMSzurück, wennconsent.ad_user_dataoderconsent.ad_personalizationdes Jobs aufDENIEDfestgelegt sind. Wenn für eine Kennung die EinwilligungDENIEDvorliegt, können Sie einen Job erstellen, um die Kennung aus der Nutzerliste zu entfernen.Fügen Sie Vorgänge mit der Methode
OfflineUserDataJobService.AddOfflineUserDataJobOperationshinzu. Für eine optimale Verarbeitung empfehlen wir,bis zu 10.000 IDs in einem einzigen Aufruf hinzuzufügen. Eine einzelneAddOfflineUserDataJobOperations-Anfrage kann für alleUserData-Objekte in der Vorgangsliste maximal 100.000 IDs enthalten.Wenn beispielsweise jedes Ihrer
UserData-Objekte eineUserIdentifierfürhashed_emailund eine weitereUserIdentifierfürhashed_phone_numberhat, ist das Senden von 5.000UserData-Objekten pro Anfrage optimal, da jede Anfrage insgesamt 10.000 Nutzerkennungen enthält.Wiederholen Sie den vorherigen Schritt, bis alle Vorgänge hinzugefügt wurden oder der Job ausgelastet ist. Die Anzahl der Vorgänge, die Sie einem einzelnen Job hinzufügen können, ist nicht begrenzt. Für eine optimale Verarbeitung empfehlen wir jedoch nicht mehr als 1.000.000 Vorgänge pro Job.
Führen Sie den Job aus.
Fragen Sie nach, ob der Upload erfolgreich war.
Prüfen Sie die Abgleichsrate.
Nehmen Sie ein Targeting auf die Liste vor.
OfflineUserDataJobService und UserDataService
Es gibt zwei Dienste, um Daten zum Kundenabgleich hochzuladen. Wählen Sie den Dienst entsprechend Ihrem Anwendungsfall aus, da er Einschränkungen unterliegen kann.
| Uploaddienste für den Kundenabgleich | |
|---|---|
OfflineUserDataJobService (bevorzugt)
|
Die meisten Entwickler verwenden diesen Dienst. Es ist für große Uploads mit hohem Durchsatz optimiert und gibt nach Abschluss Erfolgsmesswerte zurück. Der Schwerpunkt dieses Leitfadens liegt hauptsächlich auf diesem Dienst. |
UserDataService
|
Dieser Dienst ist so optimiert, dass nur eine kleine Anzahl von Kennungen gleichzeitig mit sporadischen Aktualisierungen hochgeladen werden kann. Er ist nicht für eine kontinuierliche Ausführung optimiert. Pro Anfrage sind maximal 10 Vorgänge zulässig. Außerdem darf eine Anfrage in allen user_identifiers insgesamt maximal 100 Elemente enthalten.
Informationen zu Uploads mit diesem Dienst finden Sie im Leitfaden zur Einbindung des Kundenabgleichs. Ab Version 15 der Google Ads API muss das Feld |
Best Practices
Beachten Sie beim Entwerfen der Integration für den Kundenabgleich die folgenden Best Practices:
Versuchen Sie nicht, mehrere Konten zu verwenden, um eine einzelne Nutzerliste zu ändern. Eine Nutzerliste kann nur von dem Google Ads- oder Datenpartnerkonto geändert werden, mit dem sie erstellt wurde.
Maximieren Sie die Anzahl der Vorgänge pro
AddOfflineUserDataJobOperationsRequest(bis zu 10.000 IDs), umRESOURCE_EXHAUSTED-Fehler zu vermeiden.Mischen Sie
create- undremove-Vorgänge nicht innerhalb desselbenOfflineUserDataJob. Dies kann zum FehlerCONFLICTING_OPERATIONführen.Aktivieren Sie
partial_failurein einerAddOfflineUserDataJobOperationsRequest, um problematische Vorgänge vor dem Ausführen des Jobs zu erkennen. Vorgänge werden beim Hochladen in einOfflineUserDataJobvalidiert.Vermeiden Sie gleichzeitig die gleichzeitige Ausführung mehrerer
OfflineUserDataJob-Prozesse, die dieselbe Nutzerliste ändern (d. h. mehrere Jobs, derenCustomerMatchUserListMetadata.user_listauf denselben Ressourcennamen verweist). Dies kann zum FehlerCONCURRENT_MODIFICATIONführen, da nicht mehrere Jobs gleichzeitig für dieselbe Liste ausgeführt werden dürfen. Dieser Fehler kann auch auftreten, wenn Sie versuchen, eine Liste gleichzeitig über die Google Ads-Benutzeroberfläche und die Google Ads API zu ändern. Dies gilt nicht für das Hinzufügen von Vorgängen zu einemPENDING-Job, was jederzeit vor dem Start des Jobs ausgeführt werden kann.Wenn Tausende von Vorgängen angewendet werden sollen, erstellen Sie eine
OfflineUserDataJobmit allen Vorgängen. Erstellen Sie nicht mehrere Jobs mit jeweils nur ein paar hundert Vorgängen und führen Sie diese nacheinander oder gleichzeitig aus. Ein einzelner großer Job mit allen Vorgängen ist wesentlich effizienter als mehrere kleine Jobs und verringert die Wahrscheinlichkeit, dass Fehler im Workflow auftreten.
Informationen zur optimalen Nutzung Ihrer Kundenlisten für eine optimale Ausrichtung finden Sie in der Google Ads-Hilfe.
Kundenliste erstellen
Erstellen Sie zuerst eine Kundenliste mit UserListService. Kundenlisten werden durch Festlegen des Felds crm_based_user_list im Objekt user_list erstellt. Das Feld crm_based_user_list kann für Kampagnentypen festgelegt werden, bei denen die Ausrichtung auf Kundenlisten unterstützt wird:
| Kundenabgleich bei verschiedenen Kampagnentypen | |
|---|---|
| Suchnetzwerk | Anzeigen werden im Suchnetzwerk ausgeliefert. |
| Displaynetzwerk | Anzeigen werden im Displaynetzwerk und in Gmail nur dann ausgeliefert, wenn GSP-Creatives vorhanden sind. |
| Displaynetzwerk-Aktivierung in Suchkampagnen | Anzeigen werden im Suchnetzwerk und in Gmail nur dann ausgeliefert, wenn GSP-Creatives vorhanden sind. |
| Videokampagnen | Anzeigen werden auf YouTube nur ausgeliefert, wenn es In-Stream-TrueView-Anzeigen gibt. |
| Shopping-Kampagnen | Anzeigen werden auf dem Shopping-Tab präsentiert. |
crm_based_user_list enthält drei Felder:
app_id: Ein String, der die mobile App, von der die Daten erfasst wurden, eindeutig identifiziert. Das ist erforderlich, wenn duCrmBasedUserListzum Hochladen mobiler Werbe-IDs erstellst.upload_key_type: Ein übereinstimmender Schlüsseltyp der Liste, entwederCONTACT_INFO,CRM_IDoderMOBILE_ADVERTISING_ID. Gemischte Datentypen sind in derselben Liste nicht zulässig. Dieses Feld ist für alle Kundenlisten erforderlich.data_source_type: Die Datenquelle der Liste. Der Standardwert istFIRST_PARTY. Kunden, die auf der Zulassungsliste stehen, können Kundenlisten von Drittanbietern erstellen.
Mit dem Attribut membership_life_span der Nutzerliste können Sie den Zeitraum in Tagen definieren, für den ein Nutzer in der Liste enthalten ist. Sie können für Kundenlistentypen membership_life_span auf 10.000 setzen, um anzuzeigen, dass sie nicht ablaufen.
Das Attribut membership_status definiert, ob neue Nutzer in die Liste aufgenommen werden können.
Codebeispiel zum Erstellen einer Kundenliste
Java
private String createCustomerMatchUserList(GoogleAdsClient googleAdsClient, long customerId) {
// Creates the new user list.
UserList userList =
UserList.newBuilder()
.setName("Customer Match list #" + getPrintableDateTime())
.setDescription("A list of customers that originated from email addresses")
// Customer Match user lists can use a membership life span of 10,000 to indicate
// unlimited; otherwise normal values apply.
// Sets the membership life span to 30 days.
.setMembershipLifeSpan(30)
// Sets the upload key type to indicate the type of identifier that will be used to
// add users to the list. This field is immutable and required for a CREATE operation.
.setCrmBasedUserList(
CrmBasedUserListInfo.newBuilder()
.setUploadKeyType(CustomerMatchUploadKeyType.CONTACT_INFO))
.build();
// Creates the operation.
UserListOperation operation = UserListOperation.newBuilder().setCreate(userList).build();
// Creates the service client.
try (UserListServiceClient userListServiceClient =
googleAdsClient.getLatestVersion().createUserListServiceClient()) {
// Adds the user list.
MutateUserListsResponse response =
userListServiceClient.mutateUserLists(
Long.toString(customerId), ImmutableList.of(operation));
// Prints the response.
System.out.printf(
"Created Customer Match user list with resource name: %s.%n",
response.getResults(0).getResourceName());
return response.getResults(0).getResourceName();
}
}
C#
private string CreateCustomerMatchUserList(GoogleAdsClient client, long customerId)
{
// Get the UserListService.
UserListServiceClient service = client.GetService(Services.V16.UserListService);
// Creates the user list.
UserList userList = new UserList()
{
Name = $"Customer Match list# {ExampleUtilities.GetShortRandomString()}",
Description = "A list of customers that originated from email and physical" +
" addresses",
// Customer Match user lists can use a membership life span of 10000 to
// indicate unlimited; otherwise normal values apply.
// Sets the membership life span to 30 days.
MembershipLifeSpan = 30,
CrmBasedUserList = new CrmBasedUserListInfo()
{
UploadKeyType = CustomerMatchUploadKeyType.ContactInfo
}
};
// Creates the user list operation.
UserListOperation operation = new UserListOperation()
{
Create = userList
};
// Issues a mutate request to add the user list and prints some information.
MutateUserListsResponse response = service.MutateUserLists(
customerId.ToString(), new[] { operation });
string userListResourceName = response.Results[0].ResourceName;
Console.WriteLine($"User list with resource name '{userListResourceName}' " +
$"was created.");
return userListResourceName;
}
PHP
private static function createCustomerMatchUserList(
GoogleAdsClient $googleAdsClient,
int $customerId
): string {
// Creates the user list.
$userList = new UserList([
'name' => 'Customer Match list #' . Helper::getPrintableDatetime(),
'description' => 'A list of customers that originated from email '
. 'and physical addresses',
// Customer Match user lists can use a membership life span of 10000 to
// indicate unlimited; otherwise normal values apply.
// Sets the membership life span to 30 days.
'membership_life_span' => 30,
'crm_based_user_list' => new CrmBasedUserListInfo([
// Sets the upload key type to indicate the type of identifier that will be used to
// add users to the list. This field is immutable and required for a CREATE
// operation.
'upload_key_type' => CustomerMatchUploadKeyType::CONTACT_INFO
])
]);
// Creates the user list operation.
$operation = new UserListOperation();
$operation->setCreate($userList);
// Issues a mutate request to add the user list and prints some information.
$userListServiceClient = $googleAdsClient->getUserListServiceClient();
$response = $userListServiceClient->mutateUserLists(
MutateUserListsRequest::build($customerId, [$operation])
);
$userListResourceName = $response->getResults()[0]->getResourceName();
printf("User list with resource name '%s' was created.%s", $userListResourceName, PHP_EOL);
return $userListResourceName;
}
Python
def create_customer_match_user_list(client, customer_id):
"""Creates a Customer Match user list.
Args:
client: The Google Ads client.
customer_id: The ID for the customer that owns the user list.
Returns:
The string resource name of the newly created user list.
"""
# Creates the UserListService client.
user_list_service_client = client.get_service("UserListService")
# Creates the user list operation.
user_list_operation = client.get_type("UserListOperation")
# Creates the new user list.
user_list = user_list_operation.create
user_list.name = f"Customer Match list #{uuid.uuid4()}"
user_list.description = (
"A list of customers that originated from email and physical addresses"
)
# Sets the upload key type to indicate the type of identifier that is used
# to add users to the list. This field is immutable and required for a
# CREATE operation.
user_list.crm_based_user_list.upload_key_type = (
client.enums.CustomerMatchUploadKeyTypeEnum.CONTACT_INFO
)
# Customer Match user lists can set an unlimited membership life span;
# to do so, use the special life span value 10000. Otherwise, membership
# life span must be between 0 and 540 days inclusive. See:
# https://developers.devsite.corp.google.com/google-ads/api/reference/rpc/latest/UserList#membership_life_span
# Sets the membership life span to 30 days.
user_list.membership_life_span = 30
response = user_list_service_client.mutate_user_lists(
customer_id=customer_id, operations=[user_list_operation]
)
user_list_resource_name = response.results[0].resource_name
print(
f"User list with resource name '{user_list_resource_name}' was created."
)
return user_list_resource_name
Ruby
def create_customer_match_user_list(client, customer_id)
# Creates the user list.
operation = client.operation.create_resource.user_list do |ul|
ul.name = "Customer Match List #{(Time.new.to_f * 1000).to_i}"
ul.description = "A list of customers that originated from email and " \
"physical addresses"
# Customer Match user lists can use a membership life span of 10000 to
# indicate unlimited; otherwise normal values apply.
# Sets the membership life span to 30 days.
ul.membership_life_span = 30
ul.crm_based_user_list = client.resource.crm_based_user_list_info do |crm|
crm.upload_key_type = :CONTACT_INFO
end
end
# Issues a mutate request to add the user list and prints some information.
response = client.service.user_list.mutate_user_lists(
customer_id: customer_id,
operations: [operation],
)
# Prints out some information about the newly created user list.
resource_name = response.results.first.resource_name
puts "User list with resource name #{resource_name} was created."
resource_name
end
Perl
sub create_customer_match_user_list {
my ($api_client, $customer_id) = @_;
# Create the user list.
my $user_list = Google::Ads::GoogleAds::V16::Resources::UserList->new({
name => "Customer Match list #" . uniqid(),
description =>
"A list of customers that originated from email and physical addresses",
# Customer Match user lists can use a membership life span of 10000 to
# indicate unlimited; otherwise normal values apply.
# Set the membership life span to 30 days.
membershipLifeSpan => 30,
# Set the upload key type to indicate the type of identifier that will be
# used to add users to the list. This field is immutable and required for
# a CREATE operation.
crmBasedUserList =>
Google::Ads::GoogleAds::V16::Common::CrmBasedUserListInfo->new({
uploadKeyType => CONTACT_INFO
})});
# Create the user list operation.
my $user_list_operation =
Google::Ads::GoogleAds::V16::Services::UserListService::UserListOperation->
new({
create => $user_list
});
# Issue a mutate request to add the user list and print some information.
my $user_lists_response = $api_client->UserListService()->mutate({
customerId => $customer_id,
operations => [$user_list_operation]});
my $user_list_resource_name =
$user_lists_response->{results}[0]{resourceName};
printf "User list with resource name '%s' was created.\n",
$user_list_resource_name;
return $user_list_resource_name;
}
Kundendaten hinzufügen
Die drei primären Abgleichsschlüssel sind E-Mail-Adresse, Postanschrift und Telefonnummer. Sie können User-ID und Mobilgeräte-ID als Abgleichsschlüssel verwenden. Diese Lösungen sind jedoch weniger zukunftssicher, da sie auf Cookies und Geräte-IDs angewiesen sind. Wir empfehlen, nach Möglichkeit anstelle von CRM- oder Mobil-IDs Nutzerkontaktdaten wie E-Mail-Adresse, Postanschrift und Telefonnummer hochzuladen.
Jede Nutzerliste darf nur einen einzigen Kundendatentyp enthalten, wie im Feld CrmBasedUserListInfo.upload_key_type angegeben. Darüber hinaus kann ein UserData-Objekt, das einen einzelnen Nutzer repräsentiert, bis zu 20 Nutzerkennungen enthalten, von denen jede ein eigenes UserIdentifier-Objekt hat. Mehr als 20 Kennungen führen zum Fehler TOO_MANY_USER_IDENTIFIERS.
In Google Ads wird eine Nutzerliste zum Kundenabgleich nur dann für die Ausrichtung verwendet, wenn zum Zeitpunkt der Anzeigenauslieferung eine Mindestanzahl von aktiven Nutzern erreicht wurde. „Aktive Nutzer“ entspricht der Anzahl der Nutzer auf Ihrer Liste, die in Gmail, in der Google Suche, auf YouTube oder im Displaynetzwerk aktiv sind. Laden Sie mindestens 5.000 Mitglieder hoch, um die Wahrscheinlichkeit zu erhöhen, dass genügend übereinstimmende, aktive Nutzer für das Targeting vorhanden sind.
Kontaktdaten des Nutzers hochladen
Wenn Sie E-Mail-Adressen, Postanschriften oder Telefonnummern von Nutzern hochladen möchten, setzen Sie upload_key_type auf CONTACT_INFO. Beachten Sie, dass Kontaktdaten mit einem Google-Konto verknüpft sein müssen, damit sie abgeglichen werden können. Außerdem ist eine Ausrichtung auf Unternehmenskonten wie Google Workspace nicht möglich.
Aus Datenschutzgründen müssen E-Mail-Adressen, Vornamen, Nachnamen und Telefonnummern vor dem Hochladen mit dem SHA-256-Algorithmus gehasht werden. Damit die Hash-Ergebnisse standardisiert werden können, müssen Sie vor dem Hashen eines dieser Werte die folgenden Aufgaben ausführen:
- Entfernen Sie Leerzeichen am Anfang und Ende.
- Für Namen, E-Mail-Adressen und Postanschriften: Text in Kleinbuchstaben umwandeln
- Telefonnummern: Konvertieren Sie jede Telefonnummer in das E164-Format, bevor Sie sie hashen. Dieses Format stellt eine Telefonnummer als bis zu 15-stellige Zahl dar, die mit einem
+-Zeichen beginnt, z. B.+12125650000oder+442070313000. Das vorangestellte+-Zeichen kann optional weggelassen werden.
Bei E-Mail-Adressen müssen Sie nicht alle Punkte (.) vor dem Domainnamen in E-Mail-Adressen vom Typ gmail.com und googlemail.com entfernen, da diese weiterhin akzeptiert werden.
Wenn die Kontaktdaten vor dem Hashen nicht richtig formatiert sind, akzeptiert die API die gehashten Informationen zwar, sie können aber keinem Kunden zugeordnet werden.
Wenn Sie Daten zu Postanschriften hochladen möchten, müssen Sie mindestens Folgendes angeben:
- Ländercode
- Postleitzahl
- Gehashter Vorname
- Gehashter Nachname
Wenn eines dieser Felder fehlt, kann die Adresse nicht abgeglichen werden.
Kundenlisten dürfen nur eine upload_key_type enthalten, für eine upload_key_type mit CONTACT_INFO können jedoch mehrere Arten von Kontaktdaten hochgeladen werden.
Dies wird empfohlen, um höhere Abgleichsraten zu erzielen.
CRM-IDs hochladen
Wenn Sie die Kundenliste mit CRM-IDs füllen möchten, setzen Sie upload_key_type auf CRM_ID.
CRM-IDs werden anhand einer vom Werbetreibenden generierten und zugewiesenen User-ID abgeglichen.
Dieser Vorgang ähnelt dem Hochladen von MOBILE_ADVERTISING_ID-Instanzen, allerdings füllen Sie stattdessen das Feld third_party_user_id des Objekts UserIdentifier aus.
IDs für Mobilgeräte hochladen
Ähnlich wie beim Kundenabgleich mit E-Mail-Adressen können Sie den Kundenabgleich mithilfe der Mobilgeräte-IDs (Identifier for Advertising, IDFA) oder der AAID (Google Advertising ID) durchführen. Geben Sie dazu das Attribut app_id an und legen Sie upload_key_type auf MOBILE_ADVERTISING_ID fest, bevor Sie eine Nutzerliste für den Kundenabgleich mit Mobilgeräte-IDs verwenden.
Codebeispiel
Im folgenden Beispiel wird ein OfflineUserDataJobOperation verwendet, um Kontaktdaten von Kunden an eine Kundenliste anzuhängen.
Java
// Creates a raw input list of unhashed user information, where each element of the list
// represents a single user and is a map containing a separate entry for the keys "email",
// "phone", "firstName", "lastName", "countryCode", and "postalCode". In your application, this
// data might come from a file or a database.
List<Map<String, String>> rawRecords = new ArrayList<>();
// The first user data has an email address and a phone number.
Map<String, String> rawRecord1 =
ImmutableMap.<String, String>builder()
.put("email", "dana@example.com")
// Phone number to be converted to E.164 format, with a leading '+' as required. This
// includes whitespace that will be removed later.
.put("phone", "+1 800 5550101")
.build();
// The second user data has an email address, a mailing address, and a phone number.
Map<String, String> rawRecord2 =
ImmutableMap.<String, String>builder()
// Email address that includes a period (.) before the domain.
.put("email", "alex.2@example.com")
// Address that includes all four required elements: first name, last name, country
// code, and postal code.
.put("firstName", "Alex")
.put("lastName", "Quinn")
.put("countryCode", "US")
.put("postalCode", "94045")
// Phone number to be converted to E.164 format, with a leading '+' as required.
.put("phone", "+1 800 5550102")
.build();
// The third user data only has an email address.
Map<String, String> rawRecord3 =
ImmutableMap.<String, String>builder().put("email", "charlie@example.com").build();
// Adds the raw records to the raw input list.
rawRecords.add(rawRecord1);
rawRecords.add(rawRecord2);
rawRecords.add(rawRecord3);
// Iterates over the raw input list and creates a UserData object for each record.
List<UserData> userDataList = new ArrayList<>();
for (Map<String, String> rawRecord : rawRecords) {
// Creates a builder for the UserData object that represents a member of the user list.
UserData.Builder userDataBuilder = UserData.newBuilder();
// Checks if the record has email, phone, or address information, and adds a SEPARATE
// UserIdentifier object for each one found. For example, a record with an email address and a
// phone number will result in a UserData with two UserIdentifiers.
// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is a
// oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only ONE of
// hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId, or addressInfo. Setting more
// than one of these attributes on the same UserIdentifier will clear all the other members
// of the oneof. For example, the following code is INCORRECT and will result in a
// UserIdentifier with ONLY a hashedPhoneNumber.
//
// UserIdentifier incorrectlyPopulatedUserIdentifier =
// UserIdentifier.newBuilder()
// .setHashedEmail("...")
// .setHashedPhoneNumber("...")
// .build();
//
// The separate 'if' statements below demonstrate the correct approach for creating a UserData
// for a member with multiple UserIdentifiers.
// Checks if the record has an email address, and if so, adds a UserIdentifier for it.
if (rawRecord.containsKey("email")) {
UserIdentifier hashedEmailIdentifier =
UserIdentifier.newBuilder()
.setHashedEmail(normalizeAndHash(sha256Digest, rawRecord.get("email"), true))
.build();
// Adds the hashed email identifier to the UserData object's list.
userDataBuilder.addUserIdentifiers(hashedEmailIdentifier);
}
// Checks if the record has a phone number, and if so, adds a UserIdentifier for it.
if (rawRecord.containsKey("phone")) {
UserIdentifier hashedPhoneNumberIdentifier =
UserIdentifier.newBuilder()
.setHashedPhoneNumber(normalizeAndHash(sha256Digest, rawRecord.get("phone"), true))
.build();
// Adds the hashed phone number identifier to the UserData object's list.
userDataBuilder.addUserIdentifiers(hashedPhoneNumberIdentifier);
}
// Checks if the record has all the required mailing address elements, and if so, adds a
// UserIdentifier for the mailing address.
if (rawRecord.containsKey("firstName")) {
// Checks if the record contains all the other required elements of a mailing address.
Set<String> missingAddressKeys = new HashSet<>();
for (String addressKey : new String[] {"lastName", "countryCode", "postalCode"}) {
if (!rawRecord.containsKey(addressKey)) {
missingAddressKeys.add(addressKey);
}
}
if (!missingAddressKeys.isEmpty()) {
System.out.printf(
"Skipping addition of mailing address information because the following required keys"
+ " are missing: %s%n",
missingAddressKeys);
} else {
// Creates an OfflineUserAddressInfo object that contains all the required elements of a
// mailing address.
OfflineUserAddressInfo addressInfo =
OfflineUserAddressInfo.newBuilder()
.setHashedFirstName(
normalizeAndHash(sha256Digest, rawRecord.get("firstName"), false))
.setHashedLastName(
normalizeAndHash(sha256Digest, rawRecord.get("lastName"), false))
.setCountryCode(rawRecord.get("countryCode"))
.setPostalCode(rawRecord.get("postalCode"))
.build();
UserIdentifier addressIdentifier =
UserIdentifier.newBuilder().setAddressInfo(addressInfo).build();
// Adds the address identifier to the UserData object's list.
userDataBuilder.addUserIdentifiers(addressIdentifier);
}
}
if (!userDataBuilder.getUserIdentifiersList().isEmpty()) {
// Builds the UserData and adds it to the list.
userDataList.add(userDataBuilder.build());
}
}
// Creates the operations to add users.
List<OfflineUserDataJobOperation> operations = new ArrayList<>();
for (UserData userData : userDataList) {
operations.add(OfflineUserDataJobOperation.newBuilder().setCreate(userData).build());
}
C#
// Creates a raw input list of unhashed user information, where each element of the list
// represents a single user and is a map containing a separate entry for the keys
// "email", "phone", "firstName", "lastName", "countryCode", and "postalCode".
// In your application, this data might come from a file or a database.
List<Dictionary<string, string>> rawRecords = new List<Dictionary<string, string>>();
// The first user data has an email address and a phone number.
Dictionary<string, string> rawRecord1 = new Dictionary<string, string>();
rawRecord1.Add("email", "dana@example.com");
// Phone number to be converted to E.164 format, with a leading '+' as required.
// This includes whitespace that will be removed later.
rawRecord1.Add("phone", "+1 800 5550101");
// The second user data has an email address, a mailing address, and a phone number.
Dictionary<string, string> rawRecord2 = new Dictionary<string, string>();
// Email address that includes a period (.) before the Gmail domain.
rawRecord2.Add("email", "alex.2@example.com");
// Address that includes all four required elements: first name, last name, country
// code, and postal code.
rawRecord2.Add("firstName", "Alex");
rawRecord2.Add("lastName", "Quinn");
rawRecord2.Add("countryCode", "US");
rawRecord2.Add("postalCode", "94045");
// Phone number to be converted to E.164 format, with a leading '+' as required.
// This includes whitespace that will be removed later.
rawRecord2.Add("phone", "+1 800 5550102");
// The third user data only has an email address.
Dictionary<string, string> rawRecord3 = new Dictionary<string, string>();
rawRecord3.Add("email", "charlie@example.com");
// Adds the raw records to the raw input list.
rawRecords.Add(rawRecord1);
rawRecords.Add(rawRecord2);
rawRecords.Add(rawRecord3);
// Iterates over the raw input list and creates a UserData object for each record.
List<UserData> userDataList = new List<UserData>();
foreach (Dictionary<string, string> rawRecord in rawRecords) {
// Creates a UserData object that represents a member of the user list.
UserData userData = new UserData();
// Checks if the record has email, phone, or address information, and adds a
// SEPARATE UserIdentifier object for each one found.
// For example, a record with an email address and a phone number will result in a
// UserData with two UserIdentifiers.
// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
// is a oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set
// only ONE of hashedEmail, hashedPhoneNumber, mobileId, thirdPartyUserId,
// or addressInfo.
// Setting more than one of these attributes on the same UserIdentifier will clear
// all the other members of the oneof.
// For example, the following code is INCORRECT and will result in a UserIdentifier
// with ONLY a hashedPhoneNumber.
//
// UserIdentifier incorrectlyPopulatedUserIdentifier = new UserIdentifier()
// {
// HashedEmail = "...",
// HashedPhoneNumber = "..."
// };
//
// The separate 'if' statements below demonstrate the correct approach for creating
// a UserData for a member with multiple UserIdentifiers.
// Checks if the record has an email address, and if so, adds a UserIdentifier
// for it.
if (rawRecord.ContainsKey("email")) {
UserIdentifier hashedEmailIdentifier = new UserIdentifier()
{
HashedEmail = NormalizeAndHash(rawRecord["email"], true)
};
userData.UserIdentifiers.Add(hashedEmailIdentifier);
}
// Checks if the record has a phone number, and if so, adds a UserIdentifier for it.
if (rawRecord.ContainsKey("phone")) {
UserIdentifier hashedPhoneNumberIdentifier = new UserIdentifier()
{
HashedPhoneNumber = NormalizeAndHash(rawRecord["phone"], true)
};
// Adds the hashed phone number identifier to the UserData object's list.
userData.UserIdentifiers.Add(hashedPhoneNumberIdentifier);
}
// Checks if the record has all the required mailing address elements, and if so,
// adds a UserIdentifier for the mailing address.
if (rawRecord.ContainsKey("firstName")) {
// Checks if the record contains all the other required elements of a mailing
// address.
HashSet<string> missingAddressKeys = new HashSet<string>();
foreach (string addressKey in new string[] {"lastName", "countryCode",
"postalCode"}) {
if (!rawRecord.ContainsKey(addressKey)) {
missingAddressKeys.Add(addressKey);
}
}
if (!missingAddressKeys.Any()) {
Console.WriteLine(
$"Skipping addition of mailing address information because the following " +
"required keys are missing: {missingAddressKeys}");
} else {
// Creates an OfflineUserAddressInfo object that contains all the required
// elements of a mailing address.
OfflineUserAddressInfo addressInfo = new OfflineUserAddressInfo()
{
HashedFirstName = NormalizeAndHash(rawRecord["firstName"]),
HashedLastName = NormalizeAndHash(rawRecord["lastName"]),
CountryCode = rawRecord["countryCode"],
PostalCode = rawRecord["postalCode"]
};
UserIdentifier addressIdentifier = new UserIdentifier()
{
AddressInfo = addressInfo
};
// Adds the address identifier to the UserData object's list.
userData.UserIdentifiers.Add(addressIdentifier);
}
}
if (userData.UserIdentifiers.Any())
{
userDataList.Add(userData);
}
}
// Creates the operations to add the users.
List<OfflineUserDataJobOperation> operations = new List<OfflineUserDataJobOperation>();
foreach(UserData userData in userDataList)
{
operations.Add(new OfflineUserDataJobOperation()
{
Create = userData
});
}
PHP
// Creates a raw input list of unhashed user information, where each element of the list
// represents a single user and is a map containing a separate entry for the keys 'email',
// 'phone', 'firstName', 'lastName', 'countryCode', and 'postalCode'. In your application,
// this data might come from a file or a database.
$rawRecords = [];
// The first user data has an email address and a phone number.
$rawRecord1 = [
// The first user data has an email address and a phone number.
'email' => 'dana@example.com',
// Phone number to be converted to E.164 format, with a leading '+' as required. This
// includes whitespace that will be removed later.
'phone' => '+1 800 5550101'
];
$rawRecords[] = $rawRecord1;
// The second user data has an email address, a mailing address, and a phone number.
$rawRecord2 = [
// Email address that includes a period (.) before the Gmail domain.
'email' => 'alex.2@example.com',
// Address that includes all four required elements: first name, last name, country
// code, and postal code.
'firstName' => 'Alex',
'lastName' => 'Quinn',
'countryCode' => 'US',
'postalCode' => '94045',
// Phone number to be converted to E.164 format, with a leading '+' as required.
'phone' => '+1 800 5550102',
];
$rawRecords[] = $rawRecord2;
// The third user data only has an email address.
$rawRecord3 = ['email' => 'charlie@example.com'];
$rawRecords[] = $rawRecord3;
// Iterates over the raw input list and creates a UserData object for each record.
$userDataList = [];
foreach ($rawRecords as $rawRecord) {
// Checks if the record has email, phone, or address information, and adds a SEPARATE
// UserIdentifier object for each one found. For example, a record with an email address
// and a phone number will result in a UserData with two UserIdentifiers.
// IMPORTANT: Since the identifier attribute of UserIdentifier
// (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier) is
// a oneof
// (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set only
// ONE of 'hashed_email, 'hashed_phone_number', 'mobile_id', 'third_party_user_id', or
// 'address_info'.
// Setting more than one of these attributes on the same UserIdentifier will clear all
// the other members of the oneof. For example, the following code is INCORRECT and will
// result in a UserIdentifier with ONLY a 'hashed_phone_number'.
//
// $incorrectlyPopulatedUserIdentifier = new UserIdentifier();
// $incorrectlyPopulatedUserIdentifier->setHashedEmail('...');
// $incorrectlyPopulatedUserIdentifier->setHashedPhoneNumber('...');
//
// The separate 'if' statements below demonstrate the correct approach for creating a
// UserData for a member with multiple UserIdentifiers.
$userIdentifiers = [];
// Checks if the record has an email address, and if so, adds a UserIdentifier for it.
if (array_key_exists('email', $rawRecord)) {
$hashedEmailIdentifier = new UserIdentifier([
'hashed_email' => self::normalizeAndHash($rawRecord['email'], true)
]);
// Adds the hashed email identifier to the user identifiers list.
$userIdentifiers[] = $hashedEmailIdentifier;
}
// Checks if the record has a phone number, and if so, adds a UserIdentifier for it.
if (array_key_exists('phone', $rawRecord)) {
$hashedPhoneNumberIdentifier = new UserIdentifier([
'hashed_phone_number' => self::normalizeAndHash($rawRecord['phone'], true)
]);
// Adds the hashed email identifier to the user identifiers list.
$userIdentifiers[] = $hashedPhoneNumberIdentifier;
}
// Checks if the record has all the required mailing address elements, and if so, adds a
// UserIdentifier for the mailing address.
if (array_key_exists('firstName', $rawRecord)) {
// Checks if the record contains all the other required elements of a mailing
// address.
$missingAddressKeys = [];
foreach (['lastName', 'countryCode', 'postalCode'] as $addressKey) {
if (!array_key_exists($addressKey, $rawRecord)) {
$missingAddressKeys[] = $addressKey;
}
}
if (!empty($missingAddressKeys)) {
printf(
"Skipping addition of mailing address information because the "
. "following required keys are missing: %s%s",
json_encode($missingAddressKeys),
PHP_EOL
);
} else {
// Creates an OfflineUserAddressInfo object that contains all the required
// elements of a mailing address.
$addressIdentifier = new UserIdentifier([
'address_info' => new OfflineUserAddressInfo([
'hashed_first_name' => self::normalizeAndHash(
$rawRecord['firstName'],
false
),
'hashed_last_name' => self::normalizeAndHash(
$rawRecord['lastName'],
false
),
'country_code' => $rawRecord['countryCode'],
'postal_code' => $rawRecord['postalCode']
])
]);
// Adds the address identifier to the user identifiers list.
$userIdentifiers[] = $addressIdentifier;
}
}
if (!empty($userIdentifiers)) {
// Builds the UserData and adds it to the list.
$userDataList[] = new UserData(['user_identifiers' => $userIdentifiers]);
}
}
// Creates the operations to add users.
$operations = array_map(
function (UserData $userData) {
return new OfflineUserDataJobOperation(['create' => $userData]);
},
$userDataList
);
Python
def build_offline_user_data_job_operations(client):
"""Creates a raw input list of unhashed user information.
Each element of the list represents a single user and is a dict containing a
separate entry for the keys "email", "phone", "first_name", "last_name",
"country_code", and "postal_code". In your application, this data might come
from a file or a database.
Args:
client: The Google Ads client.
Returns:
A list containing the operations.
"""
# The first user data has an email address and a phone number.
raw_record_1 = {
"email": "dana@example.com",
# Phone number to be converted to E.164 format, with a leading '+' as
# required. This includes whitespace that will be removed later.
"phone": "+1 800 5550101",
}
# The second user data has an email address, a mailing address, and a phone
# number.
raw_record_2 = {
# Email address that includes a period (.) before the email domain.
"email": "alex.2@example.com",
# Address that includes all four required elements: first name, last
# name, country code, and postal code.
"first_name": "Alex",
"last_name": "Quinn",
"country_code": "US",
"postal_code": "94045",
# Phone number to be converted to E.164 format, with a leading '+' as
# required.
"phone": "+1 800 5550102",
}
# The third user data only has an email address.
raw_record_3 = {"email": "charlie@example.com"}
# Adds the raw records to a raw input list.
raw_records = [raw_record_1, raw_record_2, raw_record_3]
operations = []
# Iterates over the raw input list and creates a UserData object for each
# record.
for record in raw_records:
# Creates a UserData object that represents a member of the user list.
user_data = client.get_type("UserData")
# Checks if the record has email, phone, or address information, and
# adds a SEPARATE UserIdentifier object for each one found. For example,
# a record with an email address and a phone number will result in a
# UserData with two UserIdentifiers.
# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you
# must set only ONE of hashed_email, hashed_phone_number, mobile_id,
# third_party_user_id, or address-info. Setting more than one of these
# attributes on the same UserIdentifier will clear all the other members
# of the oneof. For example, the following code is INCORRECT and will
# result in a UserIdentifier with ONLY a hashed_phone_number:
# incorrect_user_identifier = client.get_type("UserIdentifier")
# incorrect_user_identifier.hashed_email = "..."
# incorrect_user_identifier.hashed_phone_number = "..."
# The separate 'if' statements below demonstrate the correct approach
# for creating a UserData object for a member with multiple
# UserIdentifiers.
# Checks if the record has an email address, and if so, adds a
# UserIdentifier for it.
if "email" in record:
user_identifier = client.get_type("UserIdentifier")
user_identifier.hashed_email = normalize_and_hash(
record["email"], True
)
# Adds the hashed email identifier to the UserData object's list.
user_data.user_identifiers.append(user_identifier)
# Checks if the record has a phone number, and if so, adds a
# UserIdentifier for it.
if "phone" in record:
user_identifier = client.get_type("UserIdentifier")
user_identifier.hashed_phone_number = normalize_and_hash(
record["phone"], True
)
# Adds the hashed phone number identifier to the UserData object's
# list.
user_data.user_identifiers.append(user_identifier)
# Checks if the record has all the required mailing address elements,
# and if so, adds a UserIdentifier for the mailing address.
if "first_name" in record:
required_keys = ("last_name", "country_code", "postal_code")
# Checks if the record contains all the other required elements of
# a mailing address.
if not all(key in record for key in required_keys):
# Determines which required elements are missing from the
# record.
missing_keys = record.keys() - required_keys
print(
"Skipping addition of mailing address information "
"because the following required keys are missing: "
f"{missing_keys}"
)
else:
user_identifier = client.get_type("UserIdentifier")
address_info = user_identifier.address_info
address_info.hashed_first_name = normalize_and_hash(
record["first_name"], False
)
address_info.hashed_last_name = normalize_and_hash(
record["last_name"], False
)
address_info.country_code = record["country_code"]
address_info.postal_code = record["postal_code"]
user_data.user_identifiers.append(user_identifier)
# If the user_identifiers repeated field is not empty, create a new
# OfflineUserDataJobOperation and add the UserData to it.
if user_data.user_identifiers:
operation = client.get_type("OfflineUserDataJobOperation")
operation.create = user_data
operations.append(operation)
Ruby
# Create a list of unhashed user data records that we will format in the
# following steps to prepare for the API.
raw_records = [
# The first user data has an email address and a phone number.
{
email: 'dana@example.com',
# Phone number to be converted to E.164 format, with a leading '+' as
# required. This includes whitespace that will be removed later.
phone: '+1 800 5550100',
},
# The second user data has an email address, a phone number, and an address.
{
# Email address that includes a period (.) before the Gmail domain.
email: 'alex.2@example.com',
# Address that includes all four required elements: first name, last
# name, country code, and postal code.
first_name: 'Alex',
last_name: 'Quinn',
country_code: 'US',
postal_code: '94045',
# Phone number to be converted to E.164 format, with a leading '+' as
# required.
phone: '+1 800 5550102',
},
# The third user data only has an email address.
{
email: 'charlie@example.com',
},
]
# Create a UserData for each entry in the raw records.
user_data_list = raw_records.map do |record|
client.resource.user_data do |data|
if record[:email]
data.user_identifiers << client.resource.user_identifier do |ui|
ui.hashed_email = normalize_and_hash(record[:email], true)
end
end
if record[:phone]
data.user_identifiers << client.resource.user_identifier do |ui|
ui.hashed_phone_number = normalize_and_hash(record[:phone], true)
end
end
if record[:first_name]
# Check that we have all the required information.
missing_keys = [:last_name, :country_code, :postal_code].reject {|key|
record[key].nil?
}
if missing_keys.empty?
# If nothing is missing, add the address.
data.user_identifiers << client.resource.user_identifier do |ui|
ui.address_identifier = client.resource.offline_user_address_info do |address|
address.hashed_first_name = normalize_and_hash(record[:first_name])
address.hashed_last_name = normalize_and_hash(record[:last_name])
address.country_code = record[:country_code]
address.postal_code = record[:postal_code]
end
end
else
# If some data is missing, skip this entry.
puts "Skipping addition of mailing information because the following keys are missing:" \
"#{missing_keys}"
end
end
end
end
operations = user_data_list.map do |user_data|
client.operation.create_resource.offline_user_data_job(user_data)
end
Perl
# The first user data has an email address and a phone number.
my $raw_record_1 = {
email => 'dana@example.com',
# Phone number to be converted to E.164 format, with a leading '+' as
# required. This includes whitespace that will be removed later.
phone => '+1 800 5550101',
};
# The second user data has an email address, a mailing address, and a phone
# number.
my $raw_record_2 = {
# Email address that includes a period (.) before the Gmail domain.
email => 'alex.2@example.com',
# Address that includes all four required elements: first name, last
# name, country code, and postal code.
firstName => 'Alex',
lastName => 'Quinn',
countryCode => 'US',
postalCode => '94045',
# Phone number to be converted to E.164 format, with a leading '+' as
# required.
phone => '+1 800 5550102',
};
# The third user data only has an email address.
my $raw_record_3 = {email => 'charlie@example.com',};
my $raw_records = [$raw_record_1, $raw_record_2, $raw_record_3];
my $operations = [];
foreach my $record (@$raw_records) {
# Check if the record has email, phone, or address information, and adds a
# SEPARATE UserIdentifier object for each one found. For example, a record
# with an email address and a phone number will result in a UserData with two
# UserIdentifiers.
#
# IMPORTANT: Since the identifier attribute of UserIdentifier
# (https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier)
# is a oneof
# (https://protobuf.dev/programming-guides/proto3/#oneof-features), you must set
# only ONE of hashed_email, hashed_phone_number, mobile_id, third_party_user_id,
# or address-info. Setting more than one of these attributes on the same UserIdentifier
# will clear all the other members of the oneof. For example, the following code is
# INCORRECT and will result in a UserIdentifier with ONLY a hashed_phone_number:
#
# my $incorrect_user_identifier = Google::Ads::GoogleAds::V16::Common::UserIdentifier->new({
# hashedEmail => '...',
# hashedPhoneNumber => '...',
# });
#
# The separate 'if' statements below demonstrate the correct approach for creating a
# UserData object for a member with multiple UserIdentifiers.
my $user_identifiers = [];
# Check if the record has an email address, and if so, add a UserIdentifier for it.
if (defined $record->{email}) {
# Add the hashed email identifier to the list of UserIdentifiers.
push(
@$user_identifiers,
Google::Ads::GoogleAds::V16::Common::UserIdentifier->new({
hashedEmail => normalize_and_hash($record->{email}, 1)}));
}
# Check if the record has a phone number, and if so, add a UserIdentifier for it.
if (defined $record->{phone}) {
# Add the hashed phone number identifier to the list of UserIdentifiers.
push(
@$user_identifiers,
Google::Ads::GoogleAds::V16::Common::UserIdentifier->new({
hashedPhoneNumber => normalize_and_hash($record->{phone}, 1)}));
}
# Check if the record has all the required mailing address elements, and if so, add
# a UserIdentifier for the mailing address.
if (defined $record->{firstName}) {
my $required_keys = ["lastName", "countryCode", "postalCode"];
my $missing_keys = [];
foreach my $key (@$required_keys) {
if (!defined $record->{$key}) {
push(@$missing_keys, $key);
}
}
if (@$missing_keys) {
print
"Skipping addition of mailing address information because the following"
. "keys are missing: "
. join(",", @$missing_keys);
} else {
push(
@$user_identifiers,
Google::Ads::GoogleAds::V16::Common::UserIdentifier->new({
addressInfo =>
Google::Ads::GoogleAds::V16::Common::OfflineUserAddressInfo->
new({
# First and last name must be normalized and hashed.
hashedFirstName => normalize_and_hash($record->{firstName}),
hashedLastName => normalize_and_hash($record->{lastName}),
# Country code and zip code are sent in plain text.
countryCode => $record->{countryCode},
postalCode => $record->{postalCode},
})}));
}
}
# If the user_identifiers array is not empty, create a new
# OfflineUserDataJobOperation and add the UserData to it.
if (@$user_identifiers) {
my $user_data = Google::Ads::GoogleAds::V16::Common::UserData->new({
userIdentifiers => [$user_identifiers]});
push(
@$operations,
Google::Ads::GoogleAds::V16::Services::OfflineUserDataJobService::OfflineUserDataJobOperation
->new({
create => $user_data
}));
}
}
Listenupload und Abgleichsrate prüfen
Sobald OfflineUserDataJob den Status SUCCESS hat, ist die geschätzte Abgleichsrate im Feld operation_metadata.match_rate_range verfügbar. Wenn Sie dieses Feld abfragen, bevor der Job abgeschlossen ist, kann der Wert in diesem Feld null sein. Damit die Abgleichsrate für die Überprüfung und die Liste für das Targeting bereit ist, sollten Sie den Job abfragen. Es kann nur 10 Minuten oder bis zu 24 Stunden dauern, bis der Job abgeschlossen ist.
Codebeispiel zum Prüfen des Jobstatus
Java
private void checkJobStatus(
GoogleAdsClient googleAdsClient, long customerId, String offlineUserDataJobResourceName) {
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
String query =
String.format(
"SELECT offline_user_data_job.resource_name, "
+ "offline_user_data_job.id, "
+ "offline_user_data_job.status, "
+ "offline_user_data_job.type, "
+ "offline_user_data_job.failure_reason, "
+ "offline_user_data_job.customer_match_user_list_metadata.user_list "
+ "FROM offline_user_data_job "
+ "WHERE offline_user_data_job.resource_name = '%s'",
offlineUserDataJobResourceName);
// Issues the query and gets the GoogleAdsRow containing the job from the response.
GoogleAdsRow googleAdsRow =
googleAdsServiceClient
.search(Long.toString(customerId), query)
.iterateAll()
.iterator()
.next();
OfflineUserDataJob offlineUserDataJob = googleAdsRow.getOfflineUserDataJob();
System.out.printf(
"Offline user data job ID %d with type '%s' has status: %s%n",
offlineUserDataJob.getId(), offlineUserDataJob.getType(), offlineUserDataJob.getStatus());
OfflineUserDataJobStatus jobStatus = offlineUserDataJob.getStatus();
if (OfflineUserDataJobStatus.SUCCESS == jobStatus) {
// Prints information about the user list.
printCustomerMatchUserListInfo(
googleAdsClient,
customerId,
offlineUserDataJob.getCustomerMatchUserListMetadata().getUserList());
} else if (OfflineUserDataJobStatus.FAILED == jobStatus) {
System.out.printf(" Failure reason: %s%n", offlineUserDataJob.getFailureReason());
} else if (OfflineUserDataJobStatus.PENDING == jobStatus
|| OfflineUserDataJobStatus.RUNNING == jobStatus) {
System.out.println();
System.out.printf(
"To check the status of the job periodically, use the following GAQL query with"
+ " GoogleAdsService.search:%n%s%n",
query);
}
}
}
C#
private static void CheckJobStatusAndPrintResults(GoogleAdsClient client, long customerId,
string offlineUserDataJobResourceName)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient service = client.GetService(Services.V16.GoogleAdsService);
string query = "SELECT offline_user_data_job.resource_name, " +
"offline_user_data_job.id, offline_user_data_job.status, " +
"offline_user_data_job.type, offline_user_data_job.failure_reason " +
"offline_user_data_job.customer_match_user_list_metadata_user_list " +
"FROM offline_user_data_job WHERE " +
$"offline_user_data_job.resource_name = '{offlineUserDataJobResourceName}'";
// Issues the query and gets the GoogleAdsRow containing the job from the response.
GoogleAdsRow googleAdsRow = service.Search(customerId.ToString(), query).First();
OfflineUserDataJob offlineUserDataJob = googleAdsRow.OfflineUserDataJob;
Console.WriteLine($"Offline user data job ID {offlineUserDataJob.Id} with type " +
$"'{offlineUserDataJob.Type}' has status: {offlineUserDataJob.Status}");
switch (offlineUserDataJob.Status)
{
case OfflineUserDataJobStatus.Success:
// Prints information about the user list.
PrintCustomerMatchUserListInfo(client, customerId,
offlineUserDataJob.CustomerMatchUserListMetadata.UserList);
break;
case OfflineUserDataJobStatus.Failed:
Console.WriteLine($" Failure reason: {offlineUserDataJob.FailureReason}");
break;
case OfflineUserDataJobStatus.Pending:
case OfflineUserDataJobStatus.Running:
Console.WriteLine("To check the status of the job periodically, use the " +
$"following GAQL query with GoogleAdsService.search:\n\n{query}");
break;
}
}
PHP
private static function checkJobStatus(
GoogleAdsClient $googleAdsClient,
int $customerId,
string $offlineUserDataJobResourceName
) {
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves the offline user data job.
$query = "SELECT offline_user_data_job.resource_name, "
. "offline_user_data_job.id, "
. "offline_user_data_job.status, "
. "offline_user_data_job.type, "
. "offline_user_data_job.failure_reason, "
. "offline_user_data_job.customer_match_user_list_metadata.user_list "
. "FROM offline_user_data_job "
. "WHERE offline_user_data_job.resource_name = '$offlineUserDataJobResourceName'";
// Issues a search request to get the GoogleAdsRow containing the job from the response.
/** @var GoogleAdsRow $googleAdsRow */
$googleAdsRow =
$googleAdsServiceClient->search(SearchGoogleAdsRequest::build($customerId, $query))
->getIterator()
->current();
$offlineUserDataJob = $googleAdsRow->getOfflineUserDataJob();
// Prints out some information about the offline user data job.
$offlineUserDataJobStatus = $offlineUserDataJob->getStatus();
printf(
"Offline user data job ID %d with type '%s' has status: %s.%s",
$offlineUserDataJob->getId(),
OfflineUserDataJobType::name($offlineUserDataJob->getType()),
OfflineUserDataJobStatus::name($offlineUserDataJobStatus),
PHP_EOL
);
if ($offlineUserDataJobStatus === OfflineUserDataJobStatus::SUCCESS) {
// Prints information about the user list.
self::printCustomerMatchUserListInfo(
$googleAdsClient,
$customerId,
$offlineUserDataJob->getCustomerMatchUserListMetadata()->getUserList()
);
} elseif ($offlineUserDataJobStatus === OfflineUserDataJobStatus::FAILED) {
printf(" Failure reason: %s.%s", $offlineUserDataJob->getFailureReason(), PHP_EOL);
} elseif (
$offlineUserDataJobStatus === OfflineUserDataJobStatus::PENDING
|| $offlineUserDataJobStatus === OfflineUserDataJobStatus::RUNNING
) {
printf(
'%1$sTo check the status of the job periodically, use the following GAQL query with'
. ' GoogleAdsService.search:%1$s%2$s%1$s',
PHP_EOL,
$query
);
}
}
Python
def check_job_status(client, customer_id, offline_user_data_job_resource_name):
"""Retrieves, checks, and prints the status of the offline user data job.
If the job is completed successfully, information about the user list is
printed. Otherwise, a GAQL query will be printed, which can be used to
check the job status at a later date.
Offline user data jobs may take 6 hours or more to complete, so checking the
status periodically, instead of waiting, can be more efficient.
Args:
client: The Google Ads client.
customer_id: The ID for the customer that owns the user list.
offline_user_data_job_resource_name: The resource name of the offline
user data job to get the status of.
"""
query = f"""
SELECT
offline_user_data_job.resource_name,
offline_user_data_job.id,
offline_user_data_job.status,
offline_user_data_job.type,
offline_user_data_job.failure_reason,
offline_user_data_job.customer_match_user_list_metadata.user_list
FROM offline_user_data_job
WHERE offline_user_data_job.resource_name =
'{offline_user_data_job_resource_name}'
LIMIT 1"""
# Issues a search request using streaming.
google_ads_service = client.get_service("GoogleAdsService")
results = google_ads_service.search(customer_id=customer_id, query=query)
offline_user_data_job = next(iter(results)).offline_user_data_job
status_name = offline_user_data_job.status.name
user_list_resource_name = (
offline_user_data_job.customer_match_user_list_metadata.user_list
)
print(
f"Offline user data job ID '{offline_user_data_job.id}' with type "
f"'{offline_user_data_job.type_.name}' has status: {status_name}"
)
if status_name == "SUCCESS":
print_customer_match_user_list_info(
client, customer_id, user_list_resource_name
)
elif status_name == "FAILED":
print(f"\tFailure Reason: {offline_user_data_job.failure_reason}")
elif status_name in ("PENDING", "RUNNING"):
print(
"To check the status of the job periodically, use the following "
f"GAQL query with GoogleAdsService.Search: {query}"
)
Ruby
def check_job_status(client, customer_id, offline_user_data_job)
query = <<~QUERY
SELECT
offline_user_data_job.id,
offline_user_data_job.status,
offline_user_data_job.type,
offline_user_data_job.failure_reason,
offline_user_data_job.customer_match_user_list_metadata.user_list
FROM
offline_user_data_job
WHERE
offline_user_data_job.resource_name = '#{offline_user_data_job}'
QUERY
row = client.service.google_ads.search(
customer_id: customer_id,
query: query,
).first
job = row.offline_user_data_job
puts "Offline user data job ID #{job.id} with type '#{job.type}' has status: #{job.status}."
case job.status
when :SUCCESS
print_customer_match_user_list(client, customer_id, job.customer_match_user_list_metadata.user_list)
when :FAILED
puts " Failure reason: #{job.failure_reason}"
else
puts " To check the status of the job periodically, use the following GAQL " \
"query with GoogleAdsService.search:"
puts query
end
end
Perl
sub check_job_status() {
my ($api_client, $customer_id, $offline_user_data_job_resource_name) = @_;
my $search_query =
"SELECT offline_user_data_job.resource_name, " .
"offline_user_data_job.id, offline_user_data_job.status, " .
"offline_user_data_job.type, offline_user_data_job.failure_reason, " .
"offline_user_data_job.customer_match_user_list_metadata.user_list " .
"FROM offline_user_data_job " .
"WHERE offline_user_data_job.resource_name = " .
"$offline_user_data_job_resource_name LIMIT 1";
my $search_request =
Google::Ads::GoogleAds::V16::Services::GoogleAdsService::SearchGoogleAdsRequest
->new({
customerId => $customer_id,
query => $search_query
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({
service => $google_ads_service,
request => $search_request
});
# The results have exactly one row.
my $google_ads_row = $iterator->next;
my $offline_user_data_job = $google_ads_row->{offlineUserDataJob};
my $status = $offline_user_data_job->{status};
printf
"Offline user data job ID %d with type %s has status: %s.\n",
$offline_user_data_job->{id},
$offline_user_data_job->{type},
$status;
if ($status eq SUCCESS) {
print_customer_match_user_list_info($api_client, $customer_id,
$offline_user_data_job->{customerMatchUserListMetadata}{userList});
} elsif ($status eq FAILED) {
print "Failure reason: $offline_user_data_job->{failure_reason}";
} elsif (grep /$status/, (PENDING, RUNNING)) {
print
"To check the status of the job periodically, use the following GAQL " .
"query with the GoogleAdsService->search() method:\n$search_query\n";
}
return 1;
}
Zum Prüfen der Listengröße können Sie die Ressource user_list abfragen.
Codebeispiel zum Abfragen der user_list-Ressource
Java
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
// Creates a query that retrieves the user list.
String query =
String.format(
"SELECT user_list.size_for_display, user_list.size_for_search "
+ "FROM user_list "
+ "WHERE user_list.resource_name = '%s'",
userListResourceName);
// Constructs the SearchGoogleAdsStreamRequest.
SearchGoogleAdsStreamRequest request =
SearchGoogleAdsStreamRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.setQuery(query)
.build();
// Issues the search stream request.
ServerStream<SearchGoogleAdsStreamResponse> stream =
googleAdsServiceClient.searchStreamCallable().call(request);
C#
// Get the GoogleAdsService.
GoogleAdsServiceClient service =
client.GetService(Services.V16.GoogleAdsService);
// Creates a query that retrieves the user list.
string query =
"SELECT user_list.size_for_display, user_list.size_for_search " +
"FROM user_list " +
$"WHERE user_list.resource_name = '{userListResourceName}'";
// Issues a search stream request.
service.SearchStream(customerId.ToString(), query,
delegate (SearchGoogleAdsStreamResponse resp)
{
// Display the results.
foreach (GoogleAdsRow userListRow in resp.Results)
{
UserList userList = userListRow.UserList;
Console.WriteLine("The estimated number of users that the user list " +
$"'{userList.ResourceName}' has is {userList.SizeForDisplay}" +
$" for Display and {userList.SizeForSearch} for Search.");
}
}
);
PHP
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves the user list.
$query =
"SELECT user_list.size_for_display, user_list.size_for_search " .
"FROM user_list " .
"WHERE user_list.resource_name = '$userListResourceName'";
// Issues a search stream request.
/** @var GoogleAdsServerStreamDecorator $stream */
$stream = $googleAdsServiceClient->searchStream(
SearchGoogleAdsStreamRequest::build($customerId, $query)
);
Python
googleads_service_client = client.get_service("GoogleAdsService")
# Creates a query that retrieves the user list.
query = f"""
SELECT
user_list.size_for_display,
user_list.size_for_search
FROM user_list
WHERE user_list.resource_name = '{user_list_resource_name}'"""
# Issues a search request.
search_results = googleads_service_client.search(
customer_id=customer_id, query=query
)
Ruby
query = <<~EOQUERY
SELECT user_list.size_for_display, user_list.size_for_search
FROM user_list
WHERE user_list.resource_name = #{user_list}
EOQUERY
response = client.service.google_ads.search_stream(
customer_id: customer_id,
query: query,
)
Perl
# Create a query that retrieves the user list.
my $search_query =
"SELECT user_list.size_for_display, user_list.size_for_search " .
"FROM user_list " .
"WHERE user_list.resource_name = '$user_list_resource_name'";
# Create a search Google Ads stream request that will retrieve the user list.
my $search_stream_request =
Google::Ads::GoogleAds::V16::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
->new({
customerId => $customer_id,
query => $search_query,
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $search_stream_handler =
Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
service => $google_ads_service,
request => $search_stream_request
});
Aus Datenschutzgründen wird die Nutzerlistengröße als null angezeigt, bis die Liste mindestens 1.000 Mitglieder enthält. Danach wird die Größe auf die beiden höchstwertigen Stellen gerundet.
Fehler während der Ausführung eines OfflineUserDataJob können mithilfe der Google Ads Query Language über die Ressource offline_user_data_job abgerufen werden. Dieser Bericht enthält jedoch keine Informationen zu fehlgeschlagenen Übereinstimmungen, da bei der Durchführung von Übereinstimmungen nur Hashes verglichen werden. Konsultieren Sie die Anleitung zur Fehlerbehebung, falls Probleme mit Ihren Kundenlisten auftreten.
Vergleich mit der Google Ads-Benutzeroberfläche
Eine Liste kann kleiner als erwartet sein, wenn Sie sie über die Google Ads-Benutzeroberfläche in der Zielgruppenverwaltung aufrufen. Hier sehen Sie die Anzahl der aktiven Nutzer in der Liste. Weitere Informationen finden Sie in dieser Anleitung zur Fehlerbehebung.
Da es bis zu 24 Stunden dauern kann, bis eine Liste mit Mitgliedern gefüllt ist, wird in der Google Ads-Benutzeroberfläche möglicherweise der Status In Progress angezeigt, wenn Sie Daten häufiger als einmal alle 12 Stunden hochladen.
Auf meine Liste ausrichten
Sie können die Liste auf Anzeigengruppen- oder Kampagnenebene ausrichten. Die Vorgehensweise ähnelt anderen Arten von Targeting-Kriterien in der API.
Codebeispiel für das Targeting von Anzeigen in einer Anzeigengruppe auf eine Nutzerliste
Java
private String targetAdsInAdGroupToUserList(
GoogleAdsClient googleAdsClient, long customerId, long adGroupId, String userList) {
// Creates the ad group criterion targeting members of the user list.
AdGroupCriterion adGroupCriterion =
AdGroupCriterion.newBuilder()
.setAdGroup(ResourceNames.adGroup(customerId, adGroupId))
.setUserList(UserListInfo.newBuilder().setUserList(userList).build())
.build();
// Creates the operation.
AdGroupCriterionOperation operation =
AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterion).build();
// Creates the ad group criterion service.
try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
// Adds the ad group criterion.
MutateAdGroupCriteriaResponse response =
adGroupCriterionServiceClient.mutateAdGroupCriteria(
Long.toString(customerId), ImmutableList.of(operation));
// Gets and prints the results.
String adGroupCriterionResourceName = response.getResults(0).getResourceName();
System.out.printf(
"Successfully created ad group criterion with resource name '%s' "
+ "targeting user list with resource name '%s' with ad group with ID %d.%n",
adGroupCriterionResourceName, userList, adGroupId);
return adGroupCriterionResourceName;
}
}
C#
private string TargetAdsInAdGroupToUserList(
GoogleAdsClient client, long customerId, long adGroupId, string userListResourceName)
{
// Get the AdGroupCriterionService client.
AdGroupCriterionServiceClient adGroupCriterionServiceClient = client.GetService
(Services.V16.AdGroupCriterionService);
// Create the ad group criterion targeting members of the user list.
AdGroupCriterion adGroupCriterion = new AdGroupCriterion
{
AdGroup = ResourceNames.AdGroup(customerId, adGroupId),
UserList = new UserListInfo
{
UserList = userListResourceName
}
};
// Create the operation.
AdGroupCriterionOperation adGroupCriterionOperation = new AdGroupCriterionOperation
{
Create = adGroupCriterion
};
// Add the ad group criterion, then print and return the new criterion's resource name.
MutateAdGroupCriteriaResponse mutateAdGroupCriteriaResponse =
adGroupCriterionServiceClient.MutateAdGroupCriteria(customerId.ToString(),
new[] { adGroupCriterionOperation });
string adGroupCriterionResourceName =
mutateAdGroupCriteriaResponse.Results.First().ResourceName;
Console.WriteLine("Successfully created ad group criterion with resource name " +
$"'{adGroupCriterionResourceName}' targeting user list with resource name " +
$"'{userListResourceName}' with ad group with ID {adGroupId}.");
return adGroupCriterionResourceName;
}
PHP
private static function targetAdsInAdGroupToUserList(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $adGroupId,
string $userListResourceName
): string {
// Creates the ad group criterion targeting members of the user list.
$adGroupCriterion = new AdGroupCriterion([
'ad_group' => ResourceNames::forAdGroup($customerId, $adGroupId),
'user_list' => new UserListInfo(['user_list' => $userListResourceName])
]);
// Creates the operation.
$operation = new AdGroupCriterionOperation();
$operation->setCreate($adGroupCriterion);
// Issues a mutate request to add an ad group criterion.
$adGroupCriterionServiceClient = $googleAdsClient->getAdGroupCriterionServiceClient();
/** @var MutateAdGroupCriteriaResponse $adGroupCriterionResponse */
$adGroupCriterionResponse = $adGroupCriterionServiceClient->mutateAdGroupCriteria(
MutateAdGroupCriteriaRequest::build($customerId, [$operation])
);
$adGroupCriterionResourceName =
$adGroupCriterionResponse->getResults()[0]->getResourceName();
printf(
"Successfully created ad group criterion with resource name '%s' " .
"targeting user list with resource name '%s' with ad group with ID %d.%s",
$adGroupCriterionResourceName,
$userListResourceName,
$adGroupId,
PHP_EOL
);
return $adGroupCriterionResourceName;
}
Python
def target_ads_in_ad_group_to_user_list(
client, customer_id, ad_group_id, user_list_resource_name
):
"""Creates an ad group criterion that targets a user list with an ad group.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a str client customer ID used to create an ad group
criterion.
ad_group_id: a str ID for an ad group used to create an ad group
criterion that targets members of a user list.
user_list_resource_name: a str resource name for a user list.
Returns:
a str resource name for an ad group criterion.
"""
ad_group_criterion_operation = client.get_type("AdGroupCriterionOperation")
# Creates the ad group criterion targeting members of the user list.
ad_group_criterion = ad_group_criterion_operation.create
ad_group_criterion.ad_group = client.get_service(
"AdGroupService"
).ad_group_path(customer_id, ad_group_id)
ad_group_criterion.user_list.user_list = user_list_resource_name
ad_group_criterion_service = client.get_service("AdGroupCriterionService")
response = ad_group_criterion_service.mutate_ad_group_criteria(
customer_id=customer_id, operations=[ad_group_criterion_operation]
)
resource_name = response.results[0].resource_name
print(
"Successfully created ad group criterion with resource name: "
f"'{resource_name}' targeting user list with resource name: "
f"'{user_list_resource_name}' and with ad group with ID "
f"{ad_group_id}."
)
return resource_name
Ruby
def target_ads_in_ad_group_to_user_list(
client,
customer_id,
ad_group_id,
user_list
)
# Creates the ad group criterion targeting members of the user list.
operation = client.operation.create_resource.ad_group_criterion do |agc|
agc.ad_group = client.path.ad_group(customer_id, ad_group_id)
agc.user_list = client.resource.user_list_info do |info|
info.user_list = user_list
end
end
# Issues a mutate request to create the ad group criterion.
response = client.service.ad_group_criterion.mutate_ad_group_criteria(
customer_id: customer_id,
operations: [operation],
)
ad_group_criterion_resource_name = response.results.first.resource_name
puts "Successfully created ad group criterion with resource name " \
"'#{ad_group_criterion_resource_name}' targeting user list with resource name " \
"'#{user_list}' with ad group with ID #{ad_group_id}"
ad_group_criterion_resource_name
end
Perl
sub target_ads_in_ad_group_to_user_list {
my ($api_client, $customer_id, $ad_group_id, $user_list_resource_name) = @_;
# Create the ad group criterion targeting members of the user list.
my $ad_group_criterion =
Google::Ads::GoogleAds::V16::Resources::AdGroupCriterion->new({
adGroup => Google::Ads::GoogleAds::V16::Utils::ResourceNames::ad_group(
$customer_id, $ad_group_id
),
userList => Google::Ads::GoogleAds::V16::Common::UserListInfo->new({
userList => $user_list_resource_name
})});
# Create the operation.
my $ad_group_criterion_operation =
Google::Ads::GoogleAds::V16::Services::AdGroupCriterionService::AdGroupCriterionOperation
->new({
create => $ad_group_criterion
});
# Add the ad group criterion, then print and return the new criterion's resource name.
my $ad_group_criteria_response =
$api_client->AdGroupCriterionService()->mutate({
customerId => $customer_id,
operations => [$ad_group_criterion_operation]});
my $ad_group_criterion_resource_name =
$ad_group_criteria_response->{results}[0]{resourceName};
printf "Successfully created ad group criterion with resource name '%s' " .
"targeting user list with resource name '%s' with ad group with ID %d.\n",
$ad_group_criterion_resource_name, $user_list_resource_name, $ad_group_id;
return $ad_group_criterion_resource_name;
}
Ausrichtung auf mehrere Kundenlisten
Ein crm_based_user_list kann nur mit einem anderen crm_based_user_list kombiniert werden, wenn ein logical_user_list verwendet wird.
Alle Richtlinien für crm_based_user_list gelten für die resultierende Nutzerliste.