Android v4 (ancienne version) – Premiers pas

Introduction

Google Tag Manager permet aux développeurs de modifier les valeurs de configuration de leur application mobile à l'aide de l'interface Google Tag Manager, sans avoir à recompiler et à renvoyer les binaires de l'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
  • 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, 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.

Avant de commencer

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

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

Premiers pas

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

Ce guide utilise des extraits de code de l'exemple d'application Cute Animals inclus dans 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. Configurer 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 campagne, ajoutez ce qui suit 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 ne sera plus utilisé dès que l'application pourra 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 :

  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. Initialisation de 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 de conteneur doit être en majuscules et correspondre exactement à l'ID de conteneur 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 le délai d'expiration écoulé :
    // 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 conserver qu'une seule instance de ContainerHolder par exécution de votre application. C'est pourquoi l'exemple ci-dessus utilise une classe d'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 collecte 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 d'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 Container à partir de ContainerHolder à l'aide de ContainerHolder.getContainer().
  2. Récupère la valeur de 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 à dataLayer

Google Tag Manager fournit également une dataLayer, dans laquelle vous pouvez transférer des informations sur votre application qui peuvent être lues dans d'autres parties de votre application ou utilisées pour déclencher des balises que vous avez configurées dans l'interface Web de Google Tag Manager.

Transférer des valeurs vers la couche de données

dataLayer fournit une couche de persistance que vous pouvez utiliser pour stocker des paires clé-valeur que vous souhaitez peut-être utiliser dans d'autres parties de votre application ou comme entrées pour les balises Google Tag Manager.

Pour transférer une valeur vers dataLayer, suivez ce modèle :

  1. Obtenez le singleton DataLayer :
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Envoyez 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

En transmettant des événements à dataLayer, vous pouvez séparer le code de votre application des balises que vous souhaitez 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 transférer les événements d'écran vers dataLayer et définir vos balises de suivi via l'interface Web de Google Tag Manager. Vous pouvez ainsi modifier cette balise ou ajouter des balises supplémentaires qui répondent aux événements d'écran, sans mettre à jour le code de votre application.

Pour transférer un événement vers la dataLayer, suivez ce modèle :

  1. Obtenez le singleton DataLayer :
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. Envoyez 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 une carte de paires clé-valeur qui mettra à jour la dataLayer en même temps que l'événement est transmis.

6. Prévisualiser, déboguer et publier

Avant de publier une version de votre conteneur, vous devez la prévisualiser pour vous assurer qu'elle 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 QR codes 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. Ajoutez cet 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 de l'aperçu.
  3. Utilisez le lien ou le QR code 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 de fin d'aperçu dans l'interface Web.

Débogage

Si vous devez résoudre les problèmes liés à l'implémentation de votre conteneur, 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, les balises et les événements de votre conteneur seront disponibles 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 pouvez utiliser pour personnaliser davantage votre implémentation de Google Tag Manager.

Actualisation du 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 renvoie pas de résultat 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 sans effet.