Android v3 (ancienne version) – Présentation

Ce guide du développeur explique comment implémenter Google Tag Manager dans une application mobile.

Introduction

Google Tag Manager permet aux développeurs de modifier les valeurs de configuration de leurs applications mobiles à l'aide de l'interface Google Tag Manager, sans avoir à recompiler et à renvoyer les binaires d'application aux plates-formes de téléchargement d'applications.

Cela est utile pour gérer les valeurs de configuration ou les options de votre application que vous devrez peut-être modifier à l'avenir, y compris :

  • Divers paramètres d'interface utilisateur et chaînes d'affichage
  • Tailles, emplacements ou types d'annonces diffusées dans votre application
  • Paramètres des jeux

Les valeurs de configuration peuvent également être évaluées au moment de l'exécution à l'aide de règles, ce qui permet d'utiliser des configurations dynamiques telles que :

  • Utiliser la taille de l'écran pour déterminer la taille de la bannière publicitaire
  • Utiliser la langue et la localisation pour configurer les éléments d'interface utilisateur

Google Tag Manager permet également l'implémentation dynamique de balises et de pixels de suivi dans les applications. Les développeurs peuvent transférer des événements importants dans une couche de données et décider ultérieurement des balises ou pixels de suivi à déclencher. Tag Manager est compatible avec les balises suivantes :

  • Google Analytics pour les applications mobiles
  • Balise d'appel de fonction personnalisée

Avant de commencer

Avant d'utiliser ce guide de démarrage, vous devez disposer des éléments suivants :

Si vous débutez avec Google Tag Manager, nous vous recommandons de vous renseigner sur les conteneurs, les macros et les règles (Centre d'aide) avant de poursuivre la lecture de ce guide.

Premiers pas

Cette section présente aux développeurs un workflow Tag Manager standard :

  1. Ajouter le SDK Google Tag Manager à votre projet
  2. Définir les valeurs par défaut du conteneur
  3. Ouvrir le conteneur
  4. Obtenir les valeurs de configuration du conteneur
  5. Transmettre des événements à la couche de données
  6. Prévisualiser et publier le conteneur

1. Ajouter le SDK Google Tag Manager à votre projet

Avant d'utiliser le SDK Google Tag Manager, vous devez extraire le package du SDK, ajouter la bibliothèque au chemin de compilation de votre projet et ajouter des autorisations à votre fichier AndroidManifest.xml.

Commencez par ajouter la bibliothèque Google Tag Manager au dossier /libs de votre projet.

Ensuite, mettez à jour votre fichier AndroidManifest.xml pour utiliser les autorisations suivantes :

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

2. Ajouter un fichier de conteneur par défaut à votre projet

Google Tag Manager utilise un conteneur par défaut lors de la première exécution de votre application. Le conteneur par défaut sera utilisé jusqu'à ce que l'application puisse récupérer un nouveau conteneur sur le réseau.

Pour télécharger et ajouter un binaire de conteneur par défaut à votre application, procédez comme suit :

  1. Connectez-vous à l'interface Web de Google Tag Manager.
  2. Sélectionnez la version du conteneur que vous souhaitez télécharger.
  3. Cliquez sur le bouton Télécharger pour récupérer le binaire du conteneur.
  4. Ajoutez le fichier binaire au chemin d'accès suivant : <project-root>/assets/tagmanager/.

Le nom de fichier par défaut doit être l'ID du conteneur (par exemple, GTM-1234). Une fois que vous avez téléchargé le fichier binaire, veillez à supprimer le suffixe de version du nom de fichier pour vous assurer de respecter la convention d'attribution de noms.

Bien que l'utilisation du fichier binaire soit recommandée, si votre conteneur ne contient pas de règles ni de balises, vous pouvez choisir d'utiliser un fichier JSON à la place. Le fichier doit se trouver dans un nouveau dossier /assets/tagmanager de votre projet Android et doit respecter la convention d'attribution de noms suivante : <Container_ID>.json. Par exemple, si l'ID de votre conteneur est GTM-1234, vous devez ajouter les valeurs de conteneur par défaut à /assets/tagmanager/GTM-1234.json.

3. Ouvrir un conteneur

Avant de récupérer les valeurs d'un conteneur, votre application doit l'ouvrir. L'ouverture d'un conteneur le charge à partir du disque (si disponible) ou le demande au réseau (si nécessaire).

Le moyen le plus simple d'ouvrir un conteneur sur Android consiste à utiliser ContainerOpener.openContainer(..., Notifier notifier), comme dans l'exemple suivant :

import com.google.tagmanager.Container;
import com.google.tagmanager.ContainerOpener;
import com.google.tagmanager.ContainerOpener.OpenType;
import com.google.tagmanager.TagManager;

import android.app.Activity;
import android.os.Bundle;

public class RacingGame {

  // Add your public container ID.
  private static final String CONTAINER_ID = "GTM-YYYY";

  volatile private Container mContainer;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TagManager mTagManager = TagManager.getInstance(this);

    // The container is returned to containerFuture when available.
    ContainerOpener.openContainer(
        mTagManager,                            // TagManager instance.
        CONTAINER_ID,                           // Tag Manager Container ID.
        OpenType.PREFER_NON_DEFAULT,            // Prefer not to get the default container, but stale is OK.
        null,                                   // Time to wait for saved container to load (ms). Default is 2000ms.
        new ContainerOpener.Notifier() {        // Called when container loads.
          @Override
          public void containerAvailable(Container container) {
            // Handle assignment in callback to avoid blocking main thread.
            mContainer = container;
          }
        }
    );
    // Rest of your onCreate code.
  }
}

