Monitoraggio delle conversioni di app e remarketing - Specifiche di richiesta/risposta

User agent dell'app

Nell'ambito dei nostri sforzi più ampi per combattere lo spam, abbiamo sviluppato una specifica standardizzata per l'intestazione User-Agent inviata da un prodotto di analisi/pubblicità per conto di un utente dell'app. L'User-Agent dell'app può essere derivato dal codice nativo per rispettare la seguente specifica:

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

La definizione di questi campi è la seguente:

Componenti dello user agent
name

Il nome del prodotto di analisi/pubblicità. (Google AdMob)

Tieni presente che se lo user agent viene creato sul lato client, name deve essere l'ID bundle dell'app client.

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

La versione del prodotto di analisi/annunci. (7.10.1)

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

Il sistema operativo e la versione del sistema operativo su cui è in esecuzione l'app. (Android 6.0 )

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

Un tag locale IETF per il dispositivo, utilizzando il codice paese e lingua di due lettere separati da un trattino basso. (en_US)

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

Il nome del dispositivo fisico su cui è in esecuzione il prodotto di analisi/pubblicità. (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/" seguito dal numero di build del sistema operativo. (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];
}

Includi solo ; Proxy alla fine dell'User-Agent dell'app durante la costruzione dell'User-Agent dell'app lato server. Se lo user agent dell'app è costruito interamente sul lato client, escludi ; Proxy. Pertanto, lo user agent di un'app potrebbe essere:

  • 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)

Guida alla richiesta di monitoraggio delle conversioni

Lo scopo delle richieste di monitoraggio delle conversioni è comunicare a Google Ads un evento app che deve essere monitorato come conversione e/o utilizzato per compilare un elenco per il remarketing e recuperare i metadati che descrivono qualsiasi clic precedente all'evento.

Tutte le chiamate API vengono effettuate al dominio www.googleadservices.com. Le richieste di conversione sono richieste POST tramite HTTPS nel seguente percorso: 

/pagead/conversion/app/version
dove version è la versione prevista dell'API Conversion Tracking.

Una richiesta di conversione standard dell'app conterrà i seguenti parametri per l'API Conversioni v1.1.

Richiesta di monitoraggio delle conversioni
dev_token

Obbligatorio

Luogo: Query

Il token sviluppatore statico univoco rilasciato al consumer dell'API.

Z_eErE4DkvcKjDM1OVE4c4
link_id

Obbligatorio

Luogo: Query

L'identificatore di collegamento che associa il token sviluppatore del consumer dell'API a un'app specifica.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

Obbligatorio

Luogo: Query

Il nome dell'evento app che si è verificato. Questo campo è un'enumerazione e accetterà solo i seguenti valori:

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

L'evento first_open deve essere sempre inviato per l'attribuzione delle installazioni e l'evento session_start deve essere sempre inviato per l'attribuzione delle sessioni. Utilizza in_app_purchase per gli acquisti effettuati tramite lo store nativo dell'app; utilizza ecommerce_purchase per tutti gli altri acquisti.
app_event_name

Obbligatorio a determinate condizioni

Luogo: Query

Il nome di qualsiasi evento app personalizzato non accettato nel campo app_event_type. Questo campo deve contenere da 1 a 64 caratteri Unicode (utilizzando la codifica UTF-8). Questo campo è obbligatorio se app_event_type è personalizzato.

level_achieved
Level Achieved

Questo campo non deve contenere nessuno dei valori riservati a app_event_type. Se viene utilizzato un nome di evento riservato, l'API restituirà un errore APP_EVENT_NAME_RESERVED_VALUE.
app_event_data

Facoltativo

Località: corpo

Inoltra tutti i dati aggiuntivi degli eventi avanzati come semplice oggetto JSON che mappa le chiavi stringa ai valori. I valori accettabili sono stringhe e array di stringhe.

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

Obbligatorio quando si utilizza la misurazione delle conversioni integrata su iOS

Luogo: Query

Il valore del parametro di query info, acquisito al momento dell'installazione o della reinstallazione dell'app per iOS dall'SDK Google On Device Measurement (ODM): Event Data. Questo campo attiva la misurazione delle conversioni integrata per le campagne per app per iOS.

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

Obbligatorio

Il tipo di identificatore passato nel campo rdid.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

Obbligatorio

Luogo: Query

Una stringa UUID valida che rappresenta l'ID dispositivo non elaborato.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

Nel caso in cui l'ID dispositivo non sia presente, ad esempio l'ID dispositivo di un utente che non ha dato il consenso ATT, impostalo come tutti zeri.

00000000-0000-0000-0000-000000000000
ctry_c

Obbligatorio

Luogo: Query

Codice paese ISO di due lettere per indicare il paese di origine della conversione.

Questo campo è necessario per attivare la misurazione delle conversioni da app non a livello di utente su iOS e Android.

US, IN
eea

Obbligatorio a determinate condizioni

Luogo: Query

L'ambito del SEE.

0: i regolamenti europei non si applicano a questo utente e a questa conversione

1: i regolamenti europei si applicano a questo utente e a questa conversione. Ad esempio, se un utente si trova nel SEE, rientra nell'ambito di applicazione dei regolamenti europei vigenti. 

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

Obbligatorio a determinate condizioni

Luogo: Query

I flag per gli annunci personalizzati

0: l'utente finale ha negato il consenso alla personalizzazione degli annunci

1: l'utente finale ha concesso il consenso alla personalizzazione degli annunci 

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

Obbligatorio a determinate condizioni

Luogo: Query

Il flag di consenso per l'utilizzo dei dati utente a fini pubblicitari

0: l'utente ha negato il consenso per la trasmissione a Google dei dati a livello utente a fini pubblicitari

1: l'utente ha concesso il consenso per la trasmissione a Google dei dati a livello utente a fini pubblicitari 

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

Obbligatorio

Luogo: Query

Stato della limitazione del monitoraggio degli annunci per il dispositivo.

  • 0: l'utente non ha scelto di limitare il monitoraggio degli annunci.
  • 1: l'utente ha scelto di limitare il monitoraggio degli annunci.
app_version

Obbligatorio

Luogo: Query

La versione attuale dell'app. Deve essere standardizzata nel seguente modo.

Android

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

iOS

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

Obbligatorio

Luogo: Query

La versione attuale del sistema operativo host dell'app. Questo valore deve essere standardizzato come segue.

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

Obbligatorio

Luogo: Query

La versione dell'SDK che ha misurato l'evento. Poiché viene utilizzato principalmente per il debug, deve riflettere la versione di rilascio esattamente come viene pubblicata con le release dell'SDK. Se l'app non utilizza un SDK, trasmetti lo stesso valore di app_version.

1.9.5r6
timestamp

Obbligatorio

Luogo: Query

Il timestamp UNIX in cui si è verificato l'evento di conversione, in secondi con precisione in microsecondi.

1432681913.123456
fot

Obbligatorio

Luogo: Query

Il timestamp UNIX del corrispondente first_open in secondi con precisione in microsecondi per tutte le sessioni successive e gli eventi post-installazione.

1432681913.123456
value

Facoltativo

Luogo: Query

Il valore monetario dell'evento, se presente. Questo valore deve sempre essere formattato come un valore in virgola mobile leggibile automaticamente utilizzando un punto decimale per separare la parte intera e quella frazionaria del valore.

1.99
currency_code

Obbligatorio a determinate condizioni

Luogo: Query

Il codice valuta ISO 4217 per il parametro value. Questo campo è obbligatorio se il parametro value viene fornito e non è vuoto.

USD
gclid

Obbligatorio a determinate condizioni

Luogo: Query

Il valore del parametro di query gclid di un URL di link diretto che ha aperto l'app.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

Obbligatorio a determinate condizioni

Luogo: Query

Il valore del parametro di query gclid di un URL di link diretto acquisito dal valore install_referrer tramite l'API Play Install Referrer.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

Obbligatorio a determinate condizioni

Luogo: Query

Identificatore per l'attribuzione basata su gclid in scenari in cui rdid (advertisingid) è not disponibile o tutti i zeroes E sono presenti gclid o market_referrer_gclid.

1
gbraid

Obbligatorio a determinate condizioni

Luogo: Query

Valore gbraidUltima visualizzazione inviato tramite l'URL del link diretto che ha aperto l'app. Tieni presente che questo valore deve essere memorizzato nella cache dell'app in modo che possa essere inviato con le conversioni future che si verificano nell'app.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

Obbligatorio a determinate condizioni

Luogo: Query

Valore per identificare i deep link dei clic sugli annunci o le sessioni organiche dell'app.

ad_click or organic
User-Agent

Obbligatorio

Località: intestazione

Lo user agent dell'app come definito nella sezione precedente.

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

Obbligatorio

Località: intestazione

L'indirizzo IPv4 o IPv6 pubblico del dispositivo in cui è stato misurato l'evento.

216.58.194.174

