Google Analytics SDK for iOS v1 (versione precedente)

L'SDK Google Analytics per dispositivi mobili per iOS semplifica l'implementazione di Google Analytics in un'applicazione basata su iOS. Questo documento descrive come integrare l'SDK nelle tue app.

Panoramica dell'SDK

Questo SDK utilizza un modello di monitoraggio progettato per monitorare gli utenti su siti web tradizionali e interagire con i widget nelle pagine web tradizionali. Per questo motivo, i termini utilizzati di seguito riflettono il modello di monitoraggio convenzionale del sito web e vengono mappati per il monitoraggio delle applicazioni per dispositivi mobili. Dovresti conoscere il monitoraggio di Analytics per comprendere il funzionamento di questo SDK.

Utilizza l'SDK per il monitoraggio dei dispositivi mobili per monitorare le tue applicazioni telefoniche con i seguenti tipi di interazione di Analytics:

Monitoraggio delle visualizzazioni di pagina
Una visualizzazione di pagina è un mezzo standard per misurare il volume di traffico verso un sito web tradizionale. Poiché le app per dispositivi mobili 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 di directory, devi fornire nomi descrittivi affinché le richieste possano sfruttare la denominazione dei percorsi delle pagine nei report sui contenuti in Analytics. I nomi che scegli verranno inseriti nei report di Analytics come percorsi pagina, anche se in realtà non sono pagine HTML, ma puoi sfruttare questa situazione a tuo vantaggio strutturando i percorsi per 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, indipendentemente dalle richieste di visualizzazione di pagina. Puoi utilizzare la funzionalità di monitoraggio eventi di Google Analytics per effettuare chiamate aggiuntive che verranno segnalate nella sezione Monitoraggio eventi dell'interfaccia del report Analytics. Gli eventi vengono raggruppati utilizzando categorie e possono anche utilizzare etichette per evento, che offrono flessibilità nei report. Ad esempio, un'app multimediale potrebbe avere azioni di riproduzione/interruzione/pausa per la relativa categoria video e assegnare un'etichetta per ogni nome di video. I report di Google Analytics aggregano quindi gli eventi per tutti gli eventi taggati con la categoria video. Per scoprire di più 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 e gli acquisti in-app. Per monitorare una transazione, chiama il metodo addTransaction per creare una transazione complessiva e il metodo addItem per ogni prodotto nel carrello degli acquisti. Una volta raccolti, i dati possono essere visualizzati nella sezione dei rapporti E-commerce dell'interfaccia di Google Analytics. Per scoprire di più sul monitoraggio e-commerce, consulta la Guida al monitoraggio e-commerce.
Variabili personalizzate
Le variabili personalizzate sono tag di coppie 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.
Supporto NoThumb
L'SDK per iPhone ora include una versione NoThumb della libreria e la versione standard Thumb. Per utilizzare la versione NoThumb della raccolta, utilizza il file libGoogleAnalytics_NoThumb.a anziché il file libGoogleAnalytics.a.

Per iniziare

Requisiti

Per integrare le funzionalità di monitoraggio di Google Analytics nella tua app per iOS, devi disporre di:

Configurazione

  • Apri Xcode e crea un nuovo progetto del sistema operativo iPhone.
  • Trascina GANTracker.h e libGoogleAnalytics.a dalla directory della libreria dell'SDK nel nuovo progetto.
  • Includi il framework CFNetwork nel tuo progetto e collegalo a libsqlite3.0.dylib.

L'SDK Google Analytics per le app per dispositivi mobili dovrebbe essere compatibile con qualsiasi iPhone o iPod touch che esegue iOS 2.0 o versioni successive: la libreria è compatibile con tutte le versioni iOS che supportano le applicazioni native.

Nell'SDK è inclusa un'applicazione di esempio che mostra l'aspetto del 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 tale 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 agli utenti, nell'applicazione stessa o nei tuoi termini di servizio, che ti riserva il diritto di monitorare e segnalare in modo anonimo l'attività di un utente all'interno della tua app. L'utilizzo dell'SDK di Google Analytics è inoltre regolato dai Termini di servizio di Google Analytics, che devi accettare al momento della registrazione per un account.

Esempi e best practice

Puoi trovare codice di esempio e best practice su code.google.com nel progetto analytics-api-samples.

Libreria EasyTracker

È disponibile una libreria EasyTracker. Fornisce il monitoraggio a livello di applicazione e di UIView senza quasi alcuna attività di sviluppo. È disponibile nella sezione Download del progetto analytics-api-samples.

Avvio del tracker

Avvia il tracker chiamando il metodo startTrackerWithAccountID sul singleton tracker ottenuto tramite [GANTracker sharedTracker]. Spesso è utile chiamare questo metodo direttamente nel metodo applicationDidFinishLaunching del delegato della tua app. Trasmetti l'ID proprietà web, il periodo di spedizione richiesto e un delegato facoltativo. Ad esempio:

#import "BasicExampleAppDelegate.h"

#import "GANTracker.h"

// Dispatch period in seconds
static const NSInteger kGANDispatchPeriodSec = 10;

@implementation BasicExampleAppDelegate

@synthesize window = window_;

- (void)applicationDidFinishLaunching:(UIApplication *)application {
  // **************************************************************************
  // PLEASE REPLACE WITH YOUR ACCOUNT DETAILS.
  // **************************************************************************
  [[GANTracker sharedTracker] startTrackerWithAccountID:@"UA-0000000-1"
                                        dispatchPeriod:kGANDispatchPeriodSec
                                              delegate:nil];

  NSError *error;
  if (![[GANTracker sharedTracker] setCustomVariableAtIndex:1
                                                       name:@"iPhone1"
                                                      value:@"iv1"
                                                  withError:&error]) {
    // Handle error here
  }

  if (![[GANTracker sharedTracker] trackEvent:@"my_category"
                                       action:@"my_action"
                                        label:@"my_label"
                                        value:-1
                                   withError:&error]) {
    // Handle error here
  }

  if (![[GANTracker sharedTracker] trackPageview:@"/app_entry_point"
                                   withError:&error]) {
    // Handle error here
  }

  [window_ makeKeyAndVisible];
}

- (void)dealloc {
  [[GANTracker sharedTracker] stopTracker];
  [window_ release];
  [super dealloc];
}

@end

Monitoraggio di visualizzazioni di pagina ed eventi

Il monitoraggio delle visualizzazioni di pagina e degli eventi è semplice: basta chiamare trackPageView dell'oggetto tracker ogni volta che vuoi attivare una visualizzazione di pagina. Chiama il numero trackEvent per registrare un evento. Per ulteriori informazioni sulle visualizzazioni di pagina e sugli eventi, consulta la panoramica sull'SDK in alto.

Utilizzo delle variabili personalizzate

Anche l'aggiunta di una variabile personalizzata è semplice: basta utilizzare il metodo setCustomVariableAtIndex fornito dall'SDK per dispositivi mobili. Ti consigliamo di pianificare in anticipo il momento in cui ogni variabile personalizzata viene mappata, in modo da non sovrascrivere alcuna variabile esistente. Per scoprire di più sulle variabili personalizzate, consulta la Guida alle variabili personalizzate. Tieni presente che il metodo setCustomVariableAtIndex non invia direttamente i dati da solo. Piuttosto, i dati vengono inviati con l'evento o la visualizzazione di pagina monitorata successiva. Devi chiamare setCustomVariableAtIndex 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, viene aggiunta la transazione o l'elemento a un buffer di e-commerce interno, a cui possono essere aggiunti altri elementi e transazioni. Solo quando chiami trackTransactions, le transazioni e gli elementi vengono inviati al committente e vengono messi in coda per essere inviati a Google Analytics.

Per cancellare il buffer, puoi chiamare il metodo clearTransactions. Nota: non ricorda le transazioni inviate in precedenza al committente, né le transazioni già raccolte da Google Analytics.

Il seguente codice di esempio può aiutarti a iniziare.

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   */
- (void) processPurchase:Purchase purchase {
  [[GANTracker sharedTracker] addTransaction:[purchase transactionId]
                                  totalPrice:[purchase totalPrice]
                                   storeName:[purchase store]
                                    totalTax:[purchase tax]
                                shippingCost:[purchase shipping]
                                   withError:&error];
  if (error) {
    // Handle error
  }
  for (PurchaseItem item in [purchase items]) {
    [[GANTracker sharedTracker] addItem:[purchase transactionId]
                                itemSKU:[item itemSKU]
                              itemPrice:[item price]
                              itemCount:[item count]
                           itemCategory:[item category]
                              withError:&error];
    if (error) {
      // Handle error
    }
  }

  if ([purchase isConfirmed]) {
    [[GANTracker sharedTracker] trackTransactions:&error];
  } 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.
    [[GANTracker sharedTracker] clearTransactions:&error];
  }
}

Per scoprire di più sull'e-commerce, consulta la guida al monitoraggio e-commerce.

Anonimizza IP

Per rendere anonimi i dati IP dell'utente, imposta la proprietà anonymizeIp su YES. In questo modo, Google Analytics anonimizza le informazioni inviate dall'SDK rimuovendo l'ultimo ottetto dell'indirizzo IP prima del suo spazio di archiviazione.

Ecco un esempio di impostazione:

 [[GANTracker sharedTracker] setAnonymizeIp:YES];

Puoi impostare anonymizeIp in qualsiasi momento.

Impostazione della frequenza di campionamento

