Android v4 – Premiers pas

Introduction

Google Tag Manager permet aux développeurs de modifier les valeurs de configuration de leur application mobile via son interface sans avoir à recréer et à renvoyer les fichiers binaires de l'application sur les places de marché d'applications.

Cette fonctionnalité est utile pour gérer les valeurs ou les indicateurs de configuration 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
  • Divers paramètres de jeu

Les valeurs de configuration peuvent également être évaluées au moment de l'exécution à l'aide de règles, permettant ainsi 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 l'emplacement pour configurer des éléments d'interface utilisateur

Google Tag Manager permet également d'implémenter de façon dynamique des balises et des pixels de suivi dans les applications. Les développeurs peuvent transmettre des événements importants dans une couche de données et décider ultérieurement quels pixels ou balises de suivi doivent être déclenchés.

Avant de commencer

Avant de commencer ce guide de démarrage, procédez comme suit:

Une fois ces étapes terminées, la suite de ce guide vous explique comment configurer et utiliser Google Tag Manager dans votre application Android.

Getting Started

Après avoir suivi ce guide de démarrage, vous saurez:

Ce guide utilise des extraits de code de l'exemple d'application Cute Animals fourni avec le SDK des services Google Play. La source complète de ce projet est disponible dans <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. Ajouter Google Tag Manager à votre projet

Pour ajouter Google Tag Manager à votre projet:

  1. Configurez le SDK des services Google Play.
  2. Si vous utilisez un IDE autre qu' Android Studio, ajoutez les autorisations suivantes au fichier AndroidManifest.xml : 
    <!-- For TagManager SDK -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  3. Pour permettre à InstallReferrerReceiver d'appeler le récepteur Google Analytics afin de définir les données de la campagne, ajoutez les éléments suivants au fichier AndroidManifest.xml : 
    <!-- Used for install referrer tracking-->
<service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
<receiver
  android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
  android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

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 cesse d'être utilisé dès que l'application peut 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 du conteneur téléchargé à votre projet en tant que ressource brute.
    1. Si le sous-dossier raw sous <project-root>/res/ n'existe pas, créez-le.
    2. Renommez le fichier binaire du conteneur si nécessaire. Il ne se compose que de lettres minuscules, de chiffres et de traits de soulignement.
    3. Copiez le fichier binaire du conteneur dans le dossier <project-root>/res/raw.

Bien qu'il soit recommandé d'utiliser le fichier binaire, si votre conteneur ne contient ni règles ni balises, vous pouvez choisir d'utiliser un simple fichier JSON à la place.

3. Initialiser Google Tag Manager

Pour initialiser Google Tag Manager dans votre application:

  1. Obtenez le singleton TagManager : 
    TagManager tagManager = TagManager.getInstance(this);
  2. Utilisez le singleton TagManager pour envoyer une requête de chargement d'un conteneur, en spécifiant un ID de conteneur Google Tag Manager ainsi que votre fichier de conteneur par défaut. L'ID du conteneur doit être en majuscules et correspondre exactement à celui qui figure dans l'interface Web de Google Tag Manager. L'appel à loadContainerPreferNonDefault() est non bloquant et renvoie un PendingResult :
    PendingResult<ContainerHolder> pending =
        tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
        R.raw.defaultcontainer_binary);
  3. Utilisez un ResultCallback pour renvoyer le ContainerHolder une fois le chargement terminé ou dépassé : 
    // The onResult method will be called as soon as one of the following happens:
//     1. a saved container is loaded
//     2. if there is no saved container, a network container is loaded
//     3. the 2-second timeout occurs
pending.setResultCallback(new ResultCallback<ContainerHolder>() {
    @Override
    public void onResult(ContainerHolder containerHolder) {
        ContainerHolderSingleton.setContainerHolder(containerHolder);
        Container container = containerHolder.getContainer();
        if (!containerHolder.getStatus().isSuccess()) {
            Log.e("CuteAnimals", "failure loading container");
            displayErrorToUser(R.string.load_error);
            return;
        }
        ContainerLoadedCallback.registerCallbacksForContainer(container);
        containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
        startMainActivity();
    }
}, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);

    Créer un singleton ContainerHolder

    Vous ne devez gérer qu'une seule instance de ContainerHolder à chaque exécution de votre application. C'est pourquoi l'exemple ci-dessus utilise une classe utilitaire ContainerHolderSingleton pour gérer l'accès à l'instance ContainerHolder. Voici à quoi ressemble cette classe ContainerHolderSingleton:

    package com.google.android.tagmanager.examples.cuteanimals;

import com.google.android.gms.tagmanager.ContainerHolder;

/**
 * Singleton to hold the GTM Container (since it should be only created once
 * per run of the app).
 */
public class ContainerHolderSingleton {
    private static ContainerHolder containerHolder;

    /**
     * Utility class; don't instantiate.
     */
    private ContainerHolderSingleton() {
    }

    public static ContainerHolder getContainerHolder() {
        return containerHolder;
    }

    public static void setContainerHolder(ContainerHolder c) {
        containerHolder = c;
    }
}

4. Obtenir des valeurs de configuration à partir du conteneur

Une fois le conteneur chargé, vous pouvez récupérer les valeurs de configuration à l'aide de l'une des méthodes Container.get<type>(). Les valeurs de configuration sont définies à l'aide des variables de collection de valeurs de Google Tag Manager. Par exemple, la méthode suivante récupère la dernière couleur que nous avons décidé d'utiliser pour un élément d'interface utilisateur et la renvoie sous forme de nombre entier:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

Ce code effectue deux opérations pour récupérer le nom de la couleur à partir du conteneur:

  1. Récupère les Container à partir de ContainerHolder à l'aide de ContainerHolder.getContainer().
  2. Récupère la valeur de la couleur à l'aide de Container.getString(key), où vous avez défini la clé et la valeur dans l'interface Web de Google Tag Manager.

5. Transmettre des événements et des valeurs à la couche de données

Google Tag Manager fournit également un dataLayer, dans lequel vous pouvez transmettre des informations sur votre application. Celles-ci pourront être lues dans d'autres parties de votre application ou utilisées pour déclencher les balises que vous avez configurées dans l'interface Web de Google Tag Manager.

Transmettre des valeurs à la couche de données

dataLayer fournit une couche de persistance que vous pouvez utiliser pour stocker des paires clé-valeur que vous pouvez utiliser dans d'autres parties de votre application ou en tant qu'entrées dans des balises Google Tag Manager.

Pour transmettre une valeur à dataLayer, procédez comme suit:

  1. Obtenez le singleton DataLayer : 
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Transférez l'événement à l'aide de DataLayer.push() : 
    // Put the image_name into the data layer for future use.
TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);

Pour obtenir une valeur à partir de dataLayer, utilisez DataLayer.get(key).

Transmettre des événements à la couche de données

Le transfert d'événements vers dataLayer vous permet de séparer le code de votre application des balises que vous souhaitez peut-être déclencher en réponse à ces événements.

Par exemple, au lieu de coder en dur les appels de suivi des vues d'écran Google Analytics dans votre application, vous pouvez transmettre des événements d'écran à dataLayer et définir vos balises de suivi via l'interface Web de Google Tag Manager. Vous avez ainsi la possibilité de modifier cette balise ou d'ajouter des balises supplémentaires qui répondent aux événements d'écran, sans mettre à jour le code de votre application.

Pour transmettre un événement à dataLayer, procédez comme suit:

  1. Obtenez le singleton DataLayer : 
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Transférez l'événement à l'aide de DataLayer.pushEvent() : 
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

    DataLayer.mapOf() est une méthode utilitaire qui vous permet de générer facilement un mappage de paires clé/valeur qui mettra à jour l'élément dataLayer lors du transfert de l'événement.

6. Prévisualisation, débogage et publication

Avant de publier une version de votre conteneur, vous pouvez le prévisualiser pour vous assurer qu'il fonctionne comme prévu. Google Tag Manager vous permet de prévisualiser les versions de votre conteneur en générant des liens et des codes QR dans l'interface Web, puis en les utilisant pour ouvrir votre application. Vous pouvez également activer un mode de journalisation détaillée pour déboguer tout comportement inattendu.

Prévisualisation…

Pour prévisualiser une version de votre conteneur, procédez comme suit:

  1. Ajout de l'aperçu Activity à votre fichier AndroidManifest : 
    <!--  Add preview activity. -->
<activity
    android:name="com.google.android.gms.tagmanager.PreviewActivity"
    android:label="@string/app_name"
    android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
    <intent-filter>
      <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>
</activity>

    Veillez à modifier cette ligne pour inclure le nom du package de votre application:

    <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
  2. Générez un lien d'aperçu dans l'interface Web de Google Tag Manager.
    1. Connectez-vous à Google Tag Manager.
    2. Sélectionnez la version du conteneur à prévisualiser
    3. Cliquez sur le bouton Prévisualiser
    4. Saisissez le nom du package de votre application, puis cliquez sur Générer le lien de début d'aperçu.
  3. Utiliser le lien ou le code QR généré pour lancer votre application
  4. Vous pouvez quitter le mode Aperçu en suivant un lien généré par l'option Générer un lien d'aperçu final dans l'interface Web.

Débogage

Si vous devez résoudre les problèmes liés à l'implémentation de vos conteneurs, activez la journalisation détaillée en appelant TagManager.setVerboseLoggingEnabled(true) : 

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

Publication…

Après avoir prévisualisé votre conteneur et vérifié qu'il fonctionne comme prévu, vous pouvez le publier. Les valeurs de configuration de vos conteneurs, vos balises et vos événements seront mis en ligne pour les utilisateurs lors de la prochaine actualisation de leurs conteneurs. En savoir plus sur l'actualisation des conteneurs

Configuration avancée

Les sections suivantes décrivent les options de configuration avancées que vous souhaitez utiliser pour personnaliser davantage votre implémentation de Google Tag Manager.

Actualiser le conteneur

Par défaut, votre conteneur peut être actualisé toutes les 12 heures. Pour actualiser manuellement le conteneur, utilisez ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Il s'agit d'un appel asynchrone qui ne sera pas renvoyé immédiatement. Pour réduire le trafic réseau, refresh() ne peut être appelé qu'une fois toutes les 15 minutes. Sinon, il s'agit d'une opération no-op.