Tutte le richieste devono essere inviate tramite HTTPS. I ping ricevuti tramite HTTP verranno rifiutati.

Tieni presente che se il corpo della richiesta è vuoto (nei casi in cui non vengono trasmessi dati sugli eventi avanzati nel payload app_event_data), il nostro server richiede di impostare esplicitamente l'intestazione Content-Length: 0 nella richiesta.

Codifica dei dati sugli eventi

Per il parametro del corpo app_event_data, utilizza le seguenti convenzioni per i tipi di dati primitivi:

  • Float

    • Utilizza il carattere punto come separatore decimale indipendentemente dalla localizzazione dell'app
    • Utilizza la precisione decimale a due cifre per rappresentare i valori monetari. Ad esempio, 2,99.
    • Non utilizzare la notazione esponenziale, ad esempio 2E+9
    • Non utilizzare una virgola per separare gruppi di cifre, ad esempio 1.000.000
    • Esempi validi:
      • -0.5
      • 2.99
      • 1000000.123

  • Intero

    • Invia solo valori interi senza cifre decimali
    • Non utilizzare una virgola per separare gruppi di cifre, ad es. 1.000.000
    • Esempi validi:
      • 1000
      • -11
      • 0

  • Data

    • Formato della data: aaaa-mm-gg
      • yyyy = anno a quattro cifre, ad es. 2016
      • mm = mese a due cifre, ad esempio 09 per settembre
      • dd = giorno a due cifre, ad es. 23 per il 23° giorno del mese
    • Invia sempre il numero di cifre specificato sopra. Ad esempio, se invii il valore per gg per il 5° giorno del mese, invia 05.
    • Esempi validi:
      • "2016-09-23"
      • "1990-12-31"

  • Timestamp

    • Formato ora: timestamp Unix/Epoch in secondi definito nel fuso orario UTC con precisione in microsecondi
    • Esempi validi:
      • 1478713087 per mercoledì 09 nov 2016 17:38:07 GMT
      • 1073513982.123000 per mercoledì 7 gennaio 2004 22:19:42.123 GMT

  • Array

    • Invia solo array di valori primitivi (stringhe, numeri e valori booleani)
    • Esempi validi:
      • [123, 456, 789]
      • ["abc"]

Richieste di esempio

Un esempio di richiesta di prima apertura con l'SDK On Device Measurement: Event Data per la misurazione delle conversioni integrata è:

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

Un esempio di richiesta di prima apertura senza l'SDK On Device Measurement: Event Data per la misurazione integrata delle conversioni è:

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

Un esempio di richiesta post-installazione con l'SDK per la misurazione sul dispositivo: dati sugli eventi per la misurazione integrata delle conversioni è:

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

Un esempio di richiesta di prima apertura senza l'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

Un esempio di richiesta di prima apertura per una conversione non deterministica di Android per 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

Un esempio di richiesta di monitoraggio delle conversioni valida con un tipo di evento non personalizzato e informazioni sulle entrate è:

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"]}}

Un esempio di richiesta di monitoraggio delle conversioni valida con un tipo di evento non personalizzato e informazioni sulle entrate con rdid (advertisingid) non disponibile è:

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"]}}

Un esempio di richiesta di avvio sessione valida è:

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

Un esempio di richiesta di riattribuzione valida per l'inizio sessione di una sessione iniziata dal link diretto 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

Un esempio di richiesta di monitoraggio delle conversioni valida per un utente del SEE con consenso all'utilizzo dei dati utente concesso e personalizzazione degli annunci rifiutata è:

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

Guida alla risposta del monitoraggio delle conversioni

La risposta del monitoraggio delle conversioni ha il seguente formato:

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

Gli array ad_events ed errors potrebbero essere vuoti.

Prevediamo che gli errori siano codici di errore leggibili automaticamente, ad esempio invalid_timestamp.

Codici di errore

  • invalid_timestamp: la richiesta non aveva un timestamp valido.

  • eea_missing_or_invalid: la richiesta non aveva impostato il campo "eea" o non era valido.

  • ad_user_data_missing: il campo della richiesta "ad_user_data" non è stato impostato. Il campo "ad_user_data" è obbligatorio per tutte le richieste DMA incluse nell'ambito.

  • ad_user_data_invalid: il valore della richiesta "ad_user_data" non era valido. Il campo "ad_user_data" è obbligatorio per tutte le richieste DMA incluse nell'ambito.

  • ad_personalization_missing_or_invalid: la richiesta non aveva impostato il campo "ad_personalization" o non era valido. Il campo "ad_personalization" è obbligatorio per tutte le richieste DMA incluse nell'ambito.