Dans cet exemple, ContainerOpener.openContainer(..., Notifier notifier) est utilisé pour demander un conteneur enregistré à partir de l'espace de stockage local. En gérant l'attribution de mContainer dans le rappel containerAvailable, nous nous assurons que le thread principal n'est pas bloqué. Si le conteneur enregistré date de plus de 12 heures, l'appel planifie également une requête pour récupérer de manière asynchrone un nouveau conteneur sur le réseau.

Cet exemple d'implémentation représente le moyen le plus simple d'ouvrir et de récupérer des valeurs à partir d'un conteneur à l'aide de la classe utilitaire ContainerOpener. Pour découvrir des options d'implémentation plus avancées, consultez Configuration avancée.

4. Obtenir des valeurs de configuration à partir du conteneur

Une fois le conteneur ouvert, les valeurs de configuration peuvent être récupérées à l'aide des méthodes get<type>Value() :

// Retrieving a configuration value from a Tag Manager Container.

// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");

Les requêtes effectuées avec une clé inexistante renvoient une valeur par défaut appropriée au type demandé :

// Empty keys will return a default value depending on the type requested.

// Key does not exist. An empty string is returned.
string subtitle = container.getStringValue("Non-existent-key");
subtitle.equals(""); // Evaluates to true.

5. Transférer des valeurs à la couche de données

La couche de données est une carte qui permet de mettre à disposition des macros et des balises Tag Manager dans un conteneur les informations d'exécution de votre application, telles que les événements tactiles ou les vues d'écran.

Par exemple, en transmettant des informations sur les vues d'écran dans la carte DataLayer, vous pouvez configurer des balises dans l'interface Web de Tag Manager pour déclencher des pixels de conversion et des appels de suivi en réponse à ces vues d'écran, sans avoir à les coder en dur dans votre application.

Les événements sont transmis à la couche de données à l'aide de push() et de la méthode d'assistance DataLayer.mapOf() :

//
// MainActivity.java
// Pushing an openScreen event with a screen name into the data layer.
//

import com.google.tagmanager.TagManager;
import com.google.tagmanager.DataLayer;

import android.app.Activity;
import android.os.Bundle;

public MainActivity extends Activity {

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

  }

  // This screen becomes visible when Activity.onStart() is called.
  public void onStart() {
    super.onStart();

    // The container should have already been opened, otherwise events pushed to
    // the DataLayer will not fire tags in that container.
    DataLayer dataLayer = TagManager.getInstance(this).getDataLayer();
    dataLayer.push(DataLayer.mapOf("event",
                                   "openScreen",      // The event type. This value should be used consistently for similar event types.
                                   "screenName",      // Writes a key "screenName" to the dataLayer map.
                                   "Home Screen")     // Writes a value "Home Screen" for the "screenName" key.
    );
  }
  // Rest of the Activity implementation
}

Dans l'interface Web, vous pouvez désormais créer des balises (comme les balises Google Analytics) à déclencher pour chaque vue d'écran en créant la règle suivante : est égal à "openScreen". Pour transmettre le nom de l'écran à l'une de ces balises, créez une macro de couche de données qui fait référence à la clé "screenName" dans la couche de données. Vous pouvez également créer une balise (comme un pixel de conversion Google Ads) qui ne se déclenche que pour des vues d'écran spécifiques, en créant une règle où est égal à "openScreen" et est égal à "ConfirmationScreen".

6. Prévisualiser et publier un conteneur

Les valeurs des macros correspondront toujours à la version publiée actuelle. Avant de publier la dernière version d'un conteneur, vous pouvez prévisualiser votre brouillon de conteneur.

Pour prévisualiser un conteneur, générez une URL d'aperçu dans l'interface Web de Google Tag Manager en sélectionnant la version du conteneur que vous souhaitez prévisualiser, puis en sélectionnant Preview. Enregistrez cette URL d'aperçu, car vous en aurez besoin lors des étapes suivantes.

Les URL d'aperçu sont disponibles dans la fenêtre d'aperçu de l'interface Web de Tag Manager.
Figure 1 : Obtenir une URL d'aperçu à partir de l'interface Web de Tag Manager

Ensuite, ajoutez l'activité suivante au fichier AndroidManifest.xml de votre application :

<!-- Google Tag Manager Preview Activity -->
<activity
  android:name="com.google.tagmanager.PreviewActivity"
  android:label="@string/app_name"
  android:noHistory="true" >  <!-- Optional, removes the PreviewActivity from activity stack. -->
  <intent-filter>
    <data android:scheme="tagmanager.c.application_package_name" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE"/>
  </intent-filter>
</activity>
  

Ouvrez le lien sur un émulateur ou un appareil physique pour prévisualiser le conteneur brouillon dans votre application.

Lorsque vous êtes prêt à mettre les valeurs de votre brouillon de configuration à la disposition de votre application, publiez le conteneur.

Configuration avancée

Google Tag Manager pour mobile propose un certain nombre d'options de configuration avancées qui vous permettent de sélectionner des valeurs en fonction des conditions d'exécution à l'aide de règles, d'actualiser manuellement le conteneur et d'obtenir des options supplémentaires pour ouvrir les conteneurs. Les sections suivantes décrivent plusieurs des configurations avancées les plus courantes.

Options avancées pour l'ouverture des conteneurs

Le SDK Google Tag Manager fournit plusieurs méthodes pour ouvrir des conteneurs, ce qui vous permet de mieux contrôler le processus de chargement :

TagManager.openContainer()

TagManager.openContainer() est l'API de niveau le plus bas et la plus flexible pour ouvrir un conteneur. Elle renvoie immédiatement un conteneur par défaut et charge également de manière asynchrone un conteneur à partir du disque ou du réseau si aucun conteneur enregistré n'existe ou si le conteneur enregistré n'est pas récent (plus de 12 heures).

mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() {

  // Called when a refresh is about to begin for the given refresh type.
  @Override
  public void containerRefreshBegin(Container container, RefreshType refreshType) {
    // Notify UI that the Container refresh is beginning.
   }

  // Called when a successful refresh occurred for the given refresh type.
  @Override
  public void containerRefreshSuccess(Container container, RefreshType refreshType]) {
    // Notify UI that Container is ready.
  }

  // Called when a refresh failed for the given refresh type.
  @Override
  public void containerRefreshFailure(Container container,
                                      RefreshType refreshType,
                                      RefreshFailure refreshFailure) {
    // Notify UI that the Container refresh has failed.
  }

Tout au long du processus de chargement, TagManager.openContainer() émet plusieurs rappels de cycle de vie afin que votre code puisse savoir quand la requête de chargement commence, si elle échoue ou réussit et pourquoi, et si le conteneur a finalement été chargé à partir du disque ou du réseau.

À moins que votre application puisse utiliser les valeurs par défaut, vous devrez utiliser ces rappels pour savoir quand un conteneur enregistré ou réseau a été chargé. Notez que vous ne pourrez pas charger un conteneur enregistré ou réseau s'il s'agit de la première exécution de l'application et qu'il n'y a pas de connexion réseau.

TagManager.openContainer() transmet les valeurs enum suivantes en tant qu'arguments à ces rappels :

RefreshType

ValeurDescription
Container.Callback.SAVED La requête d'actualisation charge un conteneur enregistré localement.
Container.Callback.NETWORK La requête d'actualisation charge un conteneur sur le réseau.

RefreshFailure

ValeurDescription
Container.Callback.NO_SAVED_CONTAINER Aucun conteneur enregistré n'est disponible.
Container.Callback.IO_ERROR Une erreur d'E/S a empêché l'actualisation du conteneur.
Container.Callback.NO_NETWORK Aucune connexion réseau n'est disponible.
Container.Callback.NETWORK_ERROR Une erreur réseau s'est produite.
Container.Callback.SERVER_ERROR Une erreur s'est produite sur le serveur.
Container.Callback.UNKNOWN_ERROR Une erreur qui ne peut pas être classée s'est produite.

Méthodes pour ouvrir des conteneurs non définis par défaut et nouveaux

ContainerOpener encapsule TagManager.openContainer() et fournit deux méthodes pratiques pour ouvrir des conteneurs : ContainerOpener.openContainer(..., Notifier notifier) et ContainerOpener.openContainer(..., Long timeoutInMillis).

Chacune de ces méthodes utilise une énumération demandant un conteneur non défini par défaut ou un nouveau conteneur.

OpenType.PREFER_NON_DEFAULT est recommandé pour la plupart des applications et tente de renvoyer le premier conteneur non par défaut disponible dans un délai donné, à partir du disque ou du réseau, même si ce conteneur date de plus de 12 heures. S'il renvoie un conteneur enregistré obsolète, il envoie également une requête réseau asynchrone pour en obtenir un nouveau. Lorsque vous utilisez OpenType.PREFER_NON_DEFAULT, un conteneur par défaut est renvoyé si aucun autre conteneur n'est disponible ou si le délai avant expiration est dépassé.

OpenType.PREFER_FRESH tente de renvoyer un nouveau conteneur à partir du disque ou du réseau dans le délai imparti. Elle renvoie un conteneur enregistré si aucune connexion réseau n'est disponible et/ou si le délai avant expiration est dépassé.

Il n'est pas recommandé d'utiliser OpenType.PREFER_FRESH dans les cas où un temps de requête plus long peut affecter sensiblement l'expérience utilisateur, par exemple avec des indicateurs d'interface utilisateur ou des chaînes d'affichage. Vous pouvez également utiliser Container.refresh() à tout moment pour forcer une requête de conteneur réseau.

Ces deux méthodes pratiques sont non bloquantes. ContainerOpener.openContainer(..., Long timeoutInMillis) renvoie un objet ContainerOpener.ContainerFuture, dont la méthode get renvoie un Container dès qu'il est chargé (mais qui bloque jusqu'à ce moment-là). La méthode ContainerOpener.openContainer(..., Notifier notifier) n'accepte qu'un seul rappel, appelé lorsque le conteneur est disponible, ce qui peut être utilisé pour éviter de bloquer le thread principal. Les deux méthodes ont un délai avant expiration par défaut de 2000 millisecondes.

Évaluer les macros au moment de l'exécution à l'aide de règles

Les conteneurs peuvent évaluer les valeurs au moment de l'exécution à l'aide de règles. Les règles peuvent être basées sur des critères tels que la langue de l'appareil, la plate-forme ou toute autre valeur de macro. Par exemple, les règles peuvent être utilisées pour sélectionner une chaîne d'affichage localisée en fonction de la langue de l'appareil au moment de l'exécution. Cette valeur peut être configurée à l'aide de la règle suivante :

Une règle permet de sélectionner des chaînes d'affichage en fonction de la langue de l'appareil au moment de l'exécution : la langue est l'espagnol. Cette règle utilise la macro de langue prédéfinie et un code de langue ISO 639-1 à deux caractères.
Figure 1 : Ajout d'une règle pour activer une macro de collecte de valeurs uniquement pour les appareils configurés pour utiliser l'espagnol.

Vous pouvez ensuite créer des macros de collecte de valeurs pour chaque langue, et ajouter cette règle à chaque macro en insérant le code de langue approprié. Une fois ce conteneur publié, votre application pourra afficher des chaînes d'affichage localisées, en fonction de la langue de l'appareil de l'utilisateur au moment de l'exécution.

Notez que si votre conteneur par défaut nécessite des règles, vous devez utiliser un fichier de conteneur binaire comme conteneur par défaut.

En savoir plus sur la configuration des règles (Centre d'aide)

Fichiers de conteneur binaire par défaut

Les conteneurs par défaut qui nécessitent des règles doivent utiliser un fichier de conteneur binaire au lieu d'un fichier JSON comme conteneur par défaut. Les conteneurs binaires permettent de déterminer les valeurs des macros au moment de l'exécution avec les règles Google Tag Manager, contrairement aux fichiers JSON.

Les fichiers de conteneur binaires peuvent être téléchargés depuis l'interface Web de Google Tag Manager. Ils doivent être ajoutés au dossier /assets/tagmanager/ de votre projet et respecter le format suivant : /assets/tagmanager/GTM-XXXX, où le nom de fichier représente l'ID de votre conteneur.

Si un fichier JSON et un fichier de conteneur binaire sont présents, le SDK utilisera le fichier de conteneur binaire comme conteneur par défaut.

Utiliser des macros d'appel de fonction

Les macros d'appel de fonction sont des macros définies sur la valeur renvoyée d'une fonction spécifiée dans votre application. Les macros d'appel de fonction peuvent être utilisées pour intégrer des valeurs d'exécution à vos règles Google Tag Manager, par exemple pour déterminer au moment de l'exécution le prix à afficher à un utilisateur en fonction de la langue et de la devise configurées sur un appareil.

Pour configurer une macro d'appel de fonction :

  1. Définissez la macro d'appel de fonction dans l'interface Web de Google Tag Manager. Les arguments peuvent éventuellement être configurés en tant que paires clé/valeur.
  2. Enregistrez un FunctionCallMacroHandler dans votre application à l'aide de Container.registerFunctionCallMacroHandler() et du nom de fonction que vous avez configuré dans l'interface Web de Google Tag Manager, en remplaçant sa méthode getValue() :
    /**
     * Registers a function call macro handler.
     *
     * @param functionName The function name field, as defined in the Google Tag
     *     Manager web interface.
     */
    mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() {
    
      /**
       * This code will execute when any custom macro's rule(s) evaluate to true.
       * The code should check the functionName and process accordingly.
       *
       * @param functionName Corresponds to the function name field defined
       *     in the Google Tag Manager web interface.
       * @param parameters An optional map of parameters
       *     as defined in the Google Tag Manager web interface.
       */
      @Override
      public Object getValue(String functionName, Map<String, Object> parameters)) {
    
        if (functionName.equals("myConfiguredFunctionName")) {
          // Process and return the calculated value of this macro accordingly.
          return macro_value
        }
        return null;
      }
    });

Utiliser des balises d'appel de fonction

Les balises d'appel de fonction permettent d'exécuter des fonctions préenregistrées chaque fois qu'un événement est transmis à la couche de données et que les règles de balise sont évaluées sur true.

Pour configurer une balise d'appel de fonction :

  1. Définissez la balise d'appel de fonction dans l'interface Web de Google Tag Manager. Les arguments peuvent éventuellement être configurés en tant que paires clé/valeur.
  2. Enregistrez un gestionnaire de balises d'appel de fonction dans votre application à l'aide de Container.registerFunctionCallTagHandler() :
    /**
     * Register a function call tag handler.
     *
     * @param functionName The function name, which corresponds to the function name field
     *     Google Tag Manager web interface.
     */
    mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() {
    
      /**
       * This method will be called when any custom tag's rule(s) evaluates to true.
       * The code should check the functionName and process accordingly.
       *
       * @param functionName The functionName passed to the functionCallTagHandler.
       * @param parameters An optional map of parameters as defined in the Google
       *     Tag Manager web interface.
       */
      @Override
      public void execute(String functionName, Map<String, Object> parameters) {
        if (functionName.equals("myConfiguredFunctionName")) {
          // Process accordingly.
        }
      }
    });

Définir une période d'actualisation personnalisée

Le SDK Google Tag Manager tente de récupérer un nouveau conteneur si l'âge du conteneur actuel dépasse 12 heures. Pour définir une période d'actualisation personnalisée du conteneur, utilisez Timer, comme dans l'exemple suivant :

timer.scheduleTask(new TimerTask() {
  @Override
  public void run() {
    mContainer.refresh();
  }
}, delay, <new_period_in milliseconds>);

Déboguer avec Logger

Par défaut, le SDK Google Tag Manager affiche les erreurs et les avertissements dans les journaux. L'activation d'une journalisation plus détaillée peut être utile pour le débogage. Pour ce faire, vous pouvez implémenter votre propre Logger avec TagManager.setLogger, comme dans cet exemple :

TagManager tagManager = TagManager.getInstance(this);
tagManager.setLogger(new Logger() {

  final String TAG = "myGtmLogger";

  // Log output with verbosity level of DEBUG.
  @Override
  public void d(String arg0) {
    Log.d(TAG, arg0);
  }

  // Log exceptions when provided.
  @Override
  public void d(String arg0, Throwable arg1) {
    Log.d(TAG, arg0);
    arg1.printStackTrace();
  }

  // Rest of the unimplemented Logger methods.

});

Vous pouvez également définir le niveau de journalisation de l'enregistreur existant à l'aide de TagManager.getLogger().setLogLevel(LogLevel), comme dans cet exemple :

// Change the LogLevel to INFO to enable logging at INFO and higher levels.
TagManager tagManager = TagManager.getInstance(this);
tagManager.getLogger().setLogLevel(LogLevel.INFO);