Puoi impostare la frequenza di campionamento utilizzando la proprietà sampleRate. Se la tua applicazione genera molto traffico Analytics, l'impostazione della frequenza di campionamento potrebbe impedire la generazione dei report utilizzando i dati campionati. Il campionamento avviene in modo coerente tra gli utenti unici, pertanto è presente l'integrità nelle tendenze e nei report quando viene attivata la frequenza di campionamento. Il parametro sampleRate è un NSUInteger e può avere un valore compreso tra 0 e 100, inclusi. Ecco un esempio in cui il sampleRate viene ridotto al 95%:

 [[GANTracker sharedTracker] setSampleRate:95];

Una percentuale pari a 0 disattiva la generazione di hit, mentre una frequenza di 100 invia tutti i dati a Google Analytics. È meglio impostare sampleRate prima di chiamare qualsiasi metodo di monitoraggio.

Puoi trovare ulteriori informazioni sul campionamento nella Guida ai concetti di campionamento.

Grandi successi

Per risparmiare sui costi di connessione e batteria, si consiglia di raggruppare le richieste di monitoraggio. Puoi chiamare dispatch sull'oggetto di monitoraggio ogni volta che vuoi effettuare una richiesta in batch e puoi farlo manualmente o a intervalli di tempo specifici.

Problemi noti

  • Referral/Sorgenti di traffico: al momento non è possibile tracciare la campagna/la sorgente di referral di un download di app sul dispositivo iOS.
  • Sconsigliamo vivamente di chiamare dispatch nelle seguenti situazioni:
    • Nel metodo applicationWillTerminate
    • In applicationDidEnterBackground
    • Prima di chiamare il numero stopTracker
    Questo potrebbe comportare l'invio di due hit. Utilizza invece il metodo dispatchSynchronous:.
  • Chiamare i metodi GANTracker su thread diversi può causare errori di SQLite oscuranti. Assicurati di effettuare tutte le chiamate dallo stesso thread.
  • Monitoraggio delle campagne

    Monitoraggio generale della campagna

    Con la versione 1.3 dell'SDK di Google Analytics per iOS ora puoi monitorare i referral delle campagne. Ad esempio, se la tua applicazione implementa uno schema URL personalizzato, puoi creare un URL che contenga parametri di ricerca della campagna. Quando la tua applicazione viene avviata in risposta a questo URL, puoi recuperare i parametri di ricerca e trasmetterli a setReferrer in modo che le informazioni vengano memorizzate in Google Analytics.

    Per impostare le informazioni sui referral della campagna, utilizza il metodo setReferrer nel seguente modo:

      [[GANTracker sharedTracker] setReferrer:referrer withError:&error];
    

    Esistono due limitazioni relative all'uso di questa funzionalità. Prima di chiamare setReferrer, devi chiamare startTrackerWithAccountID. È necessario farlo perché il database SQLite utilizzato da Google Analytics non è configurato prima che le chiamate a startTrackerWithAccountID e setReferrer richiedano tale database. Se non hai chiamato startTrackerWithAccountID, riceverai un messaggio di errore.

    La seconda limitazione è che la stringa di referral trasferita in setReferrer deve seguire un formato specifico. Deve avere la forma di un insieme di parametri URL e deve includere almeno un parametro gclid o uno di ciascun parametro utm_campaign, utm_medium e utm_source. Nell'ultimo caso, può avere anche i parametri utm_term e utm_content.

    Il parametro gclid fa parte della funzionalità di codifica automatica che collega automaticamente Google Analytics a Google Ads. Un referral di esempio della campagna che utilizza il tagging automatico potrebbe avere il seguente aspetto:

    referrer = @“gclid=gclidValue”;
    

    La stringa di referral manuale della campagna potrebbe avere il seguente aspetto:

    referrer = @“utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
    

    Se passi una stringa referrer errata a setReferrer, le informazioni del referrer non verranno modificate e il valore restituito sarà false. Un valore di ritorno pari a true indica che il referrer è stato aggiornato e in futuro verrà aggiunto a ogni hit. Inoltre verrà restituito un errore che puoi controllare per visualizzare i dettagli dell'errore che si è verificato nel caso in cui la chiamata non sia riuscita.

    Inoltre, tieni presente che, quando chiami setReferrer, viene avviata una nuova sessione che restituisce true.

    Parametro Obbligatorio Descrizione Esempi
    utm_campaign Nome campagna; utilizzato per l'analisi delle parole chiave per identificare una specifica promozione di prodotto o campagna strategica utm_campaign=spring_sale
    utm_source Sorgente della campagna; utilizzata per identificare un motore di ricerca, una newsletter o un'altra sorgente. utm_source=google
    utm_medium 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 test A/B e annunci con targeting dei contenuti per distinguere annunci o link che rimandano allo stesso URL utm_content=logolink
    utm_content=textlink