Gli eventi annuncio sono gli oggetti principali dell'attribuzione delle app e contengono le seguenti proprietà.

Note importanti sul comportamento della risposta a seconda del consenso dell'utente:
Se la conversione ha il consenso per i dati utente degli annunci e l'utente ha dato il consenso all'utilizzo cross-use nelle impostazioni utente di Google, Google Ads risponderà con un singolo ultimo clic in tutti i suoi CPS. Se l'utente non ha acconsentito all'utilizzo incrociato nelle impostazioni utente di Google, Google Ads risponderà con più ultimi clic, in base al costo per vendita.

Se la conversione include determinati CPS nel consenso all'uso incrociato selezionato dall'utente, ma non altri, Google Ads risponderà con un singolo ultimo clic nei CPS per i quali è stato concesso il consenso all'uso incrociato, ma con più ultimi clic, in base al CPS, per i CPS per i quali non è stato concesso il consenso all'uso incrociato.

Risposta al monitoraggio delle conversioni
ad_event_id

Sempre presente

stringa

ad_event_id funge da identificatore univoco per gli eventi pubblicitari. Viene riutilizzato nella richiesta di attribuzione cross-network e deve essere registrato/conservato a scopo di debug.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Sempre presente

stringa

La metrica di conversione utilizzata per l'attribuzione. Inizialmente supporteremo una metrica di conversione.

conversion
timestamp

Sempre presente

numero

Il timestamp UNIX in cui si è verificato l'evento annuncio, in secondi con precisione in microsecondi. Questo valore deve essere utilizzato per l'attribuzione dell'ultimo clic.

1432681913.123456
campaign_type

Sempre presente

stringa

Questo campo identifica il tipo di campagna che ha generato l'evento annuncio. I valori possibili sono i seguenti.

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACi è l'abbreviazione di Campagna per app per incrementare le installazioni. ACE è l'abbreviazione di Campagne per app per incrementare il coinvolgimento.
campaign_id

Sempre presente

numero

L'ID campagna numerico della campagna che ha generato l'evento annuncio. Questo valore è garantito univoco.

123456789
campaign_name

Sempre presente

stringa

Il nome della campagna definito dall'inserzionista che ha generato l'evento annuncio. Questo valore non è garantito come univoco.

Occasional Gamers (Video)
ad_type

Sempre presente

stringa

Il tipo di annuncio che ha generato l'evento dell'annuncio. Questo valore può essere utilizzato per distinguere i vari tipi di inventario come segue.

Promozione di app 
ClickToDownload
 Coinvolgimento in app 
AppDeepLink
 Coinvolgimento nell'app: flusso Installa e continua 
AppDeepLinkContinue
 Categoria generica per altri valori 
Unknown
external_customer_id

Sempre presente

numero

L'identificatore dell'inserzionista proprietario della campagna che ha generato l'evento annuncio. Questo valore può essere utilizzato per distinguere gli account Google Ads.

123456789
location

Sempre presente

numero

Il codice ID della località per la posizione geografica dell'evento annuncio. Per interpretare i codici località, consulta il riferimento all'API Google Ads.
network_type

Sempre presente

stringa

Questo campo identifica la rete pubblicitaria Google Ads in cui si è verificato l'evento annuncio. I valori possibili sono i seguenti.

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Sarà null quando campaign_type è ACI o ACE e network_type è Display.

stringa

Questo campo identificherà il "sottotipo" della rete pubblicitaria Google Ads in cui si è verificato l'evento annuncio. I valori possibili variano in base al tipo di rete principale.

Ricerca Google normale 
GoogleSearch
 Partner di ricerca di Google 
SearchPartners

Display

Publisher web mobile 
mGDN
 Publisher di app 
Google AdMob

YouTube

Rete video di YouTube 
YouTubeVideos
 Rete di ricerca di YouTube 
YouTubeSearch
 Partner video 
VideoPartners

GoogleTv

Rete video di GoogleTV 
GoogleTvVideos

cross-network

Performance Max cross-network 
cross-network
video_id

Fornito solo quando network_type è YouTube e campaign_type non è ACI e ACE.

stringa

L'ID video di YouTube associato all'evento pubblicitario.

dQw4w9WgXcQ
keyword

Fornito solo quando network_type è Search e campaign_type non è ACI e ACE.

stringa

La parola chiave di ricerca associata all'evento annuncio.

+food +delivery
match_type

Fornito solo quando network_type è Search e campaign_type non è ACI e ACE.

