SDK Google Analytics pour iOS v1 (ancien)

Le SDK Google Analytics pour les applications mobiles pour iOS facilite la mise en œuvre de Google Analytics dans une application iOS. Ce document explique comment intégrer le SDK à vos applications.

Présentation du SDK

Ce SDK utilise un modèle de suivi conçu pour suivre les utilisateurs vers les sites Web traditionnels et les interactions avec les widgets des pages Web traditionnelles. Pour cette raison, les termes utilisés ci-dessous reflètent le modèle de suivi de site Web classique et sont actuellement mis en correspondance avec le suivi des applications mobiles. Vous devez connaître le suivi Analytics afin de comprendre le fonctionnement de ce SDK.

Le SDK de suivi des mobiles vous permet d'effectuer le suivi de vos applications pour téléphone avec les types d'interaction Analytics suivants:

Suivi des pages vues

Une page vue est un moyen standard de mesurer le volume du trafic vers un site Web traditionnel. Étant donné que les applications mobiles ne contiennent pas de pages HTML, vous devez décider quand (et à quelle fréquence) déclencher une requête de page vue. De plus, étant donné que les demandes de page vue sont conçues pour générer des rapports sur les structures de répertoires, vous devez leur fournir des noms descriptifs afin de tirer parti des noms des chemins de page dans les rapports "Contenu" d'Analytics. Les noms que vous choisissez seront insérés dans vos rapports Analytics en tant que chemins de page, même s'il ne s'agit pas de pages HTML. Toutefois, vous pouvez utiliser cette fonctionnalité à votre avantage en structurant les chemins afin de fournir des regroupements supplémentaires pour vos appels.

Suivi des événements

Dans Analytics, les événements sont conçus pour suivre les interactions des utilisateurs avec les éléments d'une page Web de manière distincte des demandes de page vue. Vous pouvez utiliser la fonctionnalité de suivi des événements de Google Analytics pour effectuer des appels supplémentaires indiqués dans la section "Suivi des événements" de l'interface des rapports Analytics. Les événements sont regroupés à l'aide de catégories et peuvent également utiliser des libellés par événement, ce qui permet de créer des rapports de manière flexible. Par exemple, une application multimédia peut avoir des actions lecture/arrêt/pause pour sa catégorie video et attribuer un libellé à chaque nom de vidéo. Les rapports Google Analytics regrouperont ensuite les événements de tous les événements associés à la catégorie vidéo. Pour en savoir plus sur le suivi des événements, consultez le Guide sur le suivi des événements.

Suivi du e-commerce

Utilisez la fonctionnalité de suivi de l'e-commerce pour suivre les transactions liées au panier et les achats via une application. Pour suivre une transaction, appelez la méthode addTransaction afin de créer une transaction globale, ainsi que la méthode addItem pour chaque produit du panier. Une fois collectées, les données peuvent être consultées dans la section "Rapports sur l'e-commerce" de l'interface Google Analytics. Pour en savoir plus sur le suivi de l'e-commerce, consultez le Guide de suivi du commerce électronique.

Variables personnalisées

Les variables personnalisées sont des balises de paire nom/valeur que vous pouvez insérer dans votre code de suivi afin d'affiner le suivi Google Analytics. Pour en savoir plus sur l'utilisation des variables personnalisées, consultez le guide sur les variables personnalisées.

Prise en charge NoThumb

Le SDK pour iPhone inclut désormais une version NoThumb de la bibliothèque ainsi que la version standard Thumb. Pour utiliser la version NoThumb de la bibliothèque, utilisez le fichier libGoogleAnalytics_NoThumb.a au lieu de libGoogleAnalytics.a.

Premiers pas

Conditions requises

Pour intégrer les fonctionnalités de suivi de Google Analytics dans votre application iOS, vous avez besoin des éléments suivants:

• SDK du développeur iOS (nécessite Xcode 3.1+ s'exécutant sous Mac OS X 10.5.3+)
• SDK Google Analytics pour applications mobiles pour iOS

Préparation

• Ouvrez Xcode et créez un projet iPhone OS.
• Faites glisser GANTracker.h et libGoogleAnalytics.a depuis le répertoire de la bibliothèque du SDK vers votre nouveau projet.
• Incluez le framework CFNetwork dans votre projet et établissez un lien avec libsqlite3.0.dylib.

Le SDK Google Analytics pour les applications mobiles doit fonctionner avec n'importe quel iPhone ou iPod Touch exécutant iOS 2.0 ou version ultérieure. La bibliothèque est compatible avec toutes les versions d'iOS qui prennent en charge les applications natives.

Le SDK inclut un exemple d'application qui montre à quoi devrait ressembler votre projet s'il est correctement configuré. N'hésitez pas à l'utiliser comme modèle pour vos propres applications intégrées à Analytics.

Utiliser le SDK

Avant de commencer à utiliser le SDK, vous devez d'abord créer un compte sans frais sur www.google.com/analytics, puis y créer une propriété Web en utilisant une fausse URL de site Web descriptive (par exemple, http://mymobileapp.mywebsite.com). Une fois la propriété créée, notez ou conservez une copie de l'ID de propriété Web généré pour la propriété nouvellement créée.

Vous devez indiquer à vos utilisateurs, dans l'application elle-même ou dans vos conditions d'utilisation, que vous vous réservez le droit de suivre et de signaler de manière anonyme l'activité d'un utilisateur au sein de votre application. Votre utilisation du SDK Google Analytics est également régie par les Conditions d'utilisation de Google Analytics, que vous devez accepter lors de la création d'un compte.

Exemples et bonnes pratiques

Vous trouverez un exemple de code et des bonnes pratiques sur code.google.com dans le projet analytics-api-samples.

Bibliothèque EasyTracker

Une bibliothèque EasyTracker est disponible. Il offre un suivi au niveau de l'application et de UIViewController sans pratiquement aucun effort de développement. Vous pouvez le trouver dans la section Téléchargements du projet analytics-api-samples.

Démarrage du coach électronique

Démarrez le traceur en appelant la méthode startTrackerWithAccountID sur le singleton du coach électronique obtenu via [GANTracker sharedTracker]. Il est souvent pratique d'appeler cette méthode directement dans la méthode applicationDidFinishLaunching du délégué de votre application. Transmettez l'ID de propriété Web, la période de distribution requise et le délégué facultatif. Exemple :

#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

Suivi des pages vues et des événements

Le suivi des pages vues et des événements est simple: il vous suffit d'appeler trackPageView de l'objet de suivi chaque fois que vous souhaitez déclencher une page vue. Appelez trackEvent pour enregistrer un événement. Pour en savoir plus sur les pages vues et les événements, consultez Présentation du SDK ci-dessus.

Utiliser des variables personnalisées

L'ajout d'une variable personnalisée est également simple: il vous suffit d'utiliser la méthode setCustomVariableAtIndex fournie par le SDK pour mobile. Vous devez planifier à l'avance les index auxquels chaque variable personnalisée est mappée, afin de ne pas écraser une variable existante. Pour en savoir plus sur les variables personnalisées, consultez le guide sur les variables personnalisées. Notez que la méthode setCustomVariableAtIndex n'envoie pas directement des données. Les données sont plutôt envoyées avec la page vue ou l'événement suivis suivants. Vous devez appeler setCustomVariableAtIndex avant de suivre une page vue ou un événement. Notez que le champ d'application par défaut des variables personnalisées est défini au niveau de la page.

Utilisation du suivi de l'e-commerce

Il existe quatre méthodes pour activer le suivi de l'e-commerce dans votre application:

• addTransaction
• addItem
• trackTransactions
• clearTransactions

Le fait d'appeler addTransaction et addItem ajoute la transaction ou l'article à un tampon d'e-commerce interne, auquel d'autres articles et transactions peuvent être ajoutés. Ce n'est que lorsque vous appelez trackTransactions que les transactions et les articles sont envoyés au coordinateur et mis en file d'attente pour être envoyés à Google Analytics.

Pour effacer le tampon, vous pouvez appeler la méthode clearTransactions. Remarque: il ne rappelle aucune transaction précédemment envoyée au coordinateur ni aucune transaction déjà collectée par Google Analytics.

L'exemple de code suivant peut vous aider à démarrer.

  /**
   * 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];
  }
}

Pour en savoir plus sur l'e-commerce, consultez le Guide de suivi du commerce électronique.

Rendre l'IP anonyme

Pour anonymiser les informations IP de l'utilisateur, définissez la propriété anonymizeIp sur "YES". Cela indique à Google Analytics d'anonymiser les informations envoyées par le SDK en supprimant le dernier octet de l'adresse IP avant son stockage.

Voici un exemple de configuration:

 [[GANTracker sharedTracker] setAnonymizeIp:YES];

Vous pouvez définir anonymizeIp à tout moment.

Définir le taux d'échantillonnage

Vous pouvez définir le taux d'échantillonnage à l'aide de la propriété sampleRate. Si votre application génère un trafic Analytics important, le fait de définir le taux d'échantillonnage peut empêcher la génération de vos rapports à l'aide de l'échantillonnage de données. L'échantillonnage est effectué de manière cohérente entre les utilisateurs uniques, de sorte que les tendances et les rapports sont préservés lorsque le taux d'échantillonnage est activé. Le paramètre sampleRate est un NSUInteger et peut avoir une valeur comprise entre 0 et 100 inclus. Voici un exemple qui baisse la valeur sampleRate à 95%:

 [[GANTracker sharedTracker] setSampleRate:95];

Un taux égal à 0 désactive la génération d'appels, tandis qu'un taux égal à 100 envoie toutes les données à Google Analytics. Il est préférable de définir sampleRate avant d'appeler des méthodes de suivi.

Pour en savoir plus sur l'échantillonnage, consultez le guide des concepts liés à l'échantillonnage.

Traitement des appels par lot

Pour économiser la connexion et l'autonomie de la batterie, nous vous recommandons de regrouper vos demandes de suivi par lot. Vous pouvez appeler dispatch sur l'objet de suivi chaque fois que vous souhaitez effectuer une requête par lot, manuellement ou à des intervalles de temps spécifiques.

Problèmes connus

Suivi des campagnes

Suivi général des campagnes

La version 1.3 du SDK Google Analytics pour iOS vous permet d'effectuer le suivi des campagnes référents. Par exemple, si votre application implémente un schéma d'URL personnalisé, vous pouvez créer une URL contenant les paramètres de requête de la campagne. Lorsque votre application se lance en réponse à une telle URL, vous pouvez récupérer les paramètres de requête et les transmettre à setReferrer afin que les informations soient stockées dans Google Analytics.

Pour définir les informations sur le site référent dans la campagne, utilisez la méthode setReferrer comme suit :

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

L'utilisation de cette fonctionnalité est soumise à deux restrictions. Vous devez d'abord appeler startTrackerWithAccountID avant d'appeler setReferrer. Vous devez le faire, car la base de données SQLite utilisée par Google Analytics n'est pas configurée avant d'appeler startTrackerWithAccountID, et setReferrer a besoin de cette base de données. Si vous n'avez pas appelé startTrackerWithAccountID, une erreur est renvoyée.

La deuxième restriction est que la chaîne de référence transmise à setReferrer doit respecter un format spécifique. Il doit prendre la forme d'un ensemble de paramètres d'URL et inclure au moins un paramètre gclid ou l'un des paramètres suivants pour utm_campaign, utm_medium et utm_source. Dans le dernier cas, il peut également comporter les paramètres utm_term et utm_content.

Le paramètre gclid fait partie de la fonctionnalité de taggage automatique qui associe automatiquement Google Analytics à Google Ads. Voici un exemple de parrainage de campagne utilisant le taggage automatique:

referrer = @“gclid=gclidValue”;

Voici à quoi pourrait ressembler la chaîne manuelle de parrainage pour la campagne:

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

Si vous transmettez une chaîne d'URL de provenance mal formatée à setReferrer, les informations de l'URL de provenance ne seront pas modifiées, et la valeur renvoyée sera "false". La valeur "true" renvoyée indique que l'URL de provenance a été mise à jour et sera ajoutée à chaque appel à l'avenir. Un message d'erreur s'affiche également. Vous pouvez l'inspecter pour en savoir plus sur le problème en cas d'échec de l'appel.

Notez également qu'une nouvelle session démarre lorsque vous appelez setReferrer et qu'elle renvoie la valeur "true".

Paramètres des liens référents