Mapeamentos de campo

Use os mapeamentos de campo para fazer upgrade de cada etapa do seu fluxo de trabalho da Segmentação por Lista de Clientes, da API Google Ads para a API Data Manager:

Autenticação

A API Data Manager exige credenciais com um escopo diferente da API Google Ads. Siga as etapas em Configurar o acesso à API para gerar novas credenciais que incluam o escopo da API Data Manager.

Mapeamentos de campo de gerenciamento de público-alvo

Use os mapeamentos nas tabelas para mapear um UserList na API Google Ads para o equivalente em UserList na API Data Manager.

UserList (API Google Ads) UserList (API Data Manager) Observações
resource_name name Consulte Nomes de recursos para mais detalhes.
id id
read_only read_only
name display_name Obrigatório
description description Obrigatório
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

O período em que um membro do público-alvo permanece na lista depois de ser adicionado. O valor precisa corresponder a dias inteiros. Se não for definido, o padrão será o máximo.

Formate o valor usando o formato de carimbo de data/hora.
size_for_display size_info.display_network_members_count
size_range_for_display Não há equivalente. Use o atributo size_info.display_network_members_count para informações de tamanho.
size_for_search size_info.search_network_members_count
size_range_for_search Não há equivalente. Use o atributo size_info.search_network_members_count para informações de tamanho.
type Não há equivalente.
access_reason access_reason
account_user_list_status account_access_status
closing_reason closing_reason
eligible_for_search target_network_info.eligible_for_search
eligible_for_display target_network_info.eligible_for_display
match_rate_percentage ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list ingested_user_list_info.pseudonymous_id_info Não é usado para a Segmentação por Lista de Clientes.
crm_based_user_list ingested_user_list_info Obrigatório. Consulte as informações sobre o público-alvo segmentado por lista de clientes.
Não há equivalente. ingested_user_list_info.pair_id_info Não é usado para a Segmentação por Lista de Clientes.
Não há equivalente. ingested_user_list_info.partner_audience_info Não é usado para a Segmentação por Lista de Clientes.
logical_user_list Não há equivalente. Não é usado para a Segmentação por Lista de Clientes.
logical_user_list Não há equivalente. Não é usado para a Segmentação por Lista de Clientes.
lookalike_user_list Não há equivalente. Não é usado para a Segmentação por Lista de Clientes.
rule_based_user_list Não há equivalente. Não é usado para a Segmentação por Lista de Clientes.
similar_user_list Não há equivalente. Não é usado para a Segmentação por Lista de Clientes.

Informações sobre o público-alvo segmentado por lista de clientes

Na API Google Ads, é preciso definir o campo crm_based_user_list como um CrmBasedUserListInfo ao criar um público-alvo segmentado por lista de clientes.

Na API Data Manager, defina os atributos equivalentes configurando o campo ingested_user_list_info como um IngestedUserListInfo e, em seguida, defina os campos obrigatórios para a Segmentação por Lista de Clientes e o tipo de dados do usuário.

Dados de contato

upload_key_types
Defina como uma lista que contém CONTACT_ID. Isso equivale a definir o upload_key_type como CONTACT_INFO na API Google Ads.
contact_id_info

Defina como um ContactIdInfo.

Defina data_source_type como DATA_SOURCE_TYPE_FIRST_PARTY. Isso equivale a definir data_source_type como FIRST_PARTY na API Google Ads.

IDs digitais

upload_key_types
Defina como uma lista que contém MOBILE_ID. Isso equivale a definir o upload_key_type como MOBILE_ADVERTISING_ID na API Google Ads.
mobile_id_info

Defina como um MobileIdInfo.

  • Defina data_source_type como DATA_SOURCE_TYPE_FIRST_PARTY. Isso equivale a definir data_source_type como FIRST_PARTY na API Google Ads.
  • Defina key_space para IOS ou ANDROID. A API Data Manager exige esse valor. Isso é diferente da API Google Ads, em que o espaço de chave é inferido do app_id.
  • Defina app_id como a string que identifica exclusivamente o aplicativo para dispositivos móveis de onde os dados foram coletados. Use o mesmo formato que você usa para o app_id na API Google Ads.

User-IDs

upload_key_types
Defina como uma lista que contém USER_ID. Isso equivale a definir o upload_key_type como CRM_ID na API Google Ads.
user_id_info

Defina como um UserIdInfo.

Defina data_source_type como DATA_SOURCE_TYPE_FIRST_PARTY. Isso equivale a definir data_source_type como FIRST_PARTY na API Google Ads.

Nomes de recursos

A API Data Manager usa um formato de nome de recurso diferente da API Google Ads.

API Google Ads

Na API Google Ads, um nome de recurso UserList usa o formato:

customers/{customer_id}/userLists/{user_list_id}

API Data Manager

Na API Data Manager, um nome de recurso UserList usa o formato:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

Fazer upload de mapeamentos de campo

Use os mapeamentos nas tabelas para mapear um AddOfflineUserDataJobOperationsRequest na API Google Ads para a solicitação IngestionService equivalente na API Data Manager.

