Documentation de référence sur l'API de la balise Google

L'API de la balise Google (gtag.js) se compose d'une seule fonction, gtag(), avec la syntaxe suivante:

gtag(<command>, <command parameters>);
  • <command> est l'une des commandes suivantes :
  • <command parameters> sont les paramètres que vous pouvez transmettre à gtag(). Les paramètres de la commande varient en fonction de la commande. Consultez la documentation de référence ci-dessous.

Vous pouvez appeler des commandes gtag() n'importe où sur votre page, à condition qu'elles apparaissent sous l'extrait de la balise Google. Pour savoir comment ajouter l'extrait de code à une page, consultez le guide d'installation.

config

Permet d'ajouter des informations de configuration supplémentaires aux cibles. Il s'agit généralement d'une configuration spécifique à un produit, mais vous ne devez le faire qu'une seule fois si vous utilisez à la fois Google Ads et Google Analytics.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> est un identifiant qui identifie de manière unique la cible des appels, comme une propriété Google Analytics ou un compte Google Ads. <additional_config_info> correspond à une ou plusieurs paires paramètre/valeur.

Cet exemple configure une balise pour envoyer des données à un compte Google Ads:

gtag('config', 'TAG_ID');

"TAG_ID" correspond à l'ID de la balise Google.

Pour illustrer comment envoyer des informations de configuration supplémentaires, voici un exemple qui configure une balise pour envoyer des données à un compte Analytics avec un paramètre send_page_view qui transmet une valeur de false et un paramètre groups qui transmet une valeur de 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

Permet d'obtenir diverses valeurs de gtag.js, y compris des valeurs définies à l'aide de la commande set.

gtag('get', '<target>', '<field_name>', callback)
Argument Type Exemple Description
<cible> string UA-XXXXXXXX-Y

Cible à partir de laquelle extraire les valeurs.
<nom_champ> Nom du champ client_id Nom du champ à obtenir.
rappel Function (field) => console.log(field)

Fonction qui sera invoquée avec le champ demandé ou undefined si elle n'est pas définie.

Nom du champ

Le nom du champ peut être le nom d'un champ personnalisé que vous avez défini à l'aide de la commande gtag('set') ou l'une des valeurs suivantes:

Nom du champ Cibles compatibles
client_id
  • Google Analytics 4
  • Google Analytics Universal Analytics
session_id
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Exemples

Valorisez la promesse 

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Envoyer l'événement au protocole de mesure 

gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Obtenir une valeur que vous avez définie 

gtag('set', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

Permet de définir des valeurs persistantes pour tous les appels gtag() suivants sur la page.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

<parameter-value-pair> est un nom de clé et la valeur qui persiste dans les appels gtag(). Par exemple, le code ci-dessous définit la valeur de country sur 'US' et la valeur de currency sur 'USD' pour tous les événements ultérieurs sur la page:

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

L'utilisation de la commande set diffère de la transmission directe de valeurs à la commande event. Lorsque vous transmettez des valeurs directement à une commande event, celles-ci ne s'appliquent qu'à l'événement déclenché. Avec set, les valeurs sont conservées sur la page actuelle et transmises à tous les événements ultérieurs. Pour illustrer, contrôlons les deux exemples suivants:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

et

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

Dans le premier exemple, l'événement login est transmis avec une valeur method de 'Google' et l'événement share, sans aucun paramètre. Dans le deuxième exemple, login et share sont transmis avec la valeur method de 'Google'.

event

Utilisez la commande event pour envoyer des données d'événement.

gtag('event', '<event_name>', {<event_params>});

<event_name> est:

<event_params> correspond à une ou plusieurs paires paramètre/valeur. Chaque paire est séparée par une virgule.

La commande event suivante déclenche l'événement recommandé screen_view avec deux paramètres : app_name et screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

Utilisez la commande consent pour configurer le consentement.

gtag('consent', {<consent_arg>}, {<consent_params>});

Pour en savoir plus sur le comportement de ces paramètres, consultez la section Consentement du centre d'aide.

<consent_arg> correspond aux 'default' ou 'update'. 'default' permet de définir les paramètres de consentement par défaut à utiliser et 'update' permet de mettre à jour ces paramètres une fois qu'un utilisateur a donné son consentement.

Les éléments <consent_params> suivants sont compatibles:

Nom du champ Valeurs autorisées
ad_storage 'granted' | 'denied'
analytics_storage 'granted' | 'denied'
wait_for_update Tout entier positif

Champ d'application du paramètre

Vous pouvez limiter les valeurs des paramètres à des événements individuels, à tous les événements envoyés à un <TARGET_ID> spécifique ou à tous les événements. Pour ce faire, utilisez les commandes event, config et set.

Les valeurs de paramètres définies dans un champ d'application ne modifient pas celles définies pour le même paramètre dans un champ d'application différent. Dans l'exemple ci-dessous, la commande config ne modifie pas la valeur globale de currency précédemment attribuée avec la commande set. Une fois les deux commandes exécutées, la valeur globale de currency est toujours 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

Priorité des paramètres

Si différentes valeurs sont attribuées au même paramètre dans des champs d'application différents, une seule valeur est utilisée lors du traitement des événements. Les valeurs de paramètres dont la portée est définie sur event sont prioritaires sur celles définies sur config. Les paramètres config sont prioritaires sur ceux s'appliquant globalement à set.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });