L'SDK Google Analytics for Mobile Apps per Android semplifica l'implementazione di Google Analytics in un'applicazione basata su Android. Questo documento descrive come integrare l'SDK con le tue app.
Panoramica dell'SDK
Questo SDK utilizza un modello di monitoraggio progettato per monitorare gli utenti sui siti web tradizionali e sull'interazione con i widget nelle pagine web tradizionali. Per questo motivo, i termini utilizzati di seguito riflettono il modello convenzionale di monitoraggio dei siti web e sono in fase di mappatura per il monitoraggio di applicazioni mobile. Dovresti conoscere il monitoraggio di Analytics per capire come funziona questo SDK.
Utilizza l'SDK di monitoraggio mobile per monitorare le applicazioni telefoniche con i seguenti tipi di interazione Analytics:
- Monitoraggio delle visualizzazioni di pagina
- Una visualizzazione di pagina è uno strumento standard per misurare il volume di traffico verso un sito web tradizionale. Poiché le app mobile non contengono pagine HTML, devi decidere quando (e con quale frequenza) attivare una richiesta di visualizzazione di pagina. Inoltre, poiché le richieste di visualizzazione di pagina sono progettate per generare report sulle strutture delle directory, devi fornire nomi descrittivi per le richieste in modo da sfruttare la denominazione dei percorsi pagina nei report Contenuti in Analytics. I nomi che scegli verranno completati nei report di Analytics come percorsi di pagina anche se non si tratta in realtà di pagine HTML, ma puoi sfruttarli a tuo vantaggio strutturando dei percorsi in modo da fornire raggruppamenti aggiuntivi per le chiamate.
- Monitoraggio eventi
- In Analytics, gli eventi sono progettati per monitorare l'interazione degli utenti con gli elementi delle pagine web in modo distinto dalle richieste di visualizzazioni di pagina. Puoi utilizzare la funzionalità di monitoraggio eventi di Google Analytics per effettuare chiamate aggiuntive che verranno indicate nella sezione Monitoraggio eventi dell'interfaccia del report di Analytics. Gli eventi vengono raggruppati utilizzando categorie e possono anche utilizzare le etichette per evento, il che offre flessibilità nei report. Ad esempio, un'app multimediale potrebbe prevedere azioni riproduci/interrompi/pausa per la sua categoria video e assegnare un'etichetta a ciascun nome video. I report di Google Analytics aggregano quindi gli eventi per tutti gli eventi taggati con la categoria video. Per ulteriori informazioni sul monitoraggio eventi, consulta la Guida al monitoraggio eventi
- Monitoraggio e-commerce
- Utilizza la funzionalità di monitoraggio e-commerce per monitorare le transazioni del carrello
degli acquisti e gli acquisti in-app.
Per monitorare una transazione, utilizza la classe
Transaction
per rappresentare le informazioni generali sull'acquisto e la classeItem
per rappresentare ciascun prodotto nel carrello degli acquisti. Una volta raccolti, i dati possono essere visualizzati nella sezione Report sull'e-commerce dell'interfaccia di Google Analytics. Per ulteriori informazioni sul Monitoraggio e-commerce, consulta la Guida al monitoraggio e-commerce. - Variabili personalizzate
- Le variabili personalizzate sono tag di coppia nome-valore che puoi inserire nel codice di monitoraggio per perfezionare il monitoraggio di Google Analytics. Per ulteriori informazioni su come utilizzare le variabili personalizzate, consulta la Guida alle variabili personalizzate.
Per iniziare
Requisiti
Per integrare le funzionalità di monitoraggio di Google Analytics con la tua app per Android, devi disporre di quanto segue:
- SDK per sviluppatori Android (disponibile per Windows, Mac OS X e Linux)
- SDK Google Analytics per app mobile per Android
Configurazione
- Aggiungi
libGoogleAnalytics.jar
alla directory/libs
del progetto. -
Aggiungi le seguenti autorizzazioni al file manifest
AndroidManifest.xml
del tuo progetto:<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
L'SDK include un'applicazione di esempio che mostra come dovrebbe essere il tuo progetto se configurato correttamente. Puoi utilizzarlo come modello per le tue app integrate con Analytics.
Utilizzo dell'SDK
Prima di iniziare a utilizzare l'SDK, devi creare un account senza costi all'indirizzo www.google.com/analytics e creare una nuova proprietà web in quell'account utilizzando un URL del sito web falso ma descrittivo (ad es. http://mymobileapp.mywebsite.com
). Dopo aver creato la proprietà, prendi nota o conserva una copia dell'ID proprietà web generato per la proprietà appena creata.
Devi indicare ai tuoi utenti, nell'applicazione stessa o nei Termini di servizio, che ti riservi il diritto di monitorare e segnalare in modo anonimo l'attività di un utente all'interno della tua app. Il tuo utilizzo dell'SDK di Google Analytics è inoltre regolato dai Termini di servizio di Google Analytics, che devi accettare al momento della creazione di un account.
Esempi e best practice
Puoi trovare codice di esempio e best practice all'indirizzo code.google.com all'interno del progetto analytics-api-samples.
Libreria EasyTracker
È disponibile una libreria EasyTracker. Fornisce monitoraggio a livello di applicazione e attività senza quasi alcuno sforzo in termini di sviluppo. Puoi trovarlo nella sezione Download del progetto analytics-api-samples.
Avvio del rilevatore
Ottieni il singleton del tracker chiamando il numero GoogleAnalyticsTracker.getInstance()
. Quindi chiama il metodo startNewSession
, trasmettendo l'ID proprietà web e l'attività monitorata. Puoi chiamare questo metodo direttamente nel metodo onCreate
della tua attività se l'applicazione ha una sola attività. Ad esempio:
package com.google.android.apps.analytics.sample; import com.google.android.apps.analytics.GoogleAnalyticsTracker; import android.app.Activity; import android.os.Bundle; import android.view.View; import android.view.View.OnClickListener; import android.widget.Button; public class TestActivity extends Activity { GoogleAnalyticsTracker tracker; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); tracker = GoogleAnalyticsTracker.getInstance(); // Start the tracker in manual dispatch mode... tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this); // ...alternatively, the tracker can be started with a dispatch interval (in seconds). //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this); setContentView(R.layout.main); Button createEventButton = (Button)findViewById(R.id.NewEventButton); createEventButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { tracker.trackEvent( "Clicks", // Category "Button", // Action "clicked", // Label 77); // Value } }); Button createPageButton = (Button)findViewById(R.id.NewPageButton); createPageButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and // scope of session-level. tracker.setCustomVar(1, "Navigation Type", "Button click", 2); // Track a page view. This is probably the best way to track which parts of your application // are being used. // E.g. // tracker.trackPageView("/help"); to track someone looking at the help screen. // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game. // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen. tracker.trackPageView("/testApplicationHomeScreen"); } }); Button quitButton = (Button)findViewById(R.id.QuitButton); quitButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { finish(); } }); Button dispatchButton = (Button)findViewById(R.id.DispatchButton); dispatchButton.setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { // Manually start a dispatch, not needed if the tracker was started with a dispatch // interval. tracker.dispatch(); } }); } @Override protected void onDestroy() { super.onDestroy(); // Stop the tracker when it is no longer needed. tracker.stopSession(); } }
Se nell'applicazione sono presenti più attività, puoi utilizzare la libreria EasyTracker disponibile nella sezione Download del progetto analytics-api-samples.
Monitoraggio di visualizzazioni di pagina ed eventi
Il monitoraggio delle visualizzazioni di pagina e degli eventi è molto semplice: basta chiamare trackPageView
dell'oggetto tracker ogni volta che vuoi attivare una visualizzazione di pagina. Chiama trackEvent
per registrare un evento. Per saperne di più su visualizzazioni di pagina ed eventi, consulta la sezione Panoramica dell'SDK qui sopra.
Utilizzo delle variabili personalizzate
Anche l'aggiunta di una variabile personalizzata è semplice: è sufficiente utilizzare il metodo setCustomVar
fornito dall'SDK per dispositivi mobili. Ti consigliamo di pianificare in anticipo l'indicizzazione di ogni variabile personalizzata a cui viene mappata, in modo da non sovrascrivere eventuali variabili esistenti in precedenza. Per ulteriori informazioni sulle variabili personalizzate, consulta la Guida alle variabili personalizzate. Tieni presente che il metodo setCustomVar
non invia dati direttamente
autonomamente. ma vengono inviati con la successiva visualizzazione di pagina o il successivo evento monitorato. Devi chiamare setCustomVar
prima di monitorare una visualizzazione di pagina o un evento. Tieni presente che l'ambito predefinito delle variabili personalizzate è l'ambito pagina.
Utilizzo del monitoraggio e-commerce
Esistono quattro metodi per attivare il monitoraggio e-commerce nella tua applicazione:
addTransaction
addItem
trackTransactions
clearTransactions
Chiamando addTransaction
e addItem
, la transazione o l'elemento vengono aggiunti a un buffer di e-commerce interno, a cui è possibile aggiungere ulteriori elementi e transazioni. Solo quando chiami trackTransactions
le transazioni e gli elementi verranno inviati al committente e verranno messi in coda
per essere inviati a Google Analytics.
Per cancellare il buffer, puoi chiamare il metodo clearTransactions
.
Nota: non richiama alcuna transazione inviata in precedenza al supervisore né
transazioni già raccolte da Google Analytics.
Il seguente codice di esempio può aiutarti a iniziare. Presumiamo che il metodo
onPurchaseCompleted
venga chiamato quando l'acquisto viene confermato o
negato.
/** * The purchase was processed. We will track the transaction and its associated line items * now, but only if the purchase has been confirmed. * * @param purchase A PurchaseObject containing all of the transaction information needed to * send the ecommerce hit to Google Analytics. */ public void onPurchaseCompleted(PurchaseObject purchase) { tracker.addTransaction(new Transaction.Builder( purchase.getTransactionId(), purchase.getTotal()) .setStoreName(purchase.getStoreName()) .setTotalTax(purchase.getTotalTax()) .setShippingCost(purchase.getShippingCost()) .build()); for (PurchaseLineItem lineItem : purchase.getLineItems()) { tracker.addItem(new Item.Builder( purchase.getTransactionId(), lineItem.getItemSKU(), lineItem.getItemCost(), lineItem.getQuantity()) .setItemName(lineItem.getItemName()) .setItemCategory(lineItem.getItemCategory()) .build()); } if (purchase.isConfirmed()) { tracker.trackTransactions(); } else { // The purchase was denied or failed in some way. We need to clear out // any data we've already put in the Ecommerce buffer. tracker.clearTransactions(); } }
Per ulteriori informazioni sull'e-commerce, consulta la Guida al monitoraggio e-commerce.
Anonimizza IP
Per anonimizzare le informazioni IP dell'utente, utilizza il metodo setAnonymizeIp
.
Questo indica a Google Analytics di anonimizzare le informazioni inviate dall'SDK rimuovendo
l'ultimo ottetto dell'indirizzo IP prima della sua archiviazione.
Puoi chiamare setAnonymizeIp
in qualsiasi momento.
Impostazione della frequenza di campionamento
Puoi impostare la frequenza di campionamento utilizzando il metodo setSampleRate
.
Se la tua applicazione genera molto traffico di Analytics, l'impostazione della frequenza di campionamento potrebbe impedire la generazione dei report utilizzando dati campionati. Il campionamento viene eseguito in modo coerente tra gli utenti unici, in modo da garantire l'integrità delle tendenze e dei report quando la frequenza di campionamento è attivata.
Il metodo setSampleRate
accetta un parametro int
. I valori validi per questo parametro sono qualsiasi numero intero compreso tra 0 e 100 inclusi.
Una percentuale pari a 0 disattiva la generazione di hit, mentre una percentuale pari a 100 invia tutti i dati a Google Analytics.
È preferibile chiamare setSampleRate
prima di chiamare qualsiasi metodo di monitoraggio.
Per ulteriori informazioni sul campionamento, consulta la Guida ai concetti sul campionamento.
Raggruppamento di hit
Per risparmiare sui costi di connessione e batteria, ti consigliamo di raggruppare le richieste di monitoraggio. Puoi chiamare dispatch
sull'oggetto di monitoraggio ogni volta che vuoi effettuare una richiesta batch, manualmente o a intervalli di tempo specifici.
Problemi noti
Monitoraggio delle campagne
L'SDK supporta due tipi di monitoraggio delle campagne.
- Monitoraggio delle campagne su Google Play: ti consente di tenere traccia dei referral delle installazioni tramite Google Play.
- Monitoraggio generale delle campagne: consente di tenere traccia di qualsiasi campagna che indirizza gli utenti alla tua applicazione.
Monitoraggio delle campagne Google Play
La release del sistema operativo Android 1.6 supporta l'utilizzo di un parametro URL referrer
nei link di download su Google Play. L'SDK Google Analytics per Android utilizza questo parametro per compilare automaticamente le informazioni sulla campagna in Google Analytics per la tua applicazione. Ciò consente di registrare l'origine dell'installazione dell'applicazione e di associarla a visualizzazioni di pagina ed eventi futuri, il che può essere utile per valutare l'efficacia di una determinata pubblicità per la tua app, ad esempio.
Affinché il monitoraggio dei referral funzioni, devi aggiungere il seguente snippet di codice al file manifest AndroidManifest.xml
del tuo progetto:
<!-- Used for install referrer tracking --> <receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER" /> </intent-filter> </receiver>
Per impostare il monitoraggio della campagna Google Analytics tramite Google Play, utilizza lo Strumento di creazione URL di seguito per generare un link del referral. Utilizza il link per indirizzare gli utenti alla tua applicazione. L'SDK Analytics analizza e registra automaticamente le informazioni sui referral e le inserisce nel report di Analytics.
Per generare il link del referral, puoi utilizzare lo Strumento di creazione URL per campagne di Google Play. Nome pacchetto, Sorgente campagna, Mezzo della campagna e Nome campagna sono obbligatori. Per una descrizione dettagliata di ciascun parametro, consulta la tabella riportata di seguito.
Monitoraggio di campagne generali
Con la versione 1.3 dell'SDK di Google Analytics per Android, puoi ora monitorare le campagne per sorgenti diverse da Google Play. Ad esempio, se vuoi sapere che la tua applicazione è stata lanciata da un link in un annuncio, puoi controllare le informazioni sui referral della campagna nello scopo che ha portato al lancio dell'applicazione e poi memorizzare le informazioni sulla campagna in Google Analytics.
Per impostare le informazioni sui referral della campagna, utilizza il metodo setReferrer
in questo modo:
tracker.setReferrer(referrer);
Esistono due limitazioni per l'utilizzo di questa funzionalità. Devi chiamare startNewSession
prima di chiamare
setReferrer
. Devi farlo perché il database SQLite utilizzato da Google Analytics non è configurato prima della chiamata a startNewSession
e setReferrer
necessita di questo database. Se non hai chiamato
startNewSession
, riceverai un IllegalStateException
.
La seconda limitazione è che la stringa di referral passata a setReferrer
deve seguire un formato specifico.
Deve assumere la forma di un insieme di parametri URL e includere almeno un parametro gclid oppure uno tra utm_campaign, utm_medium e utm_source ciascuno. Nel secondo caso, può anche avere i parametri utm_term e utm_content.
Il parametro gclid fa parte della funzione di tagging automatico, che collega automaticamente Google Analytics a Google Ads. Un referral di campagna di esempio che utilizza il tagging automatico potrebbe avere il seguente aspetto:
referrer = “gclid=gclidValue”;
La stringa di referral della campagna manuale potrebbe avere il seguente aspetto:
referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
Se trasmetti a setReferrer
una stringa referrer formattata in modo errato, le informazioni del referrer non verranno modificate e
ti verrà restituito il valore false. Un valore restituito pari a true indica che il referrer è stato aggiornato e che verrà aggiunto a ogni hit in futuro.
Nota inoltre che, con la chiamata a setReferrer, verrà avviata una nuova sessione che restituisce true.
Parametri per i link di referral
Parametro | Obbligatorio | Descrizione | Esempi |
---|---|---|---|
utm_campaign |
Sì | Nome della campagna; utilizzato per l'analisi delle parole chiave al fine di identificare una determinata promozione di prodotti o una campagna strategica | utm_campaign=spring_sale |
utm_source |
Sì | Sorgente della campagna; utilizzata per identificare un motore di ricerca, una newsletter o un'altra sorgente | utm_source=google |
utm_medium |
Sì | Mezzo della campagna; utilizzato per identificare un mezzo come email o costo per clic (CPC) | utm_medium=cpc |
utm_term |
No | Termine della campagna; utilizzato con la ricerca a pagamento per fornire le parole chiave per gli annunci | utm_term=running+shoes |
utm_content |
No | Contenuti della campagna; utilizzati per il test A/B e gli annunci con targeting basato sui contenuti al fine di differenziare gli annunci o i link che puntano allo stesso URL |
utm_content=logolink
utm_content=textlink
|