Customer Match ti consente di utilizzare i dati online e offline per raggiungere e coinvolgere nuovamente i clienti sulla rete di ricerca, nella scheda Shopping, su Gmail, su YouTube e sulla Rete Display. Utilizzando le informazioni che i clienti hanno condiviso con te, Customer
Match indirizza gli annunci a questi e ad altri clienti simili. Puoi caricare collettivamente i dati della gestione dei rapporti con i clienti (CRM), aggiungere o rimuovere dati oppure utilizzare questi elenchi di utenti per creare un logical_user_list.
Consulta la panoramica sulla gestione dei segmenti di pubblico per un elenco dei diversi tipi di segmenti di pubblico da confrontare con Customer Match con altre opzioni di elenchi utenti.
Scopri di più su Customer Match e sul targeting per pubblico.
Prerequisiti
Non tutti gli account sono idonei all'utilizzo di Customer Match. Per utilizzare Customer Match, il tuo account deve avere quanto segue:
- Uno storico di conformità alle norme
- Uno storico di conformità in termini di pagamenti
A seconda dei requisiti soddisfatti dal tuo account, sono disponibili diverse funzionalità. Consulta le norme di Customer Match per i requisiti di idoneità e le limitazioni.
Progetta la tua integrazione
Flusso di utilizzo
Ecco la procedura consigliata per creare e scegliere come target un elenco di clienti:
Crea un elenco di clienti vuoto.
Crea una
OfflineUserDataJob. È molto più efficiente creare un unico job di grandi dimensioni che diversi job più piccoli.A partire dalla versione v15 dell'API Google Ads, devi compilare il campo
consentdicustomer_match_user_list_metadatanelle richiesteOfflineUserDataJobcreate. Per le richiesteremove, il consenso non è necessario. L'API restituisceOfflineUserDataJobError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMSse il valoreconsent.ad_user_dataoconsent.ad_personalizationdel job è impostato suDENIED. Se un identificatore ha il consenso diDENIED, puoi creare un job per rimuovere l'identificatore dall'elenco degli utenti.Aggiungi operazioni utilizzando il metodo
OfflineUserDataJobService.AddOfflineUserDataJobOperations. Consigliamo di aggiungere fino a 10.000 identificatori totali in una singola chiamata per un'elaborazione ottimale. Una singola richiestaAddOfflineUserDataJobOperationspuò contenere al massimo 100.000 identificatori in tutti gli oggettiUserDatanell'elenco delle operazioni.Ad esempio, se ciascuno dei tuoi oggetti
UserDataha unUserIdentifierperhashed_emaile un altroUserIdentifierperhashed_phone_number, l'invio di 5000 oggettiUserDataper richiesta è ottimale poiché ogni richiesta conterrà un totale di 10.000 identificatori utente.Ripeti il passaggio precedente fino a quando non vengono aggiunte tutte le operazioni o fino a quando il job non raggiunge la capacità. Non sono previsti limiti al numero di operazioni che puoi aggiungere a un singolo job; tuttavia, consigliamo non più di 1.000.000 di operazioni per job per un'elaborazione ottimale.
Esegui il job.
Sondaggio per verificare che il caricamento sia riuscito.
Verifica il tasso di corrispondenza.
Scegli come target l'elenco.
OfflineUserDataJobService e UserDataService
Sono disponibili due servizi per caricare i dati Customer Match. Seleziona il servizio in base al tuo caso d'uso, in quanto potrebbero essere soggetti a limitazioni.
| Servizi di caricamento Customer Match | |
|---|---|
OfflineUserDataJobService (preferito)
|
La maggior parte degli sviluppatori utilizza questo servizio. È ottimizzato per i caricamenti di grandi dimensioni con velocità effettiva elevata e restituisce le metriche di successo al completamento. Questa guida si concentra principalmente su questo servizio. |
UserDataService
|
Questo servizio è ottimizzato per caricare un numero limitato di identificatori alla volta con aggiornamenti sporadici e non è ottimizzato per essere eseguito continuamente. Ha un limite di 10 operazioni per richiesta. Inoltre, una singola richiesta non può contenere più di 100 elementi in totale per user_identifiers.
Per indicazioni sui caricamenti con questo servizio, consulta la guida alla gestione dell'integrazione Customer Match. A partire dalla versione v15
dell'API Google Ads, devi completare il campo
|
Best practice
Quando progetti l'integrazione Customer Match, tieni presente le seguenti best practice:
Non tentare di utilizzare più account per modificare un singolo elenco utenti. Un elenco di utenti può essere modificato solo dall'account Google Ads o dal partner di dati che lo ha creato.
Massimizza il numero di operazioni per
AddOfflineUserDataJobOperationsRequest, fino a un massimo di 10.000 identificatori, per evitare errori diRESOURCE_EXHAUSTED.Non combinare le operazioni
createeremoveall'interno della stessaOfflineUserDataJob. Questa operazione può causare un erroreCONFLICTING_OPERATION.Abilita
partial_failurein unAddOfflineUserDataJobOperationsRequestin modo da rilevare eventuali operazioni problematiche prima di eseguire il job. Le operazioni vengono convalidate quando vengono caricate in unaOfflineUserDataJob.Evita di eseguire contemporaneamente più processi
OfflineUserDataJobche modificano lo stesso elenco di utenti, ovvero più job i cuiCustomerMatchUserListMetadata.user_listpuntano allo stesso nome di risorsa. Questa operazione può causare un erroreCONCURRENT_MODIFICATION, poiché non è possibile operare contemporaneamente più job sullo stesso elenco. Questo errore può verificarsi anche se tenti di modificare contemporaneamente un elenco tramite l'interfaccia utente e l'API Google Ads. Tieni presente che questo non si applica all'aggiunta di operazioni a un jobPENDING, che può essere eseguita in qualsiasi momento prima dell'avvio del job.Se devi applicare migliaia di operazioni, creane una
OfflineUserDataJobcontenente tutte le operazioni. Non creare diversi job con solo poche centinaia di operazioni ciascuno ed eseguili in sequenza o contemporaneamente. Un singolo job di grandi dimensioni con tutte le tue operazioni è molto più efficiente rispetto a più job di piccole dimensioni e riduce le probabilità che si verifichino errori nel flusso di lavoro.
Per idee su come utilizzare gli elenchi di clienti per un targeting ottimale, visita il Centro assistenza.
Creare un elenco di clienti
Per prima cosa, crea un elenco di clienti con
UserListService, Gli elenchi di clienti vengono creati impostando il campo crm_based_user_list sull'oggetto user_list. Il campo crm_based_user_list può essere impostato sui tipi di campagna
che supportano il targeting degli elenchi di clienti:
| Customer Match in diversi tipi di campagna | |
|---|---|
| Rete di ricerca | Gli annunci vengono pubblicati sulla rete di ricerca. |
| Rete Display | Gli annunci vengono pubblicati sulla Rete Display e su Gmail solo se sono presenti creatività GSP. |
| Espansione alla Rete Display per le campagne sulla rete di ricerca | Gli annunci vengono pubblicati sulla rete di ricerca e su Gmail solo se sono presenti creatività GSP. |
| Campagne video | Gli annunci vengono pubblicati su YouTube solo se sono presenti annunci TrueView in-stream. |
| Campagne Shopping | Gli annunci vengono visualizzati nella scheda Shopping. |
crm_based_user_list contiene tre campi:
app_id: una stringa che identifica in modo univoco l'app mobile da cui sono stati raccolti i dati. Questo passaggio è obbligatorio durante la creazione diCrmBasedUserListper caricare gli ID pubblicità per il mobile.upload_key_type: un tipo di chiave corrispondente dell'elenco, che può essereCONTACT_INFO,CRM_IDoMOBILE_ADVERTISING_ID. Non sono consentiti tipi di dati misti nello stesso elenco. Questo campo è obbligatorio per tutti gli elenchi di clienti.data_source_type: l'origine dati dell'elenco. Il valore predefinito èFIRST_PARTY. I clienti inclusi nella lista consentita possono creare elenchi di clienti provenienti da terze parti.
L'attributo membership_life_span
dell'elenco utenti consente di definire il periodo di tempo, in giorni, durante il quale un
utente è considerato nell'elenco. I tipi di elenchi di clienti ti consentono di impostare
membership_life_span su 10.000 per indicare che non hanno scadenza.
L'attributo membership_status definisce se l'elenco accetta nuovi utenti.
Esempio di codice per creare un elenco di clienti
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;
}
Aggiungi i dati dei clienti
Le tre chiavi di corrispondenza principali sono indirizzo email, indirizzo postale e numero di telefono. Puoi utilizzare lo User-ID e l'ID dispositivo mobile come chiavi di corrispondenza, ma queste soluzioni sono meno a prova di futuro dato la dipendenza dai cookie e dall'ID dispositivo. Se possibile, ti consigliamo di caricare le informazioni di contatto degli utenti, come indirizzo email, indirizzo postale e numero di telefono, al posto del CRM o dell'ID dispositivo mobile.
Ogni elenco di utenti può contenere un solo tipo di dati dei clienti, come specificato dal campo CrmBasedUserListInfo.upload_key_type. Inoltre, un oggetto UserData, che
rappresenta un singolo utente, può contenere fino a 20 identificatori utente, ognuno
dei quali ha il proprio oggetto UserIdentifier. Più di 20 identificatori generano un errore TOO_MANY_USER_IDENTIFIERS.
Google Ads utilizza un elenco di utenti Customer Match per il targeting solo se ha raggiunto una soglia minima di utenti attivi al momento della pubblicazione dell'annuncio; per utenti attivi si intende il numero di utenti nell'elenco che sono attivi su Gmail, sulla rete di ricerca, su YouTube o sulla Rete Display. Carica almeno 5000 membri per aumentare le probabilità di avere un numero sufficiente di utenti attivi corrispondenti per il targeting.
Caricare i dati di contatto degli utenti
Per caricare indirizzi email, indirizzi postali o numeri di telefono degli utenti, imposta upload_key_type su CONTACT_INFO. Tieni presente che i dati di contatto devono essere associati a un Account Google per poter essere abbinati e gli account aziendali, come Google Workspace, non possono essere scelti come target.
Per motivi di privacy, indirizzi email, nomi, cognomi e numeri di telefono devono essere sottoposti ad hashing utilizzando l'algoritmo SHA-256 prima di essere caricati. Per standardizzare i risultati hash, prima di eseguire l'hashing di uno di questi valori, assicurati di eseguire le seguenti attività:
- Rimuovi gli spazi vuoti iniziali e finali.
- Per nomi, indirizzi email e indirizzi postali: converti il testo in minuscolo.
- Per i numeri di telefono: converti ogni numero di telefono nel formato E164 prima di eseguire l'hashing. Questo formato rappresenta un numero di telefono come un numero di massimo 15 cifre che inizia con un segno
+, ad esempio+12125650000o+442070313000. Il simbolo+iniziale può essere omesso facoltativamente.
Per gli indirizzi email, non è necessario rimuovere tutti i punti (.) che precedono il nome di dominio negli indirizzi email gmail.com e googlemail.com poiché sono ancora accettati.
Se i dati di contatto non sono formattati correttamente prima dell'hashing, l'API accetta comunque le informazioni sottoposte ad hashing, ma non possono essere abbinate a un cliente.
Se vuoi caricare i dati dell'indirizzo postale, devi includere almeno:
- Country code
- Codice postale
- Nome sottoposto ad hashing
- Cognome sottoposto ad hashing
Se uno di questi campi non è presente, l'indirizzo non può essere abbinato.
Mentre gli elenchi di clienti possono contenere un solo upload_key_type, è possibile caricare più tipi di dati di contatto per un upload_key_type di CONTACT_INFO.
Questa opzione è consigliata per aumentare i tassi di corrispondenza.
Carica ID CRM
Per completare l'elenco di clienti con gli ID CRM, imposta upload_key_type su
CRM_ID.
Gli ID CRM vengono abbinati da un ID utente generato e assegnato dall'inserzionista.
La procedura è simile al caricamento di istanze MOBILE_ADVERTISING_ID, ma devi compilare il campo third_party_user_id dell'oggetto UserIdentifier.
Carica ID dispositivi mobili
Analogamente a Customer Match con le email, puoi eseguire la corrispondenza dei clienti utilizzando gli ID dispositivo mobile IDFA (Identifier for Advertising) o AAID (Google Advertising ID). A questo scopo, specifica la proprietà app_id e imposta upload_key_type su MOBILE_ADVERTISING_ID prima di utilizzare un elenco di utenti per la corrispondenza dei clienti con gli ID dispositivo mobile.
Esempio di codice
L'esempio seguente utilizza un elemento OfflineUserDataJobOperation per aggiungere i dati di contatto
del cliente a un elenco di clienti.
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
}));
}
}
Verificare il caricamento dell'elenco e il tasso di corrispondenza
Una volta che OfflineUserDataJob assume lo stato SUCCESS, il tasso di corrispondenza stimato è disponibile nel campo operation_metadata.match_rate_range. Se esegui una query su questo campo prima del completamento del job, il valore in questo campo potrebbe essere zero. Per assicurarti che il tasso di corrispondenza sia pronto per la verifica e che l'elenco sia pronto per il targeting, ti consigliamo di eseguire il polling del job per il completamento. Il completamento del job può richiedere da 10 a 24 ore.
Esempio di codice per controllare lo stato del job
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;
}
Per verificare le dimensioni dell'elenco, puoi eseguire una query sulla risorsa user_list.
Esempio di codice per eseguire una query sulla risorsa user_list
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
});
Per motivi di privacy, la dimensione dell'elenco di utenti viene visualizzata come zero finché l'elenco non ha almeno 1000 membri. Successivamente, la dimensione viene arrotondata alle due cifre più significative.
Gli errori durante l'esecuzione di OfflineUserDataJob possono essere recuperati tramite la risorsa offline_user_data_job utilizzando il linguaggio di query di Google Ads. Tuttavia, tieni presente che questo report non contiene informazioni su eventuali corrispondenze non riuscite, in quanto vengono confrontati solo gli hash quando vengono eseguite corrispondenze. In caso di problemi con gli elenchi di clienti, consulta la guida alla risoluzione dei problemi.
Confronto con l'UI di Google Ads
Un elenco potrebbe sembrare più piccolo del previsto quando viene visualizzato in Gestione segmenti di pubblico dall'interfaccia utente di Google Ads. Questa visualizzazione mostra il numero di utenti attivi nell'elenco. Per ulteriori informazioni, consulta questa guida alla risoluzione dei problemi.
Poiché possono trascorrere fino a 24 ore prima che un elenco venga completato con i membri,
potresti visualizzare uno stato
In Progress nell'interfaccia utente di Google Ads se
effettui un caricamento in un elenco del segmento di pubblico più spesso di una volta ogni 12 ore.
Scegli come target il mio elenco
Puoi scegliere come target l'elenco a livello di gruppo di annunci o di campagna. La procedura è simile ad altri tipi di criteri di targeting nell'API.
Esempio di codice per indirizzare gli annunci di un gruppo a un elenco di utenti
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;
}
Scegli come target più elenchi di clienti
Un crm_based_user_list può essere combinato con un altro crm_based_user_list solo
quando si utilizza un logical_user_list.
Tutti i criteri per crm_based_user_list si applicano all'elenco di utenti risultante.