Cette page a été traduite par l'API Cloud Translation.

Créer un tag de serveur

Dans Introduction au taggage côté serveur, vous avez découvert le taggage côté serveur dans Tag Manager. Vous avez appris ce que sont les clients et ce qu'ils font: ils reçoivent des données d'événement des appareils de vos utilisateurs et les adaptent pour qu'elles soient utilisées par le reste du conteneur. Cet article explique comment traiter ces données dans les tags côté serveur.

Dans un conteneur serveur, les tags reçoivent les données d'événement entrantes de vos clients, les transforment et les renvoient pour collecte et analyse. Les balises peuvent envoyer les données où vous le souhaitez. Tant que la destination accepte les requêtes HTTP, elle peut également accepter les données d'un conteneur serveur.

Les conteneurs serveur comportent trois balises intégrées qui sont prêtes à l'emploi sans configuration personnalisée:

Google Analytics 4
Google Analytics : Universal Analytics
Requête HTTP

Si vous souhaitez envoyer des données ailleurs que dans Google Analytics ou si vous avez besoin de plus de fonctionnalités que celles fournies par la balise de requête HTTP, vous devez utiliser une autre balise. Vous trouverez d'autres balises dans la galerie de modèles de la communauté, ou vous pouvez créer les vôtres. Ce tutoriel vous explique les bases de l'écriture de vos propres balises pour un conteneur serveur.

Objectifs

Découvrez quelles API utiliser pour lire les données d'événement, envoyer des requêtes HTTP et définir des cookies dans le navigateur.
Découvrez les bonnes pratiques à suivre pour définir les options de configuration de votre balise.
Découvrez la différence entre les données spécifiées par l'utilisateur et les données collectées automatiquement, et pourquoi cette distinction est importante.
Découvrez le rôle d'une balise dans un conteneur serveur. comprendre ce qu'une balise doit et ne doit pas faire.
Découvrez dans quels cas peut être envoyé un modèle de balise à la galerie de modèles de la communauté.

Prérequis

Un conteneur serveur déployé
Vous connaissez Tag Manager, les conteneurs de serveur et leurs concepts de base tels que les clients, les balises, les déclencheurs et les variables.
Vous connaissez les principes de base de l'écriture de modèles pour les balises et les variables.

La balise Baz Analytics

Dans ce tutoriel, vous allez créer une balise qui envoie des données de mesure à un service appelé Baz Analytics.

Baz Analytics est un service d'analyse simple et hypothétique qui ingère des données via des requêtes HTTP GET envoyées à https://example.com/baz_analytics. Elle comporte les paramètres suivants:

Paramètres	Exemple	Description
id	BA-1234	ID de votre compte Baz Analytics.
en	click	Nom de l'événement
l	`https://www.google.com/search?q=sgtm`	URL de la page où l'événement s'est produit.
u	2384294892	L'ID de l'utilisateur effectuant l'action. Utilisé pour lier plusieurs actions à un seul utilisateur.

Configuration de la balise

Commencez par créer le modèle de tag. Accédez à la section Modèles de votre conteneur, puis cliquez sur Nouveau dans la section Modèles de balise. Ajoutez un nom et une description à votre tag.

Accédez ensuite à la section Fields (Champs) de l'éditeur de modèles pour ajouter les différentes options de configuration pour votre balise. La question suivante va évidente: de quelles options avez-vous besoin ? Vous pouvez choisir de créer le tag de trois manières différentes:

Configuration totale: ajoutez un champ de configuration pour chaque paramètre. Oblige l'utilisateur à tout définir explicitement.
Aucune configuration: vous ne disposez d'aucune option pour configurer la balise. Toutes les données sont directement issues de l'événement.
Certaines configurations: contiennent des champs pour certains paramètres, mais pas pour d'autres.

La création de champs pour chaque paramètre offre une grande flexibilité et permet à l'utilisateur de contrôler totalement la configuration de sa balise. Dans la pratique, cependant, cela entraîne généralement un grand nombre de tâches en double. Plus précisément, des éléments tels que le paramètre l Baz Analytics, qui contient l'URL de la page, sont sans ambiguïté et universels. Il est préférable de laisser l'ordinateur saisir la même donnée identique à chaque configuration de la balise.

La solution consiste peut-être à utiliser une balise qui ne collecte que les données d'un événement. Il s'agit de la balise la plus simple que l'utilisateur puisse configurer, car elle n'a rien à faire. Elle est, quant à elle, l'option la plus restrictive et la plus fragile. Les utilisateurs ne peuvent pas modifier le comportement de la balise, même s'ils en ont besoin. Par exemple, il peut appeler un événement purchase sur son site Web et dans Google Analytics, mais Baz Analytics l'appelle buy. Il est également possible que les hypothèses formulées par la balise sur la structure des données d'événements entrantes ne correspondent pas à la réalité. Dans les deux cas, l'utilisateur est bloqué.

Comme pour beaucoup de choses, la réponse se situe quelque part entre les deux extrêmes. Certaines données doivent toujours être extraites de l'événement. Les autres données doivent être configurées par l'utilisateur. Comment déterminez-vous laquelle ? Pour répondre à cette question, nous devons examiner de plus près les données arrivant dans le conteneur.

D’où proviennent les données ?

Les données arrivant dans un conteneur de serveur à partir de la balise Google Analytics 4 peuvent être grossièrement divisées en deux catégories: les données spécifiées par l'utilisateur et les données collectées automatiquement.

Les données spécifiées par l'utilisateur correspondent à tout ce qu'il saisit dans une commande event gtag.js. Par exemple, une commande comme celle-ci:

gtag('event', 'search', {
  search_term: 'beets',
});

Cela entraînera les paramètres suivants dans le conteneur serveur:

{
  event_name: 'search',
  search_term: 'beets',
}

C'est assez simple, mais du point de vue de la balise, il est très difficile de travailler dessus. Comme ces données sont saisies par l'utilisateur, il peut s'agir de n'importe quoi. Peut-être que, comme ci-dessus, l'utilisateur n'envoie que des événements et paramètres recommandés, ce qui n'est pas obligatoire. À l'exception importante de l'emplacement (mais pas de la valeur) du paramètre event_name, il n'existe aucune garantie quant à la forme ou la structure des données de l'utilisateur.

Heureusement, les données saisies par l'utilisateur ne sont pas la seule chose que le conteneur recevra. Il recevra également un ensemble de données collectées automatiquement par la balise Google Analytics 4 dans le navigateur. Par exemple:

ip_override
language
page_location
page_referrer
page_title
screen_resolution
user_agent

De plus, si la requête du serveur provient d'un navigateur Web, il est possible que des données de cookies de navigateur soient disponibles via l'API getCookieValue.

Ensemble, ils constituent les données collectées automatiquement dont nous avons parlé ci-dessus. En général, il s'agit de données universelles et sémantiquement sans ambiguïté. Lorsqu'une requête provient d'une balise GA4 dans le navigateur, ces données sont toujours disponibles et ont toujours le même format. Pour en savoir plus sur ces paramètres, consultez la documentation de référence sur les événements.

Cette classification constitue un outil utile pour déterminer les données à configurer par l'utilisateur et celles à spécifier dans la balise. Les données collectées automatiquement peuvent être lues directement depuis l'événement en toute sécurité. Tous les autres éléments doivent être configurés par l'utilisateur.

En gardant cela à l'esprit, examinez à nouveau les paramètres de la balise Baz Analytics.

ID de mesure, id:étant donné qu'il n'est pas collecté automatiquement, il s'agit d'un exemple clair de valeur que l'utilisateur doit saisir lors de la configuration de la balise.
Nom de l'événement, en:comme indiqué ci-dessus, le nom de l'événement peut toujours être extrait directement du paramètre event_name. Toutefois, comme sa valeur est définie par l'utilisateur, nous vous recommandons de permettre de remplacer le nom si nécessaire.
URL de la page l:cette valeur peut être issue du paramètre page_location, qui est automatiquement collecté par la balise de navigateur GA4 Google Analytics à chaque événement. Par conséquent, vous ne devez pas demander à l'utilisateur de saisir une valeur manuellement.
ID utilisateur u:dans la balise du serveur Baz Analytics, le paramètre u n'est ni spécifié par l'utilisateur, ni collecté automatiquement par la balise sur la page. Elles sont plutôt stockées dans un cookie de navigateur afin d'identifier les utilisateurs lors de leurs différentes visites sur le site Web. Comme vous le verrez dans l'implémentation ci-dessous, c'est la balise de serveur Baz Analytics qui utilise l'API setCookie pour définir le cookie. Cela signifie que la balise Baz Analytics est la seule chose qui sait où et comment le cookie est stocké. Comme pour l, le paramètre u devrait être collecté automatiquement.