Campos de solicitação

Esses mapeamentos usam o IngestAudienceMembersRequest na API Data Manager como referência, mas você também pode usá-los se estiver convertendo sua solicitação da API Google Ads em um RemoveAudienceMembersRequest ou um RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (API Google Ads) IngestAudienceMembersRequest (API Data Manager) Observações
  • Campo customer_id
  • Campo customer_match_user_list_metadata de OfflineUserDataJob
  • Cabeçalho da solicitação developer-token
  • Cabeçalho da solicitação login-customer_id
  • Cabeçalho da solicitação linked-customer-id
 destinations Consulte Campos de cliente e público-alvo.
consent do customer_match_user_list_metadata de OfflineUserDataJob consent Configurações de consentimento padrão opcionais para membros do público-alvo na solicitação. É possível modificar esse valor para um membro individual do público-alvo definindo o campo consent de AudienceMember.
Não há equivalente encoding Obrigatório:defina como o Encoding usado para valores de UserIdentifier.
Não há equivalente encryption_info Defina se a solicitação contém valores criptografados. Consulte Criptografia para mais detalhes.
job_id Não há equivalente Use o request_id retornado na resposta para recuperar diagnósticos.
enable_partial_failure Não há equivalente A API Data Manager usa um modelo de erro de falha rápida. Se algum campo de um IngestAudienceMembersRequest falhar na validação, a API Data Manager vai rejeitar toda a solicitação. Recupere erros de processamento usando diagnósticos.
enable_warnings Não há equivalente A API Data Manager não informa avisos na resposta. Recupere avisos de processamento usando diagnósticos.
validate_only validate_only
operations audience_members A lista de membros do público-alvo que serão adicionados ou removidos. Consulte a seção de campos de operação para mais detalhes.
Não há equivalente terms_of_service Obrigatório. Defina para indicar que o usuário aceitou ou rejeitou os Termos de Serviço da Segmentação por Lista de Clientes.

Campos de cliente e público-alvo

A API Google Ads só permite o upload de membros do público-alvo para um público-alvo por job.Além disso, o cabeçalho da solicitação developer-token é obrigatório, e você define os cabeçalhos da solicitação login-customer-id e linked-customer-id para diferentes cenários de autenticação.

A API Data Manager permite enviar membros do público-alvo para vários públicos-alvo em uma única solicitação. A API Data Manager não exige um token de desenvolvedor, e você especifica as informações de login e do cliente vinculado usando campos de um Destination em vez de cabeçalhos de solicitação. Confira Configurar destinos para mais informações sobre destinos.

Na API Google Ads, é possível remover todos os membros de um público-alvo definindo o campo remove_all de um OfflineUserDataJobOperation como true.

Na API Data Manager, isso é feito enviando um RemoveAllAudienceMembersRequest. Consulte o guia Remover todos os participantes para mais detalhes.

Veja como mapear os campos da API Google Ads para um único público-alvo com os campos equivalentes em um Destination:

API Google Ads Destination (API Data Manager) Observações
customer_id da solicitação operating_account Defina o account_id como o ID de cliente do público-alvo. Defina o account_type do operating_account como GOOGLE_ADS.
Cabeçalho da solicitação developer-token Não há equivalente Não é necessário um token de desenvolvedor para a API Data Manager.
Cabeçalho da solicitação login-customer-id login_account Defina account_id como o ID de cliente da conta de login. Defina account_type como GOOGLE_ADS se a conta de login for uma conta do Google Ads ou como DATA_PARTNER se for uma conta de parceiro de dados.
Cabeçalho da solicitação linked-customer-id linked_account Se você estiver acessando o operating_account usando um link de parceiro, defina o account_id como o ID de cliente da conta vinculada e defina account_type como DATA_PARTNER. Caso contrário, não defina o campo linked_account.
user_list do customer_match_user_list_metadata de OfflineUserDataJob product_destination_id Obrigatório. Defina como o ID numérico do público-alvo. Não use o nome do recurso do UserList.
Não há equivalente reference Um identificador definido pelo usuário para o Destination. Defina esse campo se você estiver enviando membros de vários públicos-alvo em uma única solicitação.

Campos de operação

A API Data Manager contém métodos separados para adicionar e remover membros do público-alvo. Por outro lado, o AddOfflineUserDataJobOperationsRequest na API Google Ads contém uma lista de operations, cada um adicionando um membro, removendo um membro ou removendo todos os membros com base no tipo de operação. Confira o mapeamento de cada tipo de operação para o método correspondente na API Data Manager:

OfflineUserDataJobOperation (API Google Ads) Método IngestionService (API Data Manager) Observações
create IngestAudienceMembers Consulte a seção de campos de membros do público-alvo para mais detalhes.
remove RemoveAudienceMembers Consulte a seção de campos de membros do público-alvo para mais detalhes.
remove_all RemoveAllAudienceMembers Consulte Remover todos os membros do público-alvo para mais detalhes.

