Configuration avancée – SDK Android

Important: Ce document décrit une ancienne version du SDK. Les nouveaux utilisateurs doivent utiliser la dernière version du SDK.

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

Présentation

Le SDK Google Analytics 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 singleton GoogleAnalytics en fournissant un Context et un ID de propriété Google Analytics:

// Initialize a tracker using a Google Analytics property ID.
GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y")

Vous pouvez désormais utiliser cet outil de suivi pour définir et envoyer des données à Google Analytics.

Définition et envoi des données

Les données sont envoyées à Google Analytics en définissant des mappages de paires paramètre/valeur sur l'outil de suivi et en les envoyant via les méthodes set et send:

/*
 * Send a screen view to Google Analytics by setting a map of parameter
 * values on the tracker and calling send.
 */
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");

HashMap<String, String> hitParameters = new HashMap<String, String>();
hitParameters.put(Fields.HIT_TYPE, "appview");
hitParameters.put(Fields.SCREEN_NAME, "Home Screen");

tracker.send(hitParameters);

La classe MapBuilder simplifie le processus de création des appels et est recommandée pour la plupart des cas d'utilisation. Ici, nous pouvons envoyer la même vue d'écran avec moins de lignes de code:

// Sending the same screen view hit using MapBuilder.createAppView()
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "Home Screen")
  .build()
);

Syntaxe de l'esperluette du protocole de mesure

Vous pouvez également définir les valeurs sur un seul appel, en définissant la valeur sur un Builder ou sur tous les appels suivants, en la définissant sur l'objet de suivi lui-même, à l'aide de la syntaxe du protocole de mesure:

