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:
- Une propriété et un profil d'application compatibles avec Universal Analytics
- SDK Google Analytics pour Android v3
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
- EasyTracker: v2.x à v3
- Implémentation personnalisée: v1.x à v3
- Implémentation personnalisée: de la version 2.x à la version 3
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:
- Mettez à jour les appels à
EasyTracker.getInstance()
pour fournir unContext:
// v2 (Old) // EasyTracker.getInstance().activityStart(this);
// v3: EasyTracker.getInstance(this).activityStart(this);
EasyTracker
sous-classesTracker
. Supprimez les appels àEasyTracker.getTracker()
:// v2 (Old) Tracker v2Tracker = EasyTracker.getInstance().getTracker();
// v3 Tracker v3Tracker = EasyTracker.getInstance(this);
- Remplacez toutes les méthodes pratiques
send<hit-type>
par la nouvelle méthodesend(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. - Remplacez le paramètre
ga_debug
EasyTracker parga_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. GoogleAnalytics.requestAppOptOut()
est obsolète. UtilisezGoogleAnalytics.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();
- (Facultatif) Ajoutez un paramètre
ga_dryRun
EasyTracker et définissez-le surtrue
lorsque vous testez l'implémentation pour éviter que les données de test n'apparaissent 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 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:
- 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() );
- Supprimez les appels à
GoogleAnalytics.setDebug()
, remplacez-les parGoogleAnalytics.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 - 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:
- (Facultatif) Définissez l'option
dryRun
lors des tests pour empêcher le traitement des données de test avec vos rapports de production:
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() ); } }
// 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