Campos de membros do público-alvo

UserData (API Google Ads) AudienceMember (API Data Manager) Observações
consent consent

Defina para especificar o consentimento do membro do público-alvo.

As duas APIs usam um objeto Consent semelhante (ad_user_data, ad_personalization).

Para a API Data Manager, também é possível definir o consentimento para todos os membros do público-alvo em uma solicitação, definindo o campo consent no nível da solicitação.
transaction_attribute Não há equivalente. Não relevante para a Segmentação por Lista de Clientes.
user_attribute Não há equivalente. Não relevante para a Segmentação por Lista de Clientes.
user_identifiers
  • mobile_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

Preencha o campo que corresponde ao tipo de dados que você está enviando para os membros do público-alvo. Consulte Campos de identificador de usuário para mais detalhes.

Campos do identificador de usuário

Na API Google Ads, use UserIdentifier para enviar dados de contato, IDs de dispositivos móveis ou IDs de usuários. A API Data Manager usa uma abordagem diferente, com campos diferentes para cada tipo de dados.

Na API Data Manager, preencha o campo que corresponde ao tipo de dados que você está enviando:

Dados de contato

Se você usar dados de contato, como endereço de e-mail, número de telefone ou endereço, defina composite_data como um CompositeData com uma entrada separada em user_data.user_identifiers para cada item de dados de contato.

Embora o user_data ainda seja compatível, recomendamos o uso de composite_data para garantir que sua integração esteja preparada para melhorias futuras. Consulte Dados compostos para mais detalhes.

UserIdentifier (API Google Ads) UserIdentifier (API Data Manager) Observações
address_info address Consulte Campos de endereço para mais detalhes.
hashed_email email_address Defina como o endereço de e-mail formatado e com hash. Também é possível criptografar o endereço de e-mail com hash.
hashed_phone_number phone_number Defina como o número de telefone formatado e com hash. Também é possível criptografar o número de telefone com hash.
user_identifier_source Não há equivalente.

Campos de endereço

Confira os mapeamentos de campos entre OfflineUserAddressInfo na API Google Ads e AddressInfo na API Data Manager. Use esses mapeamentos se você estiver usando dados de contato para preencher seu público-alvo segmentado por lista de clientes.

OfflineUserAddressInfo (API Google Ads) AddressInfo (API Data Manager) Observações
city Não há equivalente.
country_code region_code Obrigatório
hashed_first_name given_name

Obrigatório. Defina como o nome formatado e com hash. Também é possível criptografar o nome com hash.
hashed_last_name family_name

Obrigatório. Defina como o sobrenome formatado e com hash. Também é possível criptografar o nome de família com hash.
hashed_street_address Não há equivalente.
postal_code postal_code Obrigatório
state Não há equivalente.

Endereço IP

A API Data Manager permite incluir endereços IP para uploads da Segmentação por Lista de Clientes, além de identificadores de usuário. Eles são fornecidos em CompositeData, que agrupa UserData e IpData. Fornecer esses campos juntos pode ajudar a melhorar as taxas de correspondência.

Consulte Ingestão de IP para Segmentação por Lista de Clientes para mais detalhes.

API Google Ads CompositeData (API Data Manager) Observações
Não há equivalente. ip_data.ip_address Defina como o endereço IPv4 ou IPv6 bruto. Consulte as orientações sobre o formato do endereço IP.
Não há equivalente. ip_data.observe_start_time Defina como o carimbo de data/hora no formato RFC 3339 quando o endereço IP foi observado pela primeira vez.
Não há equivalente. ip_data.observe_end_time Defina como o carimbo de data/hora no formato RFC 3339 quando o endereço IP foi observado pela última vez.
user_identifiers user_data Defina como um objeto UserData.

IDs digitais

Se estiver usando IDs digitais, defina mobile_data como um MobileData com uma entrada em mobile_ids para cada ID.

UserIdentifier (API Google Ads) MobileData (API Data Manager) Observações
mobile_id mobile_ids Defina como a lista de IDs digitais do membro do público-alvo.

Na API Google Ads, você adiciona um UserIdentifier separado com mobile_id para cada ID digital do membro do público-alvo. Na API Data Manager, adicione um único MobileData com mobile_ids definido como a lista de todos os IDs digitais do membro do público-alvo.

user_identifier_source Não há equivalente.

User-IDs

Se você estiver usando IDs de usuário, defina user_id_data como um UserIdData e user_id como o ID do usuário para o membro do público-alvo.

UserIdentifier (API Google Ads) UserIdData (API Data Manager) Observações
third_party_user_id user_id

Na API Google Ads, você adiciona um UserIdentifier separado com third_party_user_id para cada ID do usuário do membro do público-alvo.

Na API Data Manager, defina o campo user_id_data como um UserIdData e o campo user_id como o ID do usuário do membro do público-alvo. Não é possível enviar vários IDs de usuário para o mesmo membro do público-alvo.

user_identifier_source Não há equivalente.
Anterior
Etapas para o upgrade