Configuration avancée

Ce document présente certaines des fonctionnalités de configuration avancées du SDK Google Analytics v4 pour Android.

Présentation

Le SDK Google Analytics v4 pour Android fournit une classe Tracker pour définir et envoyer des données à Google Analytics, ainsi qu'un singleton GoogleAnalytics qui sert d'interface avec les valeurs de configuration globales de votre implémentation.

Initialisation

Avant de pouvoir mesurer des données, vous devez initialiser au moins un outil de suivi via le singleton GoogleAnalytics en fournissant un objet Context et un ID de propriété Google Analytics. Pour en savoir plus, consultez la documentation de référence Google Analytics.

Utiliser un fichier de configuration

Il est également possible d'initialiser un outil de suivi à l'aide d'un fichier de configuration. Exemple :

package com.google.android.apps.mobileplayground;

import android.app.Application;
import com.google.android.gms.analytics.GoogleAnalytics;
import com.google.android.gms.analytics.Tracker;
import java.util.HashMap;

/**
 * An extension to Application class to provide tracker for analytics purposes. Having the tracker
 * instances here allows all the activities to access the same tracker instances. The trackers can
 * be initialised on startup or when they are required based on performance requirements.
 */
public class AnalyticsSampleApp extends Application {

  // The following line should be changed to include the correct property id.
  private static final String PROPERTY_ID = "UA-XXXXX-Y";

  /**
   * Enum used to identify the tracker that needs to be used for tracking.
   *
   * A single tracker is usually enough for most purposes. In case you do need multiple trackers,
   * storing them all in Application object helps ensure that they are created only once per
   * application instance.
   */
  public enum TrackerName {
    APP_TRACKER, // Tracker used only in this app.
    GLOBAL_TRACKER, // Tracker used by all the apps from a company. eg: roll-up tracking.
    ECOMMERCE_TRACKER, // Tracker used by all ecommerce transactions from a company.
  }

  HashMap<TrackerName, Tracker> mTrackers = new HashMap<TrackerName, Tracker>();

  public AnalyticsSampleApp() {
    super();
  }
  synchronized Tracker getTracker(TrackerName trackerId) {
    if (!mTrackers.containsKey(trackerId)) {

      GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);
      Tracker t = (trackerId == TrackerName.APP_TRACKER) ? analytics.newTracker(PROPERTY_ID)
          : (trackerId == TrackerName.GLOBAL_TRACKER) ? analytics.newTracker(R.xml.global_tracker)
              : analytics.newTracker(R.xml.ecommerce_tracker);
      mTrackers.put(trackerId, t);

    }
    return mTrackers.get(trackerId);
  }
}

Configuration et envoi de données

Les données sont envoyées à Google Analytics à l'aide d'outils de création permettant de définir des paires paramètre-valeur qui les envoient via la méthode send de l'outil de suivi.

L'exemple suivant montre comment envoyer un visionnage de l'écran à Google Analytics en créant une vue d'application et en appelant la méthode d'envoi du suivi:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

Syntaxe des esperluettes du protocole de mesure

Vous pouvez utiliser l'esperluette du protocole de mesure pour définir les valeurs d'un appel unique avec un HitBuilders.ScreenViewBuilder. Pour définir des valeurs pour tous les appels suivants, utilisez l'objet de suivi lui-même.

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(new HitBuilders.ScreenViewBuilder()
  .set("&cd", "Home Screen")
  .build()
);

Pour obtenir la liste complète des paramètres du protocole de mesure, consultez la documentation de référence sur les paramètres du protocole de mesure.

Appliquer des valeurs à plusieurs appels

Toutes les valeurs définies directement dans l'outil de suivi seront conservées et appliquées à plusieurs appels, comme dans cet exemple:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Set screen name.
t.setScreenName(screenName);

// Send a screen view.
t.send(new HitBuilders.ScreenViewBuilder().build());

// This event will also be sent with the most recently set screen name.
// Build and send an Event.
t.send(new HitBuilders.EventBuilder()
    .setCategory(getString(categoryId))
    .setAction(getString(actionId))
    .setLabel(getString(labelId))
    .build());

// Clear the screen name field when we're done.
t.setScreenName(null);

Seules les valeurs que vous souhaitez conserver pour plusieurs appels doivent être définies directement dans l'outil de suivi. Il serait logique de définir un nom d'écran sur un coach électronique, car la même valeur peut être appliquée aux appels de type visionnage d'écran et événement ultérieurs. Cependant, il n'est pas recommandé de définir un champ tel que le type d'appel sur l'outil de suivi, car il sera probablement modifié à chaque appel.

Utilisation de plusieurs coachs électroniques

Dans votre application mobile, vous pouvez utiliser plusieurs outils de suivi pour envoyer des données à différentes propriétés:


public class MyApp extends Application {

  public void initTrackers() {
    GoogleAnalytics analytics = GoogleAnalytics.getInstance(this);

    globalTracker = analytics.newTracker(R.xml.global_tracker);
    ecommerceTracker = analytics.newTracker(R.xml.ecommerce_tracker);
  }

  public static Tracker globalTracker;
  public static Tracker ecommerceTracker;

  ...
}

Bien que votre application mobile puisse comporter plusieurs outils de suivi, vous ne pouvez utiliser qu'un seul outil de suivi pour signaler les exceptions non détectées en appelant la méthode enableExceptionReporting() sur l'outil.

Échantillonnage

Vous pouvez activer l'échantillonnage côté client pour limiter le nombre d'appels envoyés à Google Analytics. Si votre application compte un grand nombre d'utilisateurs ou envoie un grand volume de données à Google Analytics, l'activation de l'échantillonnage permet d'éviter toute interruption.

Par exemple, pour activer l'échantillonnage côté client à un taux de 50%, utilisez le paramètre suivant dans votre fichier de configuration:

<string name="ga_sampleFrequency">50.0</string>

Pour activer l'échantillonnage côté client pour un outil de suivi:

mTracker.setSampleRate(50.0d);

Désactivation au niveau de l'application

Vous pouvez activer un indicateur de désactivation au niveau de l'application qui désactivera Google Analytics dans l'ensemble de l'application. Notez que cet indicateur doit être défini à chaque démarrage de l'application et qu'il sera défini par défaut sur false.

Pour obtenir le paramètre de désactivation au niveau de l'application, utilisez:

boolean isOptedOut = GoogleAnalytics.getInstance(this).getAppOptOut();

Pour définir la désactivation au niveau de l'application, utilisez:

GoogleAnalytics.getInstance(this).setAppOptOut(true);

En règle générale, une application peut écouter une modification dans SharedPreferences, puis mettre à jour le paramètre de désactivation de Google Analytics en conséquence:

SharedPreferences userPrefs = PreferenceManager.getDefaultSharedPreferences(this);

userPrefs.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener () {

  @Override
  public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals(TRACKING_PREF_KEY)) {
      GoogleAnalytics.getInstance(getApplicationContext()).setAppOptOut(sharedPreferences.getBoolean(key, false));
    } else {
      // Any additional changed preference handling.
    }
  }
});

Supprimer les données utilisateur côté client

Si vous devez réinitialiser ou supprimer les données côté client Google Analytics pour vos utilisateurs finaux, vous pouvez supprimer le fichier d'ID client.

La suppression du fichier gaClientId forcera la génération d'un nouvel ID client, et tous les appels suivants utiliseront le nouvel ID client. Les données antérieures ne seront pas associées au nouvel ID client.

Pour supprimer le fichier gaClientId, utilisez la méthode Context.deleteFile:

context.deleteFile("gaClientId");

Rendre l'IP anonyme

L'activation de la fonctionnalité d'anonymisation des adresses IP indique à Google Analytics de rendre anonymes les informations IP envoyées par le SDK en supprimant le dernier octet de l'adresse IP avant son stockage.

Pour activer l'anonymisation de la fonctionnalité d'adresse IP, utilisez le paramètre suivant dans votre fichier de configuration:

<string name="ga_anonymizeIp">true</string>

Pour activer l'anonymisation programmatique de la fonctionnalité IP pour un outil de suivi, utilisez la méthode setAnonymizeIp :

mTracker.setAnonymizeIp(true)
.

La méthode setAnonymizeIp peut être appelée à tout moment.

Tester et déboguer

Le SDK Google Analytics v4 pour Android fournit des outils qui facilitent les tests et le débogage.

Simulation

Le SDK fournit une option dryRun qui, lorsqu'elle est définie, empêche l'envoi de données à Google Analytics. L'option dryRun doit être définie lorsque vous testez ou déboguez une mise en œuvre et que vous ne souhaitez pas que les données de test apparaissent dans vos rapports Google Analytics.

Pour définir l'indicateur de simulation:

// When dry run is set, hits will not be dispatched, but will still be logged as
// though they were dispatched.
GoogleAnalytics.getInstance(this).setDryRun(true);

Logger

Google Analytics se connectera à logcat sous la balise GAv4 à l'aide du système Android Log. Par défaut, seuls les niveaux ERROR, WARN et INFO sont activés. Pour activer le niveau DEBUG, exécutez la commande adb suivante sur votre appareil ou émulateur:

adb shell setprop log.tag.GAv4 DEBUG

Pour n'afficher que les messages Google Analytics de logcat, utilisez la commande suivante:

adb logcat -v time -s GAv4

Pour en savoir plus, consultez la documentation de référence sur le service d'enregistrement Google Analytics.