Acompanhamento de conversões de app e remarketing: especificações de solicitação/resposta

User agent do app

Como parte dos nossos esforços mais amplos para combater o spam, desenvolvemos uma especificação padronizada para o cabeçalho User-Agent enviado por um produto de análise/anúncios em nome de um usuário de app. O user agent do app pode ser derivado do código nativo para aderir à seguinte especificação:

name version (os_and_version; locale; device; build; Proxy)

A definição desses campos é a seguinte:

Componentes do user agent
name

O nome do produto de análise/anúncios. (Google AdMob)

Observação: se o user agent for construído no lado do cliente, name será o ID do pacote do app cliente.

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
version

A versão do produto de análise/anúncios. (7.10.1)

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
os_and_version

O sistema operacional e a versão em que o app está sendo executado. (Android 6.0 )

Android
String osAndVersion =
    "Android " + Build.VERSION.RELEASE;
iOS
UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];
locale

Uma tag de localidade IETF para o dispositivo, usando o código de idioma e do país de duas letras separados por um sublinhado. (en_US)

Android
String locale = Locale.getDefault();
iOS
NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]
device

O nome do dispositivo físico que executa o produto de análise/anúncios. (iPhone9,1)

Android
String device = Build.MODEL;
iOS
@import Darwin.sys.sysctl;

