Com a Segmentação por lista de clientes, você pode usar dados on-line e off-line para alcançar e reengajar.
com os clientes na Pesquisa, na guia "Shopping", no Gmail, no YouTube e
Tela. Ao usar informações que seus clientes compartilharam com você,
A correspondência segmenta anúncios para esses clientes e outros clientes semelhantes. Você pode
fazer o upload em massa dos dados de gestão de relacionamento com o cliente (CRM), anexar ou remover
dados, ou usar essas listas de usuários para criar um
logical_user_list
Consultar o gerenciamento de públicos-alvo visão geral para conferir uma lista de tipos de segmentos de público-alvo para comparar com a Segmentação por lista de clientes outras opções da lista de usuários.
Saiba mais sobre o Customer Correspondente e público-alvo por segmentação.
Pré-requisitos
Nem todas as contas estão qualificadas para usar a Segmentação por lista de clientes. Para usar a Segmentação por lista de clientes, precisa ter o seguinte:
- um bom histórico de compliance com as políticas;
- um bom histórico de pagamentos;
Dependendo dos requisitos que sua conta atende, diferentes recursos são disponíveis. Usar a Segmentação por lista de clientes política de qualificação e restrições.
Projetar sua integração
Fluxo de uso
Veja o fluxo recomendado para criar e segmentar uma lista de clientes:
Crie uma lista de clientes vazia.
Crie um
OfflineUserDataJob. Está é muito mais eficiente criar um único job grande do que trabalhos menores.A partir da versão v15 da API Google Ads, você deve preencher o campo
consent; decustomer_match_user_list_metadatano seuOfflineUserDataJobcreatesolicitações. Para solicitaçõesremove, o consentimento não é necessário. A API retornaOfflineUserDataJobError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMSse oconsent.ad_user_dataouconsent.ad_personalizationdo job estiver definido paraDENIED.Se um usuário tiver negado o consentimento, você pode criar um job com uma
removepara remover os identificadores do usuário da lista.Se você não tiver o consentimento de usuários específicos, crie uma tarefa separada em que o campo
consentdo jobcustomer_match_user_list_metadatae adicione identificadores para esses usuários usando operaçõescreatepara esse job separado.Adicione operações usando o
OfflineUserDataJobService.AddOfflineUserDataJobOperations. Recomendamos adicionar até 10.000 identificadores no total em uma única chamada para o processamento ideal. Uma única solicitaçãoAddOfflineUserDataJobOperationspode conter no máximo 100.000 identificadores em todas objetosUserDatana lista de operações.Por exemplo, se cada um dos seus objetos
UserDatativer umUserIdentifierparahashed_emaile outroUserIdentifierporhashed_phone_number, depois enviar 5.000 objetosUserDatapor solicitação é o ideal,porque cada solicitação conterá 10.000 identificadores de usuário no total.Repita a etapa anterior até adicionar todas as operações ou até que a tarefa seja na capacidade máxima. Não há limites para o número de operações que podem ser adicionadas a um um único emprego; No entanto, recomendamos no máximo 1.000.000 de operações por job. para o processamento ideal.
Execute o job.
A enquete foi enviada corretamente.
Verifique a taxa de correspondência.
Segmente a lista.
Off-lineUserDataJobService e UserDataService
Há dois serviços disponíveis para fazer o upload dos dados da Segmentação por lista de clientes. Selecione o com base no seu caso de uso, já que pode haver limitações para um serviço.
| Serviços de upload da Segmentação por lista de clientes | |
|---|---|
OfflineUserDataJobService (preferencial)
|
A maioria dos desenvolvedores usa esse serviço. Ele é otimizado para uploads grandes com alta capacidade de processamento e retorna métricas de sucesso após a conclusão. Este guia se concentra principalmente nesse serviço. |
UserDataService
|
Este serviço é otimizado para fazer upload de um pequeno número de identificadores por vez.
com atualizações esporádicas e não está otimizada para execução contínua. Tem um limite
de 10 operações por solicitação. Além disso, uma única solicitação não pode conter mais
de 100 itens no total em todos
user_identifiers
Para orientações sobre envios para esse serviço, acesse o guia para gerenciar a integração da Segmentação por lista de clientes. A partir da versão v15 do
a API do Google Ads, você deve preencher
|
Práticas recomendadas
Lembre-se das seguintes práticas recomendadas ao criar a Segmentação por lista de clientes integração:
Não tente usar várias contas para modificar uma única lista de usuários. Um usuário só pode ser modificada pelo serviço do Google Ads ou dados do parceiro que que o criou.
Maximize o número de operações por
AddOfflineUserDataJobOperationsRequest, até 100.000 identificadores, a evitarRESOURCE_EXHAUSTEDerros.Não misture as operações
createeremovena mesmaOfflineUserDataJob. Isso pode resultam em umaCONFLICTING_OPERATIONerro.Ativar
partial_failureem umaAddOfflineUserDataJobOperationsRequestpara detectar operações problemáticas antes de executar o job. As operações são validadas quando são enviadasOfflineUserDataJobEvite executar simultaneamente várias Os processos do
OfflineUserDataJobque modificar a mesma lista de usuários (ou seja, vários trabalhos cujaCustomerMatchUserListMetadata.user_listapontar para o mesmo nome de recurso). Isso pode resultar em um erroCONCURRENT_MODIFICATIONporque não é permitido que vários trabalhos operem na mesma lista em ao mesmo tempo. Esse erro também pode ocorrer ao tentar realizar modificar uma lista na interface e na API Google Ads. Isso não se aplicam à adição de linha de comando para umaPENDING, que pode ser feito a qualquer momento antes do início do job.Se você tem milhares de operações para aplicar, crie uma
OfflineUserDataJobcontendo todas as operações. Não crie várias jobs com apenas algumas centenas de operações cada e os executar sequencialmente ou ao mesmo tempo. Um único job grande com todas as operações está muito distante mais eficiente do que várias tarefas pequenas e reduz as chances de você encontrar erros no seu fluxo de trabalho.
Para ver ideias sobre como aproveitar suas listas de clientes para uma segmentação ideal, acesse Central de Ajuda.
Criar uma lista de clientes
Primeiro, crie uma lista de clientes com o
UserListService As listas de clientes são criadas
definindo o
crm_based_user_list na
objeto user_list. O campo crm_based_user_list pode ser definido em tipos de campanha
compatíveis com a segmentação de listas de clientes:
| Segmentação por lista de clientes em diferentes tipos de campanha | |
|---|---|
| Rede de pesquisa | Os anúncios aparecem na rede de pesquisa. |
| Rede de Display | Os anúncios aparecem na Rede de Display e no Gmail apenas se houver PPG criativos. |
| Inclusão da Rede de Display em campanhas de pesquisa | Os anúncios aparecem na rede de pesquisa e no Gmail apenas se houver PPG criativos. |
| Campanhas de vídeo | Os anúncios só vão aparecer no YouTube se houver anúncios TrueView in-stream. |
| Campanhas do Shopping | Os anúncios aparecem na guia "Shopping". |
crm_based_user_list contém três campos:
app_id: uma string que identifica de forma exclusiva o app para dispositivos móveis do qual o dados foram coletados. Isso é necessário ao criarCrmBasedUserListpara fazer upload de códigos de publicidade para dispositivos móveis.upload_key_typeUm tipo de chave correspondente da lista, que pode serCONTACT_INFO,CRM_IDouMOBILE_ADVERTISING_ID. Tipos de dados mistos não são permitidos na mesma lista. Este campo é obrigatório para todas as listas de clientes.data_source_typeA fonte de dados da lista. O valor padrão éFIRST_PARTY. Na lista de permissões os clientes podem criar listas de clientes de terceiros.
O membership_life_span
da lista de usuários permite definir o período, em dias, para o qual uma
usuário é considerado parte da lista. Com os tipos de lista de clientes, você pode definir
membership_life_span a 10.000 para indicar que não há expiração.
O atributo membership_status
define se a lista aceita novos usuários.
Exemplo de código para criar uma lista de clientes
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.V17.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::V17::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::V17::Common::CrmBasedUserListInfo->new({
uploadKeyType => CONTACT_INFO
})});
# Create the user list operation.
my $user_list_operation =
Google::Ads::GoogleAds::V17::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;
}
Adicionar dados de clientes
As três chaves de correspondência principais são endereço de e-mail, endereço de correspondência e telefone número É possível usar o ID do usuário e o ID do dispositivo móvel como chaves de correspondência, mas essas soluções são menos preparadas para o futuro por dependerem de cookies e dispositivos ID. Recomendamos fazer upload das informações de contato dos usuários, como endereço de e-mail, endereço de correspondência e número de telefone, quando possível, em vez de usar o CRM ou o celular do Google Ads.
Cada lista de usuários pode conter apenas um tipo de dados de clientes, conforme especificado por
as
CrmBasedUserListInfo.upload_key_type
. Além disso, um objeto UserData, que
representa um único usuário e pode conter até 20 identificadores de usuário, sendo que cada um
tem o próprio objeto UserIdentifier. Mais de 20 identificadores resulta em um
TOO_MANY_USER_IDENTIFIERS
erro.
O Google Ads só usará uma lista de usuários segmentados por lista de clientes se ela atender a um limite mínimo de usuários ativos no momento em que o anúncio é veiculado; usuários ativos é o número de usuários na sua lista que estão ativos no Gmail, na Pesquisa Google, no YouTube ou Tela. Envie pelo menos 5.000 membros para aumentar a chance de ter vídeos suficientes de usuários ativos e correspondentes para segmentação.
Fazer upload dos dados de contato do usuário
Para fazer o upload de endereços de e-mail, endereços de correspondência ou números de telefone de usuários, defina
upload_key_type para CONTACT_INFO. Observe que os dados de contato devem ser
associadas a uma Conta do Google para correspondência, e o
de contas, como o Google Workspace, não podem ser segmentadas.
Por questões de privacidade, endereços de e-mail, nomes, sobrenomes e telefones Os números precisam ser criptografados com hash usando o algoritmo SHA-256 antes do upload. Em Para padronizar os resultados do hash, antes de fazer o hash de um desses valores, execute as seguintes tarefas:
- Remova os espaços em branco à esquerda e à direita.
- Para nomes, endereços de e-mail e endereços de correspondência: converta o texto em letras minúsculas.
- Para números de telefone: converta cada número de telefone para E164
formato antes do hash. Esse formato representa
Um número de telefone com até 15 dígitos, começando com
+por exemplo,+12125650000ou+442070313000. Os principais+pode ser omitido.
Para endereços de e-mail, não é necessário remover todos os pontos (.) que antecedem o
nome de domínio no domínio gmail.com e googlemail.com endereços de e-mail, já que são
ainda é aceito.
Se os dados de contato não estiverem formatados corretamente antes do hash, a API ainda aceita as informações com hash, mas não é possível fazer a correspondência delas com um cliente.
Se você quiser fazer o upload de dados de endereço de correspondência, precisará incluir pelo menos:
- Código do país
- Código postal
- Nome com hash
- Sobrenome com hash
Se algum desses campos estiver ausente, não será possível encontrar uma correspondência para o endereço.
Embora as listas de clientes possam conter apenas um upload_key_type, vários tipos de
dados de contato podem ser enviados para um upload_key_type de CONTACT_INFO.
Isso é recomendado para taxas de correspondência maiores.
Fazer upload dos IDs de CRM
Para preencher a lista de clientes com IDs de CRM, defina upload_key_type como
CRM_ID.
Os IDs de CRM são correspondentes a um ID do usuário gerado e atribuído pelo anunciante.
Isso é semelhante ao upload de instâncias MOBILE_ADVERTISING_ID, mas você
preencha o campo third_party_user_id do objeto UserIdentifier.
Fazer upload de IDs de dispositivos móveis
Assim como na Segmentação por lista de clientes com e-mails, é possível fazer a Segmentação por lista de clientes usando
Identificador de publicidade (IDFA) ou dispositivo móvel com o ID de publicidade do Google (AAID)
do Google Ads. Para fazer isso, especifique a propriedade app_id.
e defina upload_key_type como
MOBILE_ADVERTISING_ID
antes de usar uma lista de usuários para a correspondência de clientes com IDs de dispositivos móveis.
Exemplo de código
O exemplo a seguir usa um OfflineUserDataJobOperation para anexar ao cliente
informações de contato para uma lista de clientes.
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::V17::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::V17::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::V17::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::V17::Common::UserIdentifier->new({
addressInfo =>
Google::Ads::GoogleAds::V17::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::V17::Common::UserData->new({
userIdentifiers => [$user_identifiers]});
push(
@$operations,
Google::Ads::GoogleAds::V17::Services::OfflineUserDataJobService::OfflineUserDataJobOperation
->new({
create => $user_data
}));
}
}
Verificar o upload da lista e a taxa de correspondência
Depois que o OfflineUserDataJob tiver um SUCCESS
status, a taxa de correspondência estimada será
disponíveis no
operation_metadata.match_rate_range
. Se você consultar esse campo antes da conclusão do job, o valor do campo
pode ser zero. Para garantir que sua taxa de correspondência esteja pronta para verificação, e a lista
prontos para segmentação, recomendamos consultar a conclusão do job. Pode levar tanto
de 10 minutos a 24 horas para a conclusão do trabalho.
Exemplo de código para verificar o status da tarefa
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.V17.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::V17::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;
}
Para verificar o tamanho da lista, consulte o
user_list.
Exemplo de código para consultar o recurso 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.V17.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::V17::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
});
Para fins de privacidade, o tamanho da lista de usuários é mostrado como zero até que a lista tenha em ter pelo menos 1.000 membros. Depois disso, o tamanho é arredondado para os dois valores dígitos.
É possível buscar erros durante a execução de um OfflineUserDataJob usando
as
offline_user_data_job
recurso usando a linguagem de consulta do Google Ads. No entanto, esse relatório não contém
informações sobre quaisquer correspondências com falha, já que somente os hashes são comparados
realizar correspondências. Consulte a solução de problemas
guia se você
encontrar problemas nas listas de clientes.
Comparar com a interface do Google Ads
Uma lista pode aparecer menor do que o esperado quando visualizada no Gerenciador de públicos-alvo na interface do Google Ads. Essa visualização mostra o número de usuários ativos na lista. Para mais informações, consulte esta solução de problemas guia.
Como pode levar até 24 horas para que uma lista seja preenchida com membros,
talvez apareça um erro In Progress
status na interface do Google Ads se você
fazer o upload para uma lista de público-alvo com mais frequência do que uma vez a cada 12 horas.
Segmentar minha lista
Você pode segmentar sua lista no nível do grupo de anúncios ou da campanha. O é similar a outros tipos de critérios de segmentação na API.
Exemplo de código para segmentar anúncios em um grupo de anúncios para uma lista de usuários
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.V17.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::V17::Resources::AdGroupCriterion->new({
adGroup => Google::Ads::GoogleAds::V17::Utils::ResourceNames::ad_group(
$customer_id, $ad_group_id
),
userList => Google::Ads::GoogleAds::V17::Common::UserListInfo->new({
userList => $user_list_resource_name
})});
# Create the operation.
my $ad_group_criterion_operation =
Google::Ads::GoogleAds::V17::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;
}
Segmentar várias listas de clientes
Um crm_based_user_list só pode ser combinado com outro crm_based_user_list
ao usar um logical_user_list.
Todas as políticas de crm_based_user_list se aplicam à lista de usuários resultante.