Une fois la configuration de la balise terminée, la balise doit se présenter comme suit:

Instantané de la configuration de la balise pour la balise Baz Analytics

Implémentation des balises

Maintenant que la configuration de la balise est au carré, vous êtes prêt à implémenter son comportement dans le code JavaScript de bac à sable.

La balise doit effectuer quatre opérations:

Récupérez le nom de l'événement à partir de la configuration de la balise.
Obtenez l'URL de la page à partir de la propriété page_location de l'événement.
Calculez un ID utilisateur. La balise recherchera l'ID utilisateur dans un cookie appelé _bauid. Si ce cookie n'est pas présent, la balise calcule une nouvelle valeur et la stocke pour les requêtes ultérieures.
Créez une URL et envoyez une requête au serveur de collecte Baz Analytics.

Il est également utile de prendre le temps de réfléchir à la façon dont la balise s'intègre dans le conteneur dans son ensemble. Les différents composants de conteneur jouent des rôles différents. Par conséquent, il y a aussi des choses que la balise ne fait pas ou ne doit pas faire. Votre balise:

Ne doit pas examiner l'événement pour déterminer s'il doit être exécuté. C'est à cela que sert un déclencheur.
Ne doit pas exécuter le conteneur avec l'API runContainer. C'est le travail du client.
À l'exception importante des cookies, il ne doit pas essayer d'interagir directement avec la requête ou la réponse. C'est aussi le travail du client.

La rédaction d'un modèle de balise qui effectue l'une de ces opérations peut prêter à confusion pour les utilisateurs de votre balise. Par exemple, un tag qui envoie une réponse à la requête entrante empêcherait le client de faire de même. Cela irait à l'encontre des utilisateurs quant au comportement supposé du conteneur.

En gardant tout cela à l'esprit, vous trouverez ci-dessous une implémentation annotée du tag dans un code JS en bac à sable.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

La balise est alors implémentée. Avant de pouvoir utiliser le tag, vous devez définir correctement ses autorisations d'API. Accédez à l'onglet Autorisations de l'éditeur de modèle et spécifiez les autorisations suivantes:

Lit les valeurs des cookies: _bauid
Lecture des données d'événement: event_name et page_location
Envoie des requêtes HTTP: https://www.example.com/*
Définit un cookie: _bauid

Vous devez également écrire des tests pour votre balise. Pour en savoir plus sur les tests de modèles, consultez la section Tests du guide du développeur de modèles.

Enfin, n'oubliez pas d'essayer d'exécuter votre balise au moins une fois à l'aide du bouton Run Code (Exécuter le code). Vous éviterez ainsi que de nombreuses erreurs simples se produisent sur votre serveur.

Envoyer votre tag dans la galerie de modèles de la communauté

Étant donné que vous avez réalisé toutes les étapes de création, de test et de déploiement d'une nouvelle balise, il n'y a aucune raison de la garder pour vous. Si vous pensez que votre nouvelle balise pourrait être utile à d'autres personnes, pensez à l'envoyer dans la galerie de modèles de la communauté.

Conclusion

Dans ce tutoriel, vous avez appris les bases de l'écriture d'un tag pour un conteneur serveur. Vous avez appris à :

Quelles API utiliser pour lire les données d'événement, envoyer des requêtes HTTP et définir des cookies dans le navigateur ?
Bonnes pratiques pour concevoir les options de configuration d'une balise
Différence entre les données spécifiées par l'utilisateur et les données collectées automatiquement, et pourquoi cette distinction est importante.
Rôle d'une balise dans le conteneur (ce qu'elle doit et ne doit pas faire)
Quand et comment envoyer des modèles de balises à la galerie de modèles de la communauté