SDK Google Analytics per iOS v1 (legacy)

L'SDK Google Analytics for Mobile Apps per iOS semplifica l'implementazione di Google Analytics nelle applicazioni basate su iOS. 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, 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 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.
Supporto di NoThumb
L'SDK per iPhone ora include una versione NoThumb della libreria e la versione Thumb standard. Per utilizzare la versione NoThumb della libreria, usa il file libGoogleAnalytics_NoThumb.a anziché il file libGoogleAnalytics.a.

Per iniziare

Requisiti

Per integrare le funzionalità di monitoraggio di Google Analytics con la tua app per iOS, devi disporre di quanto segue:

Configurazione

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

Google Analytics for Mobile Apps SDK dovrebbe funzionare con qualsiasi iPhone o iPod Touch con iOS 2.0 o versioni successive. La libreria è compatibile con tutte le versioni di iOS che supportano le applicazioni native.

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 il monitoraggio a livello di applicazione e UIViewController senza sforzi di sviluppo. Puoi trovarlo nella sezione Download del progetto analytics-api-samples.

Avvio del rilevatore

Avvia il tracker chiamando il metodo startTrackerWithAccountID sul singleton del tracker ottenuto tramite [GANTracker sharedTracker]. Spesso è conveniente chiamare questo metodo direttamente nel metodo applicationDidFinishLaunching del delegato dell'app. Passa 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 è 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 setCustomVariableAtIndex 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 setCustomVariableAtIndex non invia dati direttamente autonomamente. ma vengono inviati con la successiva visualizzazione di pagina o il successivo evento monitorato. 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, 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. 

  /**
   * 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 ulteriori informazioni sull'e-commerce, consulta la Guida al monitoraggio e-commerce.

Anonimizza IP

Per anonimizzare le informazioni sull'IP dell'utente, imposta la proprietà anonymizeIp su SÌ. Questo indica a Google Analytics di anonimizzare le informazioni inviate dall'SDK rimuovendo l'ultimo ottetto dell'indirizzo IP prima della sua archiviazione.

Ecco un esempio di come impostarla:

 [[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 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 parametro sampleRate è un parametro NSUInteger e può avere un valore compreso tra 0 e 100 inclusi. Ecco un esempio che riduce la metrica sampleRate al 95%:

 [[GANTracker sharedTracker] setSampleRate:95];

Una percentuale pari a 0 disattiva la generazione di hit, mentre una percentuale pari a 100 invia tutti i dati a Google Analytics. È preferibile impostare sampleRate 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

  • Referral/sorgenti di traffico: al momento non è possibile tracciare la sorgente della campagna/dei referral del download di un'app sul dispositivo iOS.
  • Sconsigliamo vivamente di chiamare dispatch nelle seguenti situazioni:
    • Nel metodo applicationWillTerminate
    • In applicationDidEnterBackground
    • Prima di chiamare stopTracker
    In questo modo, gli hit potrebbero essere inviati due volte. Usa invece il metodo dispatchSynchronous:.
  • Chiamare metodi GANTracker su diversi thread può causare errori SQLite poco chiari. Assicurati di effettuare tutte le chiamate dallo stesso thread.

    • Monitoraggio delle campagne

    Monitoraggio di campagne generali

    Con la versione 1.3 dell'SDK 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 contenente i parametri di query della campagna. Quando l'applicazione viene avviata in risposta a un URL di questo tipo, puoi recuperare i parametri di query e passarli a setReferrer, in modo che le informazioni vengano memorizzate in Google Analytics.

    Per impostare le informazioni sui referral della campagna, utilizza il metodo setReferrer in questo modo: 

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

    Esistono due limitazioni per l'utilizzo di questa funzionalità. Devi chiamare startTrackerWithAccountID prima di chiamare setReferrer. Devi farlo perché il database SQLite utilizzato da Google Analytics non è configurato prima della chiamata a startTrackerWithAccountID e setReferrer necessita di questo database. Se non hai chiamato startTrackerWithAccountID, verrà restituito un errore.

    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. Ti verrà inoltre restituito un errore che puoi ispezionare per ottenere dettagli su cosa non ha funzionato nel caso in cui la chiamata non sia andata a buon fine.

    Nota inoltre che, con la chiamata a setReferrer, verrà avviata una nuova sessione che restituisce true.

    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