SDK Google Analytics pour Android v1 (ancien)

Le SDK Google Analytics pour les applications mobiles pour Android facilite la mise en œuvre de Google Analytics dans une application Android. 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, utilisez la classe Transaction pour représenter les informations d'achat globales et la classe Item pour représenter 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.

Premiers pas

Conditions requises

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

Préparation

  • Ajoutez libGoogleAnalytics.jar au répertoire /libs de votre projet.
  • Ajoutez les autorisations suivantes au fichier manifeste AndroidManifest.xml de votre projet :
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

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. Elle offre un suivi au niveau de l'application et de l'activité 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

Obtenez le singleton du traceur en appelant GoogleAnalyticsTracker.getInstance(). Appelez ensuite sa méthode startNewSession, en transmettant l'ID de propriété Web et l'activité suivie. Vous pouvez appeler cette méthode directement dans la méthode onCreate de votre activité si votre application ne comporte qu'une seule activité. Exemple :

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();
  }
}

Si votre application comporte plusieurs activités, vous pouvez utiliser la bibliothèque EasyTracker fournie dans la section Téléchargements du projet analytics-api-samples.

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 setCustomVar 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 setCustomVar 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 setCustomVar 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. Nous supposons que la méthode onPurchaseCompleted est appelée lorsque l'achat est confirmé ou refusé. 

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

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

Rendre l'IP anonyme

Pour anonymiser les informations d'adresse IP de l'utilisateur, utilisez la méthode setAnonymizeIp. 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.

Vous pouvez appeler setAnonymizeIp à tout moment.

Définir le taux d'échantillonnage

Vous pouvez définir le taux d'échantillonnage à l'aide de la méthode setSampleRate. 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é. La méthode setSampleRate accepte un paramètre int. Les valeurs valides pour ce paramètre sont des nombres entiers compris entre 0 et 100 inclus.

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 d'appeler setSampleRate 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

  • L'appel des méthodes GoogleAnalyticsTracker dans différents threads peut entraîner des erreurs obscures. Assurez-vous d'effectuer tous vos appels à partir du même thread.

    • Suivi des campagnes

    Le SDK accepte deux types de suivi des campagnes.

    - Suivi des campagnes Google Play : permet de suivre les sites référents d'installation via Google Play.
    - Suivi général des campagnes : permet d'effectuer le suivi de toute campagne redirigeant les utilisateurs vers votre application.

    Suivi des campagnes Google Play

    La version de l'OS Android 1.6 permet d'utiliser un paramètre d'URL referrer dans les liens de téléchargement vers Google Play. Le SDK Google Analytics pour Android utilise ce paramètre afin de renseigner automatiquement les informations de campagne dans Google Analytics pour votre application. Cela permet d'enregistrer la source de l'installation de l'application et de l'associer aux pages vues et aux événements à venir, ce qui peut s'avérer utile pour évaluer l'efficacité d'une publicité spécifique pour votre application, par exemple.

    Pour que le suivi des sites référents fonctionne, vous devez ajouter l'extrait de code suivant au fichier manifeste AndroidManifest.xml de votre projet:

    <!-- 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>

    Pour configurer le suivi des campagnes Google Analytics via Google Play, utilisez l'outil de création d'URL ci-dessous afin de générer un lien référent. Utilisez ce lien pour rediriger les utilisateurs vers votre application. Le SDK Analytics analysera et enregistrera automatiquement les informations sur le site référent, puis les renseignera dans votre rapport Analytics.

    Pour générer le lien référent, vous pouvez utiliser l'outil de création d'URL des campagnes Google Play. Les champs Nom du package, Source de la campagne, Support de la campagne et Nom de la campagne sont obligatoires. Pour obtenir une description détaillée de chaque paramètre, consultez le tableau ci-dessous.

    Suivi général des campagnes

    Avec la version 1.3 du SDK Google Analytics pour Android, vous pouvez désormais suivre des campagnes pour des sources autres que Google Play. Par exemple, si vous souhaitez savoir que votre application a été lancée à partir d'un lien inclus dans une annonce, vous pouvez rechercher les informations sur le site référent dans l'intent ayant entraîné le lancement de votre application, puis stocker ces informations dans Google Analytics.

    Pour définir les informations sur les sites référents de la campagne, utilisez la méthode setReferrer comme suit : 

      tracker.setReferrer(referrer);

    L'utilisation de cette fonctionnalité est soumise à deux restrictions. Vous devez d'abord appeler startNewSession 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 startNewSession, et setReferrer a besoin de cette base de données. Si vous n'avez pas appelé startNewSession, vous recevez une IllegalStateException.

    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.

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

    Paramètres Obligatoire Description Exemple(s)
    utm_campaign Oui Nom de la campagne, utilisé pour l'analyse des mots clés afin d'identifier une campagne stratégique ou une promotion spécifique sur un produit utm_campaign=spring_sale
    utm_source Oui Source de la campagne : permet d'identifier un moteur de recherche, une newsletter ou une autre source utm_source=google
    utm_medium Oui "Support de la campagne" : permet d'identifier un support tel qu'un e-mail ou le coût par clic (CPC) utm_medium=cpc
    utm_term Non Terme de la campagne : utilisé avec la recherche sponsorisée pour fournir les mots clés des annonces utm_term=running+shoes
    utm_content Non Contenu de la campagne ; utilisé pour les tests A/B et les annonces ciblées sur le réseau de contenu afin de différencier les annonces ou liens qui renvoient vers la même URL utm_content=logolink
    utm_content=textlink