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 propose désormais des sous-classes de Tracker, ce qui entraîne des modifications de l'interface.
  • Nouveau : un indicateur dryRun a été ajouté pour empêcher l'affichage des données distribuées 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 devez disposer des éléments suivants:

Processus de mise à niveau

Pour commencer, sélectionnez un chemin de mise à niveau vers la version 3 à partir de votre mise en œuvre actuelle:

EasyTracker: v1.x à v3

Il est recommandé aux utilisateurs de EasyTracker v1.x 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 EasyTracker doivent suivre la procédure suivante pour terminer la mise à niveau vers la version 3:

  1. Mettez à jour les appels à EasyTracker.getInstance() pour fournir un Context:
    // v2 (Old)
    // EasyTracker.getInstance().activityStart(this);
    
    // v3:
    EasyTracker.getInstance(this).activityStart(this);
    
  2. EasyTracker sous-classes Tracker. Supprimez les appels à EasyTracker.getTracker() :
    // v2 (Old)
    Tracker v2Tracker = EasyTracker.getInstance().getTracker();
    
    // v3
    Tracker v3Tracker = EasyTracker.getInstance(this);
    
  3. Remplacez toutes les méthodes pratiques 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()
    );
    
    Découvrez comment envoyer des données dans la version 3.


  4. Remplacez le paramètre ga_debug EasyTracker 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 plus d'informations, consultez la documentation de référence sur les 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 un paramètre ga_dryRun EasyTracker et définissez-le sur true lorsque vous testez l'implémentation pour éviter que les données de test n'apparaissent dans vos rapports de production:
  7. <!-- 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 pour la configuration avancée, si nécessaire.

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

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

  1. Remplacez toutes les méthodes d'envoi populaires 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(), 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 lance plus automatiquement de nouvelle session à l'ouverture de l'application (sauf si vous utilisez EasyTracker). Si vous souhaitez conserver ce comportement à partir d'une implémentation personnalisée de la version 2, vous devez implémenter votre propre logique de contrôle de session lorsqu'un utilisateur démarre l'application:
  4. 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()
        );
      }
    }
    
    
  5. (Facultatif) Définissez l'option dryRun lors des tests pour empêcher le traitement des données de test avec vos rapports de production:
  6. // 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 expliquant comment définir et envoyer des données à l'aide du SDK V3.

Envoyer des données à l'aide de Maps dans la version 3

Dans la version 3, les données sont envoyées à l'aide d'une seule méthode send(), qui utilise un tableau (Map) de champs et de valeurs Google Analytics comme argument. 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 tous les types d'appels compatibles, tels que 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 le coach électronique dans la version 3

Les valeurs peuvent également être définies directement sur un Tracker à l'aide de la méthode set(). Les valeurs définies directement sont appliquées à tous les appels suivants à partir de cette propriété 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 qui a été 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 de données dans la version 3