User agent dell'app
Nell'ambito del nostro più ampio impegno nella lotta allo spam, abbiamo sviluppato una specifica standardizzata per l'intestazione User-Agent inviata da un prodotto di analisi/annunci per conto di un utente dell'app. L'agente utente dell'app può essere ricavato 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 User-Agent | |
---|---|
name | Il nome del prodotto di analisi/annunci. ( Tieni presente che se lo user agent è creato sul lato client, Android// Specified by API consumer. iOS// Specified by API consumer. |
version | Versione del prodotto di analisi/annunci.
( 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. ( AndroidString osAndVersion = "Android " + Build.VERSION.RELEASE; iOSUIDevice *uid = [UIDevice currentDevice]; NSString *osAndVersion = [NSString stringWithFormat:@"%@ %@", [uid systemName], [uid systemVersion]]; |
locale | Un tag locale IETF per il dispositivo, utilizzando una lingua di due lettere e un codice paese separati da un trattino basso.
( AndroidString locale = Locale.getDefault(); iOSNSString *locale = [[NSLocale currentLocale] localeIdentifier] |
device | Il nome del dispositivo fisico che esegue il prodotto di analisi/annunci.
( AndroidString 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.
( AndroidString 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 ; Proxy
solo alla fine dell'User-Agent dell'app durante la creazione del lato server dello user agent. Se lo User-Agent dell'app è costruito interamente sul lato client, escludi ; Proxy
. Pertanto, uno User-Agent dell'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)
Richiesta di monitoraggio delle conversioni
Lo scopo delle richieste di monitoraggio delle conversioni è informare Google Ads di 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 i clic che hanno preceduto l'evento.
Tutte le chiamate API vengono effettuate al dominio www.googleadservices.com
. Le richieste di conversione sono richieste POST
tramite HTTPS sul seguente percorso:
/pagead/conversion/app/versiondove version è la versione prevista dell'API di monitoraggio delle conversioni. Attualmente l'unica versione valida è
1.0
.
Una richiesta di conversione di app standard contiene i seguenti parametri.
Richiesta di monitoraggio delle conversioni | |
---|---|
dev_token |
Obbligatorio Località: query Il token sviluppatore statico univoco emesso per il consumer dell'API. Z_eErE4DkvcKjDM1OVE4c4 |
link_id |
Obbligatorio Località: query L'identificatore del link che associa il token sviluppatore del consumer dell'API a un'app specifica. 31FF8D67E5BB5DD5029DCC2734C2F884 |
app_event_type |
Obbligatorio Località: query Il nome dell'evento app che si è verificato. Questo campo è un'enumerazione e accetta 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 |
app_event_name |
Obbligatorio in determinate condizioni Località: query Il nome di qualsiasi evento app personalizzato non accettato nel campo level_achieved Level Achieved Questo campo non deve contenere nessuno dei valori riservati per
|
app_event_data |
Facoltativo Località: corpo Inoltra eventuali dati aggiuntivi su eventi avanzati come semplici chiavi stringa di mappatura degli oggetti JSON ai valori. I valori accettabili sono stringhe e array di stringhe. {"level": 5, "attempts": 20} |
rdid |
Obbligatorio Località: query Una stringa UUID valida che rappresenta l'ID dispositivo non elaborato. f10e1de2-e237-4f50-b6aa-843c45cc63d6 Se manca l'ID dispositivo, ad esempio l'ID dispositivo da un utente ATT non autorizzato, impostalo su zero. 00000000-0000-0000-0000-000000000000 |
id_type |
Obbligatorio Località: query Il tipo di identificatore memorizzato nel campo Androidadvertisingid iOSidfa |
lat |
Obbligatorio Località: query Limita lo stato di monitoraggio degli annunci per il dispositivo.
|
app_version |
Obbligatorio Località: query La versione attuale dell'app. Dovrebbe essere standardizzata come segue. AndroidpackageManager.getPackageInfo(packageName(), PackageManager.GET_META_DATA).versionName iOS[[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"] 1.2.4 |
os_version |
Obbligatorio Località: query La versione corrente del sistema operativo host dell'app. Dovrebbe essere standardizzato come segue. Androidandroid.os.Build.VERSION.RELEASE iOS[[UIDevice currentDevice] systemVersion] |
sdk_version |
Obbligatorio Località: query La versione dell'SDK che ha misurato l'evento. Poiché viene usata principalmente
per il debug, deve riflettere la versione di release esattamente come è pubblicata
con le tue versioni dell'SDK. Se l'app non utilizza un SDK, trasmetti lo stesso valore di 1.9.5r6 |
timestamp |
Obbligatorio Località: query Il timestamp UNIX dell'evento di conversione, in secondi con precisione massima di microsecondi. 1432681913.123456 |
value |
Facoltativo Località: query Il valore monetario dell'evento, se presente. Questo valore deve sempre essere formattato come un valore in virgola mobile leggibile dal computer utilizzando un punto decimale per separare la parte intero e frazionare del valore. 1.99 |
currency_code |
Obbligatorio in determinate condizioni Località: query Il codice valuta ISO 4217 per il parametro USD |
gclid |
Obbligatorio in determinate condizioni Località: query Il valore del parametro di ricerca Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
Obbligatorio in determinate condizioni Località: query Il valore del parametro query BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
Obbligatorio in determinate condizioni Località: query Identificatore per l'attribuzione basata su 1 |
gbraid |
Obbligatorio in determinate condizioni Località: query Ultimo rilevamento del valore ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O |
app_open_source |
Obbligatorio in determinate condizioni Località: query Valore per identificare il link diretto ai clic sull'annuncio 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 passati dati avanzati sugli eventi nel payload app_event_data
), il nostro server richiede di impostare esplicitamente l'intestazione Content-Length: 0
nella richiesta.
Richiesta di esempio
Di seguito è riportato un esempio di richiesta di monitoraggio delle conversioni valida con un tipo di evento non personalizzato e le informazioni sulle entrate:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=in_app_purchase &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 ×tamp=1432681913.123456 &value=1.99 ¤cy_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
{"app_event_data":{"item_id":["Crayons","Markers"]}}
Di seguito è riportato un esempio di richiesta di monitoraggio delle conversioni valida con un tipo di evento non personalizzato e le informazioni sulle entrate con rdid (advertisingid) non disponibile:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=in_app_purchase &rdid=00000000-0000-0000-0000-000000000000 &id_type=advertisingid &lat=1 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u &gclid=Cj0KEQjw0dy4BRCuuL_e5M &gclid_only_request=1 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"]}}
Ecco un esempio di richiesta inizio sessione valida:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=session_start &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 ×tamp=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
Esempio di richiesta di riattribuzione inizio sessione valida per una sessione iniziata dal link direttoexample://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M
:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=session_start &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 ×tamp=1432681913.123456 &gclid=Cj0KEQjw0dy4BRCuuL_e5M 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
Codifica dei dati degli eventi
Per il parametro del corpo app_event_data
, utilizza le seguenti convenzioni per i tipi di dati primitivi:
Mobile
- Usa il carattere punto come separatore decimale indipendentemente dalla localizzazione delle 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 i gruppi di cifre, ad esempio 1.000.000
- Esempi validi:
-0.5
2.99
1000000.123
Intero
- Invia solo valori interi interi senza cifre decimali
- Non utilizzare una virgola per separare i gruppi di cifre, ad esempio 1.000. 000
- Esempi validi:
1000
-11
0
Data
- Formato data: aaaa-mm-gg
yyyy
= anno a quattro cifre, ad esempio 2016mm
= mese di due cifre, ad esempio 09 per settembredd
= giorno a due cifre, ad esempio 23 per il 23° giorno del mese
- Invia sempre il numero di cifre specificato sopra. Ad esempio, se invii il valore di gg per il quinto giorno del mese, invia
05
. - Esempi validi:
"2016-09-23"
"1990-12-31"
- Formato data: aaaa-mm-gg
Timestamp
- Formato dell'ora: timestamp Unix/epoca definito nel fuso orario UTC con precisione fino a microsecondi
- Esempi validi:
1478713087
per mercoledì 9 novembre 2016 17:38:07 GMT1073513982.123000
per mercoledì 7 gennaio 2004 22:19:42.123 GMT
Array
- Invia solo matrici di valori primitivi (stringhe, numeri e booleani)
- Esempi validi:
[123, 456, 789]
["abc"]
Risposta al monitoraggio delle conversioni
La risposta del monitoraggio delle conversioni ha il seguente formato:
{ "ad_events": [<ad event objects>], "errors": [<error strings>], "attributed": true|false }
Sia gli array ad_events che errors possono essere vuoti.
Prevediamo che gli errori saranno codici di errore leggibili automaticamente, ad esempio invalid_timestamp
.
Gli eventi annuncio sono gli oggetti principali dell'attribuzione dell'app e conterranno le seguenti proprietà.
Risposta al monitoraggio delle conversioni | |
---|---|
ad_event_id |
Sempre presente string
Q2owS0VRancwZHk0QlJDdXVMX2U1TQ |
conversion_metric |
Sempre presente string La metrica di conversione utilizzata per l'attribuzione. Inizialmente supporteremo una sola metrica di conversione. conversion |
timestamp |
Sempre presente number Il timestamp UNIX dell'evento dell'annuncio, in secondi con precisione fino a microsecondi. Questo valore deve essere utilizzato per l'attribuzione dell'ultimo clic. 1432681913.123456 |
campaign_type |
Sempre presente string Questo campo identifica il tipo di campagna che ha prodotto l'evento annuncio. Di seguito sono riportati i valori possibili. ACI ACE Search Display Video Shopping Hotel Performance_Max Other ACI è un'abbreviazione di App Campaign for Install. Esperimenti campagna AdWords è l'abbreviazione di campagne per app per incrementare il coinvolgimento. |
campaign_id |
Sempre presente number ID numerico della campagna che ha generato l'evento annuncio. Questo valore è garantito in modo univoco. 123456789 |
campaign_name |
Sempre presente string Il nome della campagna definito dall'inserzionista che ha prodotto l'evento annuncio. Questo valore non è garantito in modo univoco. Occasional Gamers (Video) |
ad_type |
Sempre presente string Il tipo di annuncio che ha generato l'evento annuncio. Questo valore può essere utilizzato per distinguere tra vari tipi di inventario come segue. Promozione di appClickToDownloadCoinvolgimento in-app AppDeepLinkCoinvolgimento in-app - Flusso di installazione e continua AppDeepLinkContinueCatch-all per altri valori Unknown |
external_customer_id |
Sempre presente number L'identificatore dell'inserzionista proprietario della campagna che ha prodotto l'evento annuncio. Questo valore può essere utilizzato per distinguere gli account Google Ads. 123456789 |
location |
Sempre presente number Codice dell'ID località della posizione geografica dell'evento annuncio. Consulta il riferimento API di Google Ads per interpretare i codici di località. |
network_type |
Sempre presente string Questo campo identifica la rete pubblicitaria Google Ads in cui si è verificato l'evento. Di seguito sono riportati i valori possibili. Search Display YouTube |
network_subtype |
Sarà string Questo campo identifica il "sottotipo" della rete pubblicitaria Google Ads in cui si è verificato l'evento. I valori possibili variano in base al tipo di rete principale. RicercaRicerca Google ordinariaGoogleSearchPartner della Ricerca Google SearchPartners VisualizzazionePublisher web per dispositivi mobilimGDNPublisher di app Google AdMob YouTubeRete video di YouTubeYouTubeVideosRete di ricerca di YouTube YouTubeSearchPartner video VideoPartners |
video_id |
Viene fornito soltanto quando string ID video di YouTube associato all'evento annuncio. dQw4w9WgXcQ |
keyword |
Viene fornito soltanto quando string La parola chiave per la rete di ricerca associata all'evento annuncio. +food +delivery |
match_type |
Viene fornito soltanto quando string Il tipo di corrispondenza per le parole chiave per la rete di ricerca. EsattoeFrase pGenerico b |
placement |
Viene fornito soltanto quando string Il posizionamento associato all'evento annuncio. mobileapp::1-343200656 |
ad_group_id |
Sempre presente number L'ID numerico del gruppo di annunci prodotto con l'evento annuncio. Questo valore è garantito in modo univoco. 123456789 |
ad_group_name |
Fornito solo quando string Il nome del gruppo di annunci definito dall'inserzionista che ha prodotto l'evento annuncio. Questo valore non è garantito in modo univoco. My App AdGroup |
creative_id |
Fornito solo quando number L'ID numerico dell'unità pubblicitaria che ha generato l'evento annuncio. Questo valore è garantito in modo univoco. 123456789 |
interaction_type |
Questo campo sarà sempre di coinvolgimento. string |
Risposte di esempio
Ecco un esempio di risposta al monitoraggio delle conversioni quando la richiesta conteneva errori:
{ "ad_events": [], "errors": ["INVALID_CURRENCY_CODE"], "attributed": false }
Esempio di risposta di monitoraggio delle conversioni esclusa:
{ "ad_events": [], "errors": [], "attributed": false }
Verrà restituita una risposta al monitoraggio delle conversioni per tutte le richieste di monitoraggio delle conversioni.
Ecco un esempio di risposta di monitoraggio delle conversioni per una campagna universale 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 }
Ecco un esempio di risposta di monitoraggio delle conversioni 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 }
Ecco un esempio di risposta di monitoraggio delle conversioni 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 }
Esempio di risposta di monitoraggio delle conversioni per una campagna di 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 }
Richiesta di attribuzione su più reti
Quando Google Ads risponde in modo affermativo a una richiesta di monitoraggio delle conversioni, il consumatore API deve informare Google Ads della sua decisione sull'attribuzione su più reti dopo aver identificato l'ultimo clic.
La richiesta di attribuzione su più reti è identica alla richiesta di monitoraggio delle conversioni originale, ma con un percorso di richiesta di:
/pagead/conversion/app/1.0/cross_network
e l'aggiunta di due parametri obbligatori:
Richiesta di attribuzione su più reti | |
---|---|
ad_event_id |
Obbligatorio Località: query L'identificatore |
attributed |
Obbligatorio Località: query Indica se Google Ads ha ricevuto o meno il merito di conversione dal consumatore dell'API. |
Esempio di richiesta di attribuzione su più reti valida:
POST /pagead/conversion/app/1.0/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 ×tamp=1432681913.123456 &value=1.99 ¤cy_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 su più reti valida riceve sempre una risposta generica di tipo 200 senza corpo di risposta.