// Setting the content description field on a single hit using ampersand syntax.
tracker.send(MapBuilder
  .createAppView()
  .set(Fields.SCREEN_NAME, "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:

// Set screen name on the tracker to be sent with all hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// Send a screen view for "Home Screen"
tracker.send(MapBuilder
    .createAppView()
    .build()
);

// This event will also be sent with &cd=Home%20Screen.
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

// Clear the screen name field when we're done.
tracker.set(Fields.SCREEN_NAME, 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

Plusieurs outils de suivi peuvent être utilisés dans une même implémentation, ce qui peut être utile pour envoyer des données à plusieurs propriétés:

Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");

// Trackers may be named. By default, name is set to the property ID.
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("altTracker", "UA-XXXX-2";

t1.set(Fields.SCREEN_NAME, "Home Screen");
t2.set(Fields.SCREEN_NAME, getClass().toString());

// Send screen view to UA-XXXX-1.
t1.send(MapBuilder
   .createAppView()
   .build()
);

// Send screen view to UA-XXXX-2.
t2.send(MapBuilder
   .createAppView()
   .build()
);

Les fonctionnalités de mesure automatisée, comme l'écran automatique et la mesure des exceptions non détectées, n'utilisent qu'un seul outil de suivi pour envoyer des données à Google Analytics. Si vous utilisez ces fonctionnalités et que vous souhaitez envoyer des données à l'aide d'autres traceurs, vous devez le faire manuellement.

Utilisation de l’outil de suivi par défaut

Google Analytics dispose d'un outil de suivi par défaut. Le premier outil de suivi initialisé devient l'outil de suivi par défaut, mais peut être ignoré:

// Tracker t1 becomes the default tracker because it is initialized first.
Tracker t1 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-1");
Tracker t2 = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-2");


// Returns tracker t1.
Tracker defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-1.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, "Home Screen")
    .build()
);

// Override the default tracker.
GoogleAnalytics.getInstance(this).setDefaultTracker(t2);

// Now this call returns tracker t2.
defaultTracker = GoogleAnalytics.getInstance(this).getDefaultTracker();

// Hit sent to UA-XXXX-2.
defaultTracker.send(MapBuilder
    .createAppView()
    .set(Fields.SCREEN_NAME, getClass().toString())
    .build()
);

É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% via EasyTracker et XML, utilisez le paramètre suivant dans votre fichier analytics.xml:

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

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

mTracker.set(Fields.SAMPLE_RATE, 50.0d);

Pour éviter les incohérences dans les rapports,chacune des vues d'application (profils) doit contenir des données collectées au même taux d'échantillonnage. Si différentes versions de votre application utilisent des taux d'échantillonnage différents, vous devez configurer des filtres de vue (profil) à l'aide de la dimension "Version de l'application" pour séparer les données de chaque version.

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 NO.

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

Tester et déboguer

Le SDK Google Analytics 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

L'interface Logger permet de gérer les messages utiles du SDK à ces niveaux de verbosité : error, warning, info et verbose.

Le SDK initialise une implémentation Logger standard, qui par défaut ne consigne que les messages d'avertissement ou d'erreur dans la console. Ces messages seront disponibles dans Logcat. Pour définir la verbosité de Logger:

// Set the log level to verbose.
GoogleAnalytics.getInstance(this).getLogger()
    .setLogLevel(LogLevel.VERBOSE);

Vous pouvez également utiliser les implémentations personnalisées de Logger:

// Provide a custom logger.
GoogleAnalytics.getInstance(this).setLogger(new CustomLogger ());

Exemple complet

L'exemple ci-dessous présente le code nécessaire pour initialiser une implémentation Google Analytics et envoyer un seul visionnage de l'écran.

package com.example.app;

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

import android.app.Application;
import android.content.SharedPreferences;
import android.preference.PreferenceManager;


/*
 * An advanced Google Analytics implementation may be initialized
 * in a subclass of Application. Note that this example assumes data
 * only needs to be sent to a single Google Analytics property ID.
 */
public class MyApp extends Application {

  private static GoogleAnalytics mGa;
  private static Tracker mTracker;

  /*
   * Google Analytics configuration values.
   */
  // Placeholder property ID.
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  // Dispatch period in seconds.
  private static final int GA_DISPATCH_PERIOD = 30;

  // Prevent hits from being sent to reports, i.e. during testing.
  private static final boolean GA_IS_DRY_RUN = false;

  // GA Logger verbosity.
  private static final LogLevel GA_LOG_VERBOSITY = LogLevel.INFO;

  // Key used to store a user's tracking preferences in SharedPreferences.
  private static final String TRACKING_PREF_KEY = "trackingPreference";


  /*
   * Method to handle basic Google Analytics initialization. This call will not
   * block as all Google Analytics work occurs off the main thread.
   */
  private void initializeGa() {
    mGa = GoogleAnalytics.getInstance(this);
    mTracker = mGa.getTracker(GA_PROPERTY_ID);

    // Set dispatch period.
    GAServiceManager.getInstance().setLocalDispatchPeriod(GA_DISPATCH_PERIOD);

    // Set dryRun flag.
    mGa.setDryRun(GA_IS_DRY_RUN);

    // Set Logger verbosity.
    mGa.getLogger().setLogLevel(GA_LOG_VERBOSITY);

    // Set the opt out flag when user updates a tracking preference.
    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));
        }
      }
    });
  }

  @Override
  public void onCreate() {
    super.onCreate();
    initializeGa();
  }

  /*
   * Returns the Google Analytics tracker.
   */
  public static Tracker getGaTracker() {
    return mTracker;
  }

  /*
   * Returns the Google Analytics instance.
   */
  public static GoogleAnalytics getGaInstance() {
    return mGa;
  }
}

Ensuite, un visionnage de l'écran est mesuré lorsque le premier écran s'affiche:

package com.example.app

import android.app.Activity

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private static final String SCREEN_LABEL = "Home Screen";

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Fields set on a tracker persist for all hits, until they are
    // overridden or cleared by assignment to null.
    MyApp.getGaTracker().set(Fields.SCREEN_NAME, SCREEN_LABEL);
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    MyApp.getGaTracker().send(MapBuilder
        .createAppView.build());
  }
}