SDK Google Analytics pour Android: migration vers la version 3

Ce guide explique comment passer à la version 3 du SDK Google Analytics pour Android.

Aperçu: nouveautés de la version 3

Les API de la version 3 ont été refactorisées pour être plus cohérentes sur les plates-formes natives et Web. Tous les utilisateurs de la version 2 doivent noter les changements suivants:

• Les appels sont désormais envoyés à l'aide d'une seule méthode send(Map<String, String> parameters).
• Le mode débogage a été remplacé par un Logger
• EasyTracker sous-classe désormais Tracker, ce qui entraîne des modifications de l'interface.
• Nouveau : un indicateur dryRun a été ajouté pour empêcher les données distribuées d'apparaître dans les rapports.

Pour obtenir la liste complète des modifications, consultez le journal des modifications Android.

Avant de commencer

Avant de passer à la version 3, vous avez besoin des éléments suivants:

• Une propriété Universal Analytics et un profil d'application
• SDK Google Analytics pour Android v3

Méthodes de mise à niveau

Pour commencer, choisissez un processus de mise à niveau vers la v3 dans votre implémentation actuelle:

• EasyTracker: de la version 1.x à la version 3
• EasyTracker: de la version 2.x à la version 3
• Implémentation personnalisée: de la v1.x à la v3
• Implémentation personnalisée: de la v2.x à la v3

EasyTracker: v1.x à v3

Il est recommandé aux utilisateurs de la version 1.x d'EasyTracker de suivre le Guide de démarrage de la version 3 pour commencer à utiliser la version 3 avec EasyTracker.

EasyTracker: v2.x à v3

Les utilisateurs de la version 2.x d'EasyTracker doivent suivre ces étapes pour effectuer la mise à niveau vers la version 3:

1. Mettre à jour les appels à EasyTracker.getInstance() pour fournir un Context:

   // v2 (Old)
   // EasyTracker.getInstance().activityStart(this);
   

   // v3:
   EasyTracker.getInstance(this).activityStart(this);
   

2. EasyTracker sous-classe désormais Tracker. Suppression des appels à EasyTracker.getTracker() :

   // v2 (Old)
   Tracker v2Tracker = EasyTracker.getInstance().getTracker();
   

   // v3
   Tracker v3Tracker = EasyTracker.getInstance(this);
   

3. Remplacez toutes les méthodes pratiques de send<hit-type> par la nouvelle méthode send(Map<String, String> parameters) :

   // v2 (Old)
   Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this);
   v2EasyTracker.sendView("Home Screen");
   

   // v3
   Tracker v3EasyTracker = EasyTracker.getInstance(this);
   
   // Set the screen name on the tracker so that it is used in all hits sent from this screen.
   v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen");
   
   // Send a screenview.
   v3EasyTracker.send(MapBuilder
     .createAppView()
     .build()
   );
   

   En savoir plus sur l'envoi de données dans la version 3



4. Remplacez le paramètre EasyTracker ga_debug par ga_logLevel et l'une des valeurs de verbosité suivantes : verbose, info, warning, error :

   <!-- res/values/analytics.xml -->
   
   <?xml version="1.0" encoding="utf-8"?>
   <resources>
     <string name="ga_trackingId">UA-XXXX-Y</string>
     <!-- REMOVE: <bool name="ga_debug">true</bool> -->
     <string name="ga_logLevel">verbose</string>
   </resources>
   

   Pour en savoir plus, consultez la documentation de référence des paramètres EasyTracker.



5. GoogleAnalytics.requestAppOptOut() est obsolète. Utilisez GoogleAnalytics.getAppOptOut() à la place :

   // v2 (Old)
   GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() {
      @Override
      public void reportAppOptOut(boolean optOut) {
        if (optOut) {
        ... // Alert the user that they've opted out.
        }
      });
   }
   

   // v3
   boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
   

6. (Facultatif) Ajoutez le paramètre EasyTracker ga_dryRun et définissez-le sur true lors du test de votre implémentation pour empêcher l'affichage de données de test dans vos rapports de production:

<!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>

<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <string name="ga_logLevel">verbose</string>

  <!-- Prevent data from appearing in reports. Useful for testing. -->
  <bool name="ga_dryRun">true</bool>

</resources>

Implémentation personnalisée: v1.x à v3

Les utilisateurs de la version 1.x qui n'utilisent pas EasyTracker doivent suivre le guide de démarrage de la version 3 et consulter le guide du développeur sur la configuration avancée si nécessaire.

Implémentation personnalisée: v2.x à v3

Les utilisateurs de la version 2.x qui n'utilisent pas EasyTracker doivent suivre les étapes ci-dessous pour passer à la version 3:

1. Remplacez toutes les méthodes pratiques "send<hit-type>" par la nouvelle méthode send(Map<String, String> parameters) :

   // v2 (Old)
   Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
   v2Tracker.sendView("Home Screen");
   

   // v3
   Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
   
   // This screen name value will remain set on the tracker and sent with
   // hits until it is set to a new value or to null.
   v3Tracker.set(Fields.SCREEN_NAME, "Home Screen");
   
   v3Tracker.send(MapBuilder
     .createAppView()
     .build()
   );
   

2. Supprimez les appels à GoogleAnalytics.setDebug() et remplacez-les par GoogleAnalytics.getLogger().setLogLevel() :

   // V2 (Old)
   GoogleAnalytics.getInstance(this).setDebug(true);
   

   // V3
   GoogleAnalytics.getInstance(this)
       .getLogger()
       .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
   

   En savoir plus sur Logger


3. Le SDK v3 ne démarre plus automatiquement une nouvelle session à l'ouverture de l'application (sauf lorsque vous utilisez EasyTracker). Si vous souhaitez conserver ce comportement issu d'une implémentation personnalisée v2, vous devez implémenter votre propre logique de contrôle de session lorsqu'un utilisateur démarre l'application:

package com.example.app;

import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;

public class MyApp extends Application {

  private static Tracker mTracker;
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  @Override
  public void onCreate() {
    super.onCreate();
    mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID);

    // CAUTION: Setting session control directly on the tracker persists the
    // value across all subsequent hits, until it is manually set to null.
    // This should never be done in normal operation.
    //
    // mTracker.set(Fields.SESSION_CONTROL, "start");

    // Instead, send a single hit with session control to start the new session.
    mTracker.send(MapBuilder
      .createEvent("UX", "appstart", null, null)
      .set(Fields.SESSION_CONTROL, "start")
      .build()
    );
  }
}

4. (Facultatif) Définissez l'option dryRun lors des tests pour empêcher le traitement des données de test avec vos rapports de production:

// When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

Reference

Les sections suivantes fournissent des exemples de référence sur la définition et l'envoi de données à l'aide du SDK V3.

Envoyer des données avec Google Maps dans la version 3

Dans la version 3, les données sont envoyées à l'aide d'une seule méthode send() qui accepte comme argument un Map de champs et de valeurs Google Analytics. Une classe utilitaire MapBuilder est fournie pour simplifier le processus de création des appels:

// Sending a screenview in v3 using MapBuilder.
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");
tracker.set(Fields.SCREEN_NAME, "Home Screen");

tracker.send(MapBuilder
  .createAppView()                           // Creates a Map of hit type 'AppView' (screenview).
  .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit.
  .build()                                   // Build and return the Map to the send method.
);

La classe MapBuilder peut être utilisée pour créer n'importe quel type d'appel compatible, comme des événements:

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

En savoir plus sur l'envoi de données dans la version 3

Définition des données sur l'outil de suivi dans la version 3

Les valeurs peuvent également être définies directement dans un Tracker à l'aide de la méthode set(). Les valeurs définies directement sont appliquées à tous les appels suivants à partir de ce Tracker :

// Values set directly on a tracker apply to all subsequent hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// This screenview hit will include the screen name "Home Screen".
tracker.send(MapBuilder.createAppView().build());

// And so will this event hit.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

Pour effacer une valeur définie dans Tracker, définissez la propriété sur null:

// Clear the previously-set screen name value.
tracker.set(Fields.SCREEN_NAME, null);

// Now this event hit will not include a screen name value.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

En savoir plus sur la définition des données dans la version 3