NSString *device(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("hw.machine",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}
build

"Build/" seguido pelo número da versão do sistema operacional. (Build/13D15)

Android
String build = "Build/" + Build.ID;
iOS
@import Darwin.sys.sysctl;

NSString *build(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("kern.osversion",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}

Inclua apenas ; Proxy no final do user agent do app ao construir o user agent do app no lado do servidor. Se o user agent do app for totalmente construído no lado do cliente, exclua ; Proxy. Assim, um user agent de app pode ser:

  • Android: AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
  • iOS: AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)

Guia de solicitação do acompanhamento de conversões

A finalidade das solicitações de acompanhamento de conversões é notificar o Google Ads sobre um evento de app que deve ser acompanhado como uma conversão e/ou usado para preencher uma lista de remarketing, além de recuperar metadados que descrevem qualquer clique anterior ao evento.

Todas as chamadas de API são feitas para o domínio www.googleadservices.com. As solicitações de conversão são solicitações POST via HTTPS no seguinte caminho: 

/pagead/conversion/app/version
em que version é a versão pretendida da API Conversion Tracking.

Uma solicitação de conversão de app padrão vai conter os seguintes parâmetros para a API App Conversion v1.1.

Solicitação de acompanhamento de conversões
dev_token

Obrigatório

Localização: consulta

O token de desenvolvedor estático e exclusivo emitido para o consumidor da API.

Z_eErE4DkvcKjDM1OVE4c4
link_id

Obrigatório

Localização: consulta

A vinculação do identificador de link que associa o token de desenvolvedor do consumidor da API a um app específico.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

Obrigatório

Localização: consulta

O nome do evento do app que ocorreu. Esse campo é uma enumeração e só aceita os seguintes valores:

 • first_open
 • session_start
 • in_app_purchase
 • view_item_list
 • view_item
 • view_search_results
 • add_to_cart
 • ecommerce_purchase
 • custom

O evento first_open sempre deve ser enviado para atribuir instalações, e o evento session_start sempre deve ser enviado para reatribuir sessões. Use in_app_purchase para compras feitas na app store nativa e ecommerce_purchase para todas as outras compras.
app_event_name

Obrigatório sob certas condições

Localização: consulta

O nome de qualquer evento de app personalizado que não seja aceito no campo app_event_type. Esse campo precisa conter de 1 a 64 caracteres Unicode (usando a codificação UTF-8). Este campo é obrigatório se app_event_type for personalizado.

level_achieved
Level Achieved

Esse campo não pode conter nenhum dos valores reservados para app_event_type. Se um nome de evento reservado for usado, a API vai retornar um erro APP_EVENT_NAME_RESERVED_VALUE.
app_event_data

Opcional

Local: corpo

Encaminhe outros dados de eventos avançados como um objeto JSON simples que mapeia chaves de string para valores. Os valores aceitáveis são strings e matrizes de strings.

{"level": 5, "attempts": 20}
odm_info

Obrigatório ao usar a medição integrada de conversões no iOS

Localização: consulta

O valor do parâmetro de consulta info, capturado na instalação ou reinstalação do app iOS pelo SDK de dados de eventos da medição no dispositivo (ODM) do Google. Esse campo ativa a medição integrada de conversões em campanhas para apps iOS.

XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL
FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg
_CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23
id_type

Obrigatório

O tipo de identificador transmitido no campo rdid.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

Obrigatório

Localização: consulta

Uma string UUID válida que representa o ID bruto do dispositivo.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

Se o ID do dispositivo estiver faltando, como o ID de um usuário que não consentiu com a ATT, defina como zero.

00000000-0000-0000-0000-000000000000
ctry_c

Obrigatório

Localização: consulta

Código do país ISO de duas letras para indicar o país de origem da conversão.

Esse campo é obrigatório para ativar a medição de conversões de app fora do nível do usuário no iOS e no Android.

US, IN
eea

Obrigatório sob certas condições

Localização: consulta

O escopo do EEE.

0: as regulamentações europeias não se aplicam a este usuário e conversão.

1: as regulamentações europeias se aplicam a este usuário e conversão. Por exemplo, se um usuário estiver localizado no EEE, ele estará no escopo das regulamentações europeias aplicáveis. 

*Required to be sent when the value is known.
ad_personalization

Obrigatório sob certas condições

Localização: consulta

As flags para anúncios personalizados

0: o usuário final negou o consentimento para a personalização de anúncios

1: o usuário final deu consentimento para a personalização de anúncios 

*Required to be sent when the value is known.
ad_user_data

Obrigatório sob certas condições

Localização: consulta

A flag de consentimento para uso de dados do usuário para fins de publicidade.

0: o usuário negou o consentimento para transmissão de dados no nível do usuário ao Google para fins de publicidade.

1: o usuário concedeu o consentimento para transmissão de dados no nível do usuário ao Google para fins de publicidade. 

*Required to be sent when the value is known.
lat

Obrigatório

Localização: consulta

Status de limitação do rastreamento de anúncios para o dispositivo.

  • 0: o usuário não escolheu limitar o rastreamento de anúncios.
  • 1: o usuário escolheu limitar o rastreamento de anúncios.
app_version

Obrigatório

Localização: consulta

A versão atual do app. Ela precisa ser padronizada da seguinte forma:

Android

packageManager.getPackageInfo(packageName(),
  PackageManager.GET_META_DATA).versionName

iOS

[[[NSBundle mainBundle] infoDictionary]
  objectForKey:@"CFBundleShortVersionString"]
 
1.2.4
os_version

Obrigatório

Localização: consulta

A versão atual do SO do host do app. Isso deve ser padronizado da seguinte forma.

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

Obrigatório

Localização: consulta

A versão do SDK que mediu o evento. Como isso é usado principalmente para depuração, ele precisa refletir a versão de lançamento exatamente como é publicada com as versões do SDK. Se o app não usar um SDK, transmita o mesmo valor de app_version.

1.9.5r6
timestamp

Obrigatório

Localização: consulta

O carimbo de data/hora UNIX em que o evento de conversão ocorreu, em segundos com precisão de microssegundos.

1432681913.123456
fot

Obrigatório

Localização: consulta

O carimbo de data/hora UNIX do first_open correspondente em segundos com precisão de microssegundos para todas as sessões subsequentes e eventos pós-instalação.

1432681913.123456
value

Opcional

Localização: consulta

O valor monetário do evento, se houver. Ele sempre precisa ser formatado como um valor de ponto flutuante legível por máquina usando um ponto decimal para separar a parte inteira e fracionária do valor.

1.99
currency_code

Obrigatório sob certas condições

Localização: consulta

O código de moeda ISO 4217 para o parâmetro value. Este campo é obrigatório se o parâmetro value for fornecido e não estiver em branco.

USD
gclid

Obrigatório sob certas condições

Localização: consulta

O valor do parâmetro de consulta gclid de um URL de link direto que abriu o app.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

Obrigatório sob certas condições

Localização: consulta

O valor do parâmetro de consulta gclid de um URL de link direto capturado do valor "install_referrer" pela API Play Install Referrer.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

Obrigatório sob certas condições

Localização: consulta

Identificador para atribuição baseada em gclid em cenários em que o rdid (advertisingid) não está not disponível ou todos os zeroes E gclid ou market_referrer_gclid estão presentes.

1
gbraid

Obrigatório sob certas condições

Localização: consulta

Valor gbraid visto por último enviado pelo URL de link direto que abriu o app. Observe que isso precisa ser armazenado em cache no app para que possa ser enviado com as conversões futuras que acontecem no app.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

Obrigatório sob certas condições

Localização: consulta

Valor para identificar o link direto de clique no anúncio ou as sessões orgânicas do app.

ad_click or organic
User-Agent

Obrigatório

Localização: cabeçalho

O user agent do app, conforme definido na seção anterior.

AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)
X-Forwarded-For

Obrigatório

Localização: cabeçalho

O endereço IPv4 ou IPv6 público do dispositivo em que o evento foi medido.

216.58.194.174

Todas as solicitações precisam ser enviadas via HTTPS. Os pings recebidos por HTTP serão rejeitados.

Se o corpo da solicitação estiver vazio (nos casos em que nenhum dado de evento avançado é transmitido no payload app_event_data), nosso servidor exige que você defina explicitamente o cabeçalho Content-Length: 0 na sua solicitação.

Codificação de dados de eventos

Para o parâmetro de corpo app_event_data, use as seguintes convenções para tipos de dados primitivos:

  • Ponto flutuante

    • Use o ponto como separador decimal, independente da localização do app
    • Use precisão decimal de dois dígitos para representar valores monetários, por exemplo, 2,99.
    • Não use notação exponencial, por exemplo, 2E+9.
    • Não use uma vírgula para separar grupos de dígitos, por exemplo, 1.000.000
    • Exemplos válidos:
      • -0.5
      • 2.99
      • 1000000.123

  • Número inteiro

    • Envie apenas valores inteiros sem dígitos decimais.
    • Não use uma vírgula para separar grupos de dígitos, por exemplo, 1.000.000.
    • Exemplos válidos:
      • 1000
      • -11
      • 0

  • Data

    • Formato da data: aaaa-mm-dd
      • yyyy = ano com quatro dígitos, por exemplo, 2016
      • mm = mês de dois dígitos, por exemplo, 09 para setembro
      • dd = dia de dois dígitos, por exemplo, 23 para o 23º dia do mês
    • Sempre envie o número de dígitos especificado acima. Por exemplo, se você estiver enviando o valor de dd para o 5º dia do mês, envie 05.
    • Exemplos válidos:
      • "2016-09-23"
      • "1990-12-31"

  • Carimbo de data/hora

    • Formato de hora: carimbo de data/hora Unix/época em segundos definido no fuso horário UTC com precisão de microssegundos
    • Exemplos válidos:
      • 1478713087 para Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 para Wed, 07 Jan 2004 22:19:42.123 GMT

  • Matrizes

    • Envie apenas matrizes de valores primitivos (strings, números e booleanos)
    • Exemplos válidos:
      • [123, 456, 789]
      • ["abc"]

Exemplos de solicitações