stringa

Il tipo di corrispondenza per le parole chiave per la rete di ricerca.

Esatto 
e
 Frase 
p
 Generica 
b
placement

Fornito solo quando network_type è Display e campaign_type non è ACI e ACE.

stringa

Il posizionamento associato all'evento annuncio.

mobileapp::1-343200656
ad_group_id

Fornito solo quando campaign_type non è Performance_Max.

numero

L'ID numerico del gruppo di annunci che ha generato l'evento annuncio. Questo valore è garantito univoco.

123456789
ad_group_name

Fornito solo quando campaign_type è ACI, ACE o ACPRE.

stringa

Il nome del gruppo di annunci definito dall'inserzionista che ha prodotto l'evento annuncio. Questo valore non è garantito come univoco.

My App AdGroup
creative_id

Fornito solo quando campaign_type non ACI, ACE, ACPRE o Performance_Max.

numero

L'ID numerico dell'unità pubblicitaria della creatività che ha generato l'evento pubblicitario. Questo valore è garantito univoco.

123456789
interaction_type

Questo campo sarà sempre il coinvolgimento.

stringa
is_deterministic

Indica se il metodo di attribuzione è deterministico o meno.

Booleano

true, false
device_model

Modello del dispositivo che ha generato l'evento annuncio.

Stringa

sm-s936w, sm-3936w
os_version

La versione principale del sistema operativo che ha generato l'evento annuncio.

Stringa

14, 12
country

Il codice paese di due lettere che ha generato l'evento annuncio.

Stringa

CA, US
city

La città che ha prodotto l'evento annuncio.

Stringa

san jose, london
region

Lo stato o la provincia che ha generato l'evento pubblicitario.

Stringa

california, british columbia

Risposte di esempio

Un esempio di risposta per una conversione deterministica è:

{
  "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": null,
    "ad_group_name": null,
    "is_deterministic": true
    "timestamp": 1234567.898765,
  }],
  "errors": [],
  "attributed": true
}

Un esempio di risposta per una conversione non deterministica di 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": null,
    "ad_group_name": null,
    "is_deterministic": false
    },
    "device_info": {
        "device_model": "iphone12,3",
        "os_version": "14",
    },
    "timestamp": 1432681918.123456
    }],
  "errors": [],
  "attributed": true
}

Un esempio di risposta per una conversione non deterministica di 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": null,
      "ad_group_name": 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" [],
  }

Un esempio di risposta per una conversione iOS/Android attribuita da 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",
    "is_deterministic": true
    "timestamp": 0.000000,
  }],
  "errors": [],
  "attributed": true
  "warnings" [],
}

Un esempio di risposta al monitoraggio delle conversioni quando la richiesta conteneva errori è:

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

Un esempio di risposta negativa al monitoraggio delle conversioni è:

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

Verrà restituita una risposta di monitoraggio delle conversioni per tutte le richieste di monitoraggio delle conversioni.

Un esempio di risposta di monitoraggio delle conversioni affermativa per un utente non SEE per una campagna per app è:

{
  "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": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Un esempio di risposta affermativa del monitoraggio delle conversioni per un utente non SEE per una campagna sulla rete di ricerca è:

{
  "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": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Un esempio di risposta affermativa del monitoraggio delle conversioni per un utente non SEE per una campagna 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": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Un esempio di risposta affermativa al monitoraggio delle conversioni per un utente non SEE per una campagna 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": "My App AdGroup",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


Richiesta di attribuzione su più reti

Quando Google Ads risponde in modo affermativo a una richiesta di monitoraggio delle conversioni, il consumer dell'API deve comunicare a Google Ads la sua decisione di attribuzione cross-network dopo aver identificato l'ultimo clic.

La richiesta di attribuzione cross-network è identica alla richiesta di monitoraggio delle conversioni originale, ma con un percorso della richiesta di:

/pagead/conversion/app/1.1/cross_network

e l'aggiunta di due parametri obbligatori:

Richiesta di attribuzione su più reti
ad_event_id

Obbligatorio

Luogo: Query

L'identificatore ad_event_id dell'evento pubblicitario associato all'attribuzione nella richiesta precedente.
attributed

Obbligatorio

Luogo: Query

Se Google Ads ha ricevuto o meno il merito della conversione da parte del consumer dell'API. 0 o 1.

Un esempio di richiesta di attribuzione cross-network valida è:

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

Una richiesta di attribuzione cross-network valida riceverà sempre una risposta 200 generica senza corpo della risposta.