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

Créer un tag de serveur

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

Dans un conteneur serveur, les balises reçoivent les données d'événement entrantes de vos clients, les transforment et les renvoient pour les collecter et les analyser. 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 disposent de trois balises intégrées prêtes à l'emploi sans configuration personnalisée:

Google Analytics 4
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 proposées 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 écrire les vôtres. Ce tutoriel vous apprend les bases de l'écriture de vos propres tags pour un conteneur serveur.

Objectifs

Découvrez les 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 concevoir 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 quand envoyer un modèle de balise à la galerie de modèles de la communauté.

Prérequis

Un conteneur serveur déployé
Connaissances de Tag Manager, des conteneurs serveurs et de 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.

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. Il comporte les paramètres suivants:

Paramètre	Exemple	Description
id	BA-1234	ID de votre compte Baz Analytics.
en	clic	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	ID de l'utilisateur effectuant l'action. Permet d'associer plusieurs actions à un seul utilisateur.

Configuration de la balise

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

Accédez ensuite à la section Champs de l'éditeur de modèles pour ajouter les différentes options de configuration de votre balise. La question suivante est évidente: quelles options avez-vous besoin ? Trois possibilités s'offrent à vous pour créer le tag:

Configuration totale: ajoutez un champ de configuration pour chaque paramètre. Exiger de l'utilisateur qu'il configure tout explicitement.
Aucune configuration: aucune option de configuration de la balise n'est disponible. Toutes les données sont extraites directement de l'événement.
Certaines configurations: elles comportent des champs pour certains paramètres, mais pas pour d'autres.

Le fait de disposer de champs pour chaque paramètre est très flexible et offre à l'utilisateur un contrôle total sur la configuration de sa balise. En pratique, cependant, cela entraîne généralement beaucoup de travail en double. Plus précisément, des éléments tels que le paramètre l de Baz Analytics, qui contient l'URL de la page, sont clairs et universels. Il est préférable de laisser l'ordinateur saisir les mêmes données immuables à chaque fois que la balise est configurée.

La solution consiste peut-être à utiliser une balise qui ne récupère que les données d'un événement. Il s'agit de la balise la plus simple à configurer pour un utilisateur, car il n'a rien à faire. D'un autre côté, il s'agit également de 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. Ou peut-être que les hypothèses formulées par le tag sur la structure des données d'événements entrantes ne correspondent pas réellement à 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. Il est judicieux de toujours extraire certaines données de l'événement. Les autres données doivent être configurées par l'utilisateur. Comment choisissez-vous laquelle ? Pour répondre à cette question, nous devons examiner de plus près les données qui arrivent dans le conteneur.

D'où proviennent les données ?

Les données entrantes dans un conteneur serveur à partir de la balise Google Analytics 4 peuvent être 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 sont tout ce qu'un utilisateur met dans une commande event gtag.js. Par exemple, une commande comme celle-ci:

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

Les paramètres suivants seront définis dans le conteneur du serveur:

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

C'est assez simple, mais du point de vue de la balise, il est très difficile d'y faire face. Comme ces données sont saisies par l'utilisateur, elles peuvent être de n'importe quelle nature. Comme ci-dessus, l'utilisateur n'envoie peut-être que des événements recommandés et des paramètres, mais il n'est pas obligé de le faire. À l'exception importante de l'emplacement (mais pas de la valeur) du paramètre event_name, il n'existe aucune garantie concernant la forme ou la structure des données de l'utilisateur.

Heureusement, les données saisies par l'utilisateur ne sont pas les seules que le conteneur recevra. Il obtiendra également un certain nombre de données automatiquement collectées 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, des données de cookie du navigateur peuvent également être disponibles via l'API getCookieValue.

Ensemble, ces éléments forment les données collectées automatiquement que nous avons mentionnées ci-dessus. En général, il s'agit de données universelles et sémantiquement non ambiguës. 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 nous fournit un outil utile pour décider quelles données doivent être configurées par l'utilisateur et quelles données doivent être spécifiées dans la balise. Les données collectées automatiquement peuvent être lues directement à partir de l'événement. Tout le reste doit être configuré par l'utilisateur.

À la lumière de ces informations, examinez à nouveau les paramètres de la balise Baz Analytics.

ID de mesure, id:comme il n'est pas collecté automatiquement, il s'agit d'un exemple clair d'une 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. Cependant, comme sa valeur est définie par l'utilisateur, il est judicieux d'offrir la possibilité de remplacer le nom si nécessaire.
URL de la page, l:cette valeur peut être extraite du paramètre page_location, qui est collecté automatiquement par la balise de navigateur Google Analytics GA4 pour chaque événement. Par conséquent, vous ne devez pas demander à l'utilisateur de saisir une valeur manuellement.
ID utilisateur, u:dans la balise de serveur Baz Analytics, le paramètre u n'est ni spécifié par l'utilisateur, ni collecté automatiquement par la balise sur la page. Il est stocké dans un cookie de navigateur afin d'identifier les utilisateurs lors de plusieurs 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 à savoir où et comment le cookie est stocké. Comme l, le paramètre u doit être collecté automatiquement.

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

Capture d'écran de la configuration de la balise Baz Analytics.

Implémentation des balises

Maintenant que la configuration de la balise est terminée, vous pouvez passer à l'implémentation de son comportement dans 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.
Récupérez l'URL de la page à partir de la propriété page_location de l'événement.
Calculer 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 réfléchir à la façon dont la balise s'intègre au conteneur dans son ensemble. Les différents composants du conteneur jouent des rôles différents. Il existe donc également des choses que la balise ne fait pas ou ne devrait pas faire. Votre balise:

Ne doit pas examiner l'événement pour déterminer s'il doit s'exécuter. C'est à cela que sert un déclencheur.
Vous ne devez 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.

Écrire un modèle de balise qui effectue l'une de ces actions entraînerait un comportement déroutant pour les utilisateurs de votre balise. Par exemple, une balise qui envoie une réponse à la requête entrante empêcherait le client de faire de même. Cela briserait les attentes des utilisateurs concernant le comportement du conteneur.

Compte tenu de tout cela, voici une implémentation annotée de la balise dans le code JavaScript 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 l'utiliser, vous devez définir correctement ses autorisations d'API. Accédez à l'onglet Autorisations de l'éditeur de modèles et spécifiez les autorisations suivantes:

Lit les valeurs des cookies: _bauid
Lire les données d'événement: event_name et page_location
Envoi de 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 sur les tests du guide du développeur de modèles.

Enfin, n'oubliez pas d'exécuter votre balise avec le bouton Exécuter le code au moins une fois. Cela évitera de commettre de nombreuses erreurs simples sur votre serveur.

Envoyer votre balise à la galerie de modèles de la communauté

Étant donné que vous avez créé, testé et déployé une nouvelle balise, il n'y a aucune raison de la garder pour vous. Si vous pensez que votre nouvelle balise peut être utile à d'autres utilisateurs, envisagez de l'envoyer à la galerie de modèles de la communauté.

Conclusion

Dans ce tutoriel, vous avez appris les principes de base de l'écriture d'une balise pour un conteneur serveur. Vous avez appris à :

Les 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 ce qu'elle ne doit pas faire.
Quand et comment envoyer des modèles de balises à la galerie de modèles de la communauté.