Um exemplo de solicitação de primeiro acesso com o SDK de medição no dispositivo: dados de eventos para medição de conversões integrada é:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Um exemplo de solicitação de primeiro acesso sem o SDK de medição no dispositivo: dados de eventos para medição de conversões integrada é:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Um exemplo de solicitação pós-instalação com o SDK de medição no dispositivo: dados de eventos para medição integrada de conversões é:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &&fot=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Um exemplo de uma solicitação de primeira abertura sem o SDK On Device Measurement: Event Data é:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Um exemplo de solicitação de primeiro acesso para uma conversão não determinista do Android para a ACAPI v1.1 é:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=appsetid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &ctry_c=IN
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (android 11; en-GB; RMX2040; Build/_; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Exemplo de uma solicitação válida de acompanhamento de conversões com um tipo de evento não personalizado e informações de receita:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=0
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

Exemplo de uma solicitação válida de acompanhamento de conversões com um tipo de evento não personalizado e informações de receita com rdid (advertisingid) não disponível:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

Exemplo de uma solicitação válida de início de sessão:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Exemplo de uma solicitação de início de sessão reatribuição válida para uma sessão que começou com o link direto example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Exemplo de uma solicitação de acompanhamento de conversões válida para um usuário do EEE com consentimento de dados do usuário de anúncios concedido e personalização de anúncios recusada:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=1
       &ad_personalization=0
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Guia de respostas do acompanhamento de conversões

A resposta do acompanhamento de conversões tem o seguinte formato:

{
  "ad_events": [<ad event objects>],
  "errors": [<error strings>],
  "attributed": true|false
}

As matrizes ad_events e errors podem estar vazias.

Esperamos que os erros sejam códigos legíveis por máquina, por exemplo, invalid_timestamp.

Códigos de erro

  • invalid_timestamp: a solicitação não tinha um carimbo de data/hora válido.

  • eea_missing_or_invalid: a solicitação não tinha o campo "eea" definido ou era inválida.

  • ad_user_data_missing: o campo de solicitação "ad_user_data" não foi definido. O campo "ad_user_data" é obrigatório para todas as solicitações de DMA no escopo.

  • ad_user_data_invalid: o valor da solicitação "ad_user_data" era inválido. O campo "ad_user_data" é obrigatório para todas as solicitações de DMA no escopo.

  • ad_personalization_missing_or_invalid: a solicitação não tinha o campo "ad_personalization" definido ou ele era inválido. O campo "ad_personalization" é obrigatório para todas as solicitações de DMA no escopo.

Os eventos de anúncio são os objetos principais da atribuição de app e contêm as seguintes propriedades.

Observações importantes sobre o comportamento da resposta dependendo do consentimento do usuário:
Se a conversão tiver consentimento para uso de dados do usuário de anúncios e o usuário tiver consentimento para uso cruzado nas configurações de usuário do Google, o Google Ads vai responder com um único último clique em todas as CPSes. Se o usuário não tiver dado consentimento para o uso cruzado nas configurações de usuário do Google, o Google Ads vai responder com vários últimos cliques, por CPS.

Se a conversão incluir determinados CPSs no consentimento de uso cruzado selecionado pelo usuário, mas não outros, o Google Ads vai responder com um único último clique em todos os CPSs que receberam consentimento de uso cruzado, mas com vários últimos cliques, por CPS, para aqueles que não receberam consentimento de uso cruzado.

Resposta do acompanhamento de conversões
ad_event_id

Sempre presente

string

O ad_event_id serve como um identificador exclusivo para eventos de anúncio. Ele é reutilizado na solicitação de atribuição de várias redes e precisa ser registrado/mantido para fins de depuração.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Sempre presente

string

A métrica de conversão usada para atribuição. Inicialmente, vamos oferecer suporte a uma métrica de conversão.

conversion
timestamp

Sempre presente

número

O carimbo de data/hora UNIX em que o evento de anúncio ocorreu, em segundos com precisão de microssegundos. Esse valor deve ser usado para a atribuição de último clique.

1432681913.123456
campaign_type

Sempre presente

string

Esse campo identifica o tipo de campanha que gerou o evento de anúncio. Os valores possíveis são os seguintes.

ACI
ACE
ACPRE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI é a abreviação de campanha de apps para instalação. ACE é a abreviação de Campanhas de apps para engajamento.
campaign_id

Sempre presente

número

O ID numérico da campanha que gerou o evento de anúncio. Esse valor é garantido como exclusivo.

123456789
campaign_name

Sempre presente

string

O nome da campanha definido pelo anunciante que gerou o evento de anúncio. Esse valor não é garantido como exclusivo.

Occasional Gamers (Video)
ad_type

Sempre presente

string

O tipo de anúncio que resultou no evento de anúncio. Esse valor pode ser usado para distinguir entre vários tipos de inventário da seguinte maneira.

Promoção de app 
ClickToDownload
 Engajamento no app 
AppDeepLink
 Engajamento com o app: fluxo de instalação e continuidade 
AppDeepLinkContinue
 Genérico para outros valores 
Unknown
external_customer_id

Sempre presente

número

O identificador do anunciante proprietário da campanha que gerou o evento de anúncio. Esse valor pode ser usado para diferenciar contas do Google Ads.

123456789
location

Sempre presente

número

O código de ID do local para a localização geográfica do evento de anúncio. Consulte a referência da API Google Ads para interpretar os códigos de local.
network_type

Sempre presente

string

Esse campo identifica a rede de publicidade do Google Ads em que o evento de anúncio ocorreu. Os valores possíveis são os seguintes:

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Será null quando campaign_type for ACI ou ACE e network_type for Display.

string

Esse campo identifica o "subtipo" da rede de publicidade do Google Ads em que o evento de anúncio ocorreu. Os valores possíveis variam de acordo com o tipo de rede principal.

Pesquisa Google comum 
GoogleSearch
 Parceiros de pesquisa do Google 
SearchPartners

Display

Publishers da Web para dispositivos móveis 
mGDN
 Editores de apps 
Google AdMob

YouTube

Rede de vídeos do YouTube 
YouTubeVideos
 Rede de pesquisa do YouTube 
YouTubeSearch
 Parceiros de vídeo 
VideoPartners

GoogleTv

Rede de vídeos do Google TV 
GoogleTvVideos

várias redes

Campanhas Performance Max em várias redes 
cross-network
video_id

Só é fornecido quando network_type é YouTube e campaign_type não é ACI e ACE.

string

O ID do vídeo do YouTube associado ao evento de anúncio.

dQw4w9WgXcQ
keyword

Só é fornecido quando network_type é Search e campaign_type não é ACI e ACE.

string

A palavra-chave da rede de pesquisa associada ao evento de anúncio.

+food +delivery
match_type

Só é fornecido quando network_type é Search e campaign_type não é ACI e ACE.

string

O tipo de correspondência para palavras-chave de pesquisa.

Exata 
e
 Frase 
p
 Ampla 
b
placement

Só é fornecido quando network_type é Display e campaign_type não é ACI e ACE.

string

A posição associada ao evento de anúncio.

mobileapp::1-343200656
ad_group_id

Fornecido apenas quando campaign_type não é Performance_Max.

número

O ID numérico do grupo de anúncios que gerou o evento de anúncio. Esse valor é garantido como exclusivo.

Esse campo não é fornecido para eventos de anúncio atribuídos pela gbraid que são atribuídos de forma determinística (is_deterministic é true), como a atribuição de link direto.

123456789
ad_group_name

Só é fornecido quando campaign_type é ACI, ACE ou ACPRE.

string

O nome do grupo de anúncios definido pelo anunciante que gerou o evento de anúncio. Esse valor não é garantido como exclusivo.

Esse campo não é fornecido para eventos de anúncio atribuídos pela gbraid que são atribuídos de forma determinística (is_deterministic é true), como a atribuição de link direto.

My App AdGroup
asset_group_id

Fornecido somente quando campaign_type é Performance_Max.

número

O ID numérico do grupo de recursos que gerou o evento de anúncio. Esse valor é exclusivo.

123456789
creative_id

Só é fornecido quando campaign_type não é ACI, ACE, ACPRE ou Performance_Max.

número

O ID numérico do bloco de anúncios do criativo que gerou o evento de anúncio. Esse valor é garantido como exclusivo.

123456789
interaction_type

Esse campo sempre será "engagement".

string
is_deterministic

Indica se o método de atribuição é determinista ou não.

Booleano

true, false
device_model

Modelo do dispositivo que gerou o evento de anúncio.

String

sm-s936w, sm-3936w
os_version

A versão principal do SO que gerou o evento de anúncio.

String

14, 12
country

O código de duas letras do país que gerou o evento de anúncio.

String

CA, US
city

A cidade que gerou o evento de anúncio.

String

san jose, london
region

O estado ou a província que gerou o evento de anúncio.

String

california, british columbia

Exemplos de respostas

Exemplo de resposta para uma conversão determinística:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "is_deterministic": true,
    "timestamp": 1234567.898765
  }],
  "errors": [],
  "attributed": true
}

Exemplo de resposta para uma conversão não determinista do iOS:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "is_deterministic": false,
    },
    "device_info": {
        "device_model": "iphone12,3",
        "os_version": "14"
    },
    "timestamp": 1432681918.123456
    }],
  "errors": [],
  "attributed": true
}

Exemplo de resposta para uma conversão não determinista do Android:

{
  "ad_events": [
    {
      "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
      "conversion_metric": "conversion",
      "interaction_type": "click",
      "campaign_type": "ACI",
      "campaign_id": 123456789,
      "campaign_name": "My App Campaign",
      "network_type": null,
      "network_subtype": null,
      "ad_group_id": 123456789,
      "ad_group_name": "My App AdGroup",
      "asset_group_id": null,
      "is_deterministic": false,
      "geo_info": {
        "city": "san jose",
        "country": "US",
        "region": "california"
      },
      "device_info": {
          "device_model": "sm-s926u",
          "os_version": "14"
      },
      "timestamp": 1432681918.123456
    },
    ],
    "errors": [],
    "warnings": []
  }

Exemplo de resposta para uma conversão de iOS/Android atribuída por gbraid:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "interaction_type": "engagement",
    "network_type": null,
    "ad_group_id": null,
    "ad_group_name": null,
    "asset_group_id": null,
    "is_deterministic": true,
    "timestamp": 0.000000
  }],
  "errors": [],
  "attributed": true,
  "warnings": [],
}

Exemplo de uma resposta de acompanhamento de conversões quando a solicitação continha erros:

{
  "ad_events": [],
  "errors": ["INVALID_CURRENCY_CODE"],
  "attributed": false
}

Exemplo de uma resposta negativa de acompanhamento de conversões:

{
  "ad_events": [],
  "errors": [],
  "attributed": false
}

Uma resposta de acompanhamento de conversões será retornada para todas as solicitações de acompanhamento de conversões.

Exemplo de uma resposta afirmativa de acompanhamento de conversões para um usuário de uma campanha universal para apps que não está no EEE:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Exemplo de uma resposta afirmativa de acompanhamento de conversões para um usuário de fora do EEE em uma campanha de pesquisa:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Search",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": "+space +birds",
    "match_type": "b",
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Exemplo de uma resposta afirmativa de acompanhamento de conversões para um usuário de fora do EEE em uma campanha de display:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Display",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "mGDN",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": "mobile-app::2-343200656",
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Exemplo de uma resposta afirmativa de acompanhamento de conversões para um usuário de fora do EEE em uma campanha do YouTube:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Video",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": "dQw4w9WgXcQ",
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


Solicitação de atribuição de várias redes

Quando o Google Ads responde a uma solicitação de acompanhamento de conversões de forma afirmativa, o consumidor da API precisa notificar o Google Ads sobre a decisão de atribuição entre redes depois de identificar o último clique.

A solicitação de atribuição entre redes é idêntica à solicitação original de acompanhamento de conversões, mas com um caminho de solicitação de:

/pagead/conversion/app/1.1/cross_network

e a adição de dois parâmetros obrigatórios:

Solicitação de atribuição de várias redes
ad_event_id

Obrigatório

Localização: consulta

O identificador ad_event_id do evento de anúncio associado à atribuição na solicitação anterior.
attributed

Obrigatório

Localização: consulta

Se o Google Ads recebeu crédito pela conversão do consumidor da API. 0 ou 1.

Exemplo de uma solicitação válida de atribuição de várias redes:

POST /pagead/conversion/app/1.1/cross_network
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=custom
       &app_event_name=level_achieved
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
       &attributed=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Uma solicitação de atribuição entre redes válida sempre vai receber uma resposta 200 genérica sem corpo de resposta.