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

Définition et envoi des données

Les données sont envoyées à Google Analytics à l'aide de compilateurs pour 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 traceur:

// 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 de l'esperluette du protocole de mesure

Vous pouvez utiliser la syntaxe esperluette du protocole de mesure pour définir des valeurs sur un seul appel avec un élément HitBuilders.ScreenViewBuilder. Pour définir des valeurs sur tous les appels suivants, utilisez l'objet Tracker 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 disponibles, consultez la documentation de référence sur les paramètres du protocole de mesure.

Application de valeurs à plusieurs appels

Toutes les valeurs définies directement sur l'outil de suivi sont 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 judicieux de définir un nom d'écran sur un outil de suivi, car la même valeur peut être appliquée aux vues d'écran et aux appels avec événement suivants. Toutefois, nous vous déconseillons de définir un champ tel que le type d'appel sur l'outil de suivi, car il est susceptible de changer à chaque appel.

Utiliser 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 avoir plusieurs outils de suivi, vous ne pouvez en utiliser qu'un seul pour signaler les exceptions non détectées en appelant la méthode enableExceptionReporting() sur l'outil de suivi.

É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 vous permettra de générer des rapports sans 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 de manière programmatique 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 pour l'ensemble de l'application. Notez que cet indicateur doit être défini chaque fois que l'application démarre et qu'il est défini par défaut sur false.

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

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

Pour désactiver la fonctionnalité au niveau d'une application, utilisez:

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

Dans une implémentation typique, une application peut écouter une modification de SharedPreferences et 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 Google Analytics côté client de vos utilisateurs finaux, vous pouvez supprimer le fichier d'ID client.

La suppression du fichier gaClientId force la génération d'un nouvel identifiant client. Tous les appels ultérieurs utiliseront ce nouvel identifiant. 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

Activer la fonctionnalité d'anonymisation de l'adresse IP indique à Google Analytics d'anonymiser les informations IP envoyées par le SDK en supprimant le dernier octet de l'adresse IP avant son stockage.

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

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

Pour activer l'anonymisation de la fonctionnalité d'adresse IP de manière automatisée pour un traceur, 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.

Test à blanc

Le SDK fournit un indicateur dryRun qui, lorsqu'il est défini, empêche l'envoi de données à Google Analytics. L'indicateur dryRun doit être défini chaque fois que vous testez ou déboguez une implémentation et que vous ne souhaitez pas que des données de test apparaissent dans vos rapports Google Analytics.

Pour définir l'indicateur de dry run:

// 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 connecte à 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 votre émulateur:

adb shell setprop log.tag.GAv4 DEBUG

Pour afficher uniquement 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 les journaux Google Analytics.