Documentation de référence de 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 varient selon la commande. Reportez-vous à la documentation de référence sur les commandes ci-dessous.

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

Champ d'application du paramètre

Vous pouvez définir la portée des valeurs des paramètres sur des événements individuels, tous les événements envoyés à un <TARGET_ID> spécifique ou globalement pour tous les événements. Pour ce faire, utilisez les commandes event, config et set.

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

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Priorité des paramètres

Si des valeurs différentes sont attribuées au même paramètre dans différentes portées, une seule valeur est utilisée lors du traitement des événements. Les valeurs de paramètre limitées à event seront prioritaires sur les paramètres limités à config, et les paramètres config seront prioritaires sur les paramètres définis au niveau mondial à l'aide de set.

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// 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>' });

config

Vous 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 la configurer 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');

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

Pour vous montrer 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 différentes valeurs à partir de gtag.js, y compris les valeurs définies avec la commande set.

gtag('get', '<target>', '<field_name>', callback)
Argument Type Exemple Description
<target> string G-XXXXXXXXXX

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

Une fonction qui sera appelée avec le champ demandé, ou undefined si ce champ n'est pas défini.

FieldName

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

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

Exemples

Obtenir une valeur dans une promesse 

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

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

Envoyer un événement au protocole de mesure 

gtag('get', 'G-XXXXXXXXXX', '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', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

set

La commande set vous permet de définir des paramètres qui seront associés à chaque événement ultérieur sur la page.

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

Par exemple, vous pouvez partager des paramètres de campagne afin qu'ils soient accessibles par plusieurs balises sur la même page.

L'exemple ci-dessous montre comment définir un nom et un ID de campagne pour un événement commercial du Black Friday. Étant donné que vous avez utilisé set, toutes les autres balises, comme les balises d'événement GA4 ou les balises de remarketing Google Ads, peuvent accéder à ces données.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

event

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

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

<event_name> est l'un des éléments suivants :

<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 configuré par 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 acceptés:

Nom du champ Valeurs autorisées Description
ad_storage 'granted' | 'denied' Permet le stockage (comme les cookies (Web) ou les identifiants d'appareils (applications)) lié à la publicité.
ad_user_data 'granted' | 'denied' Définit le consentement pour l'envoi de données utilisateur à Google à des fins publicitaires.
ad_personalization 'granted' | 'denied' Définit le consentement pour la publicité personnalisée.
analytics_storage 'granted' | 'denied' Permet le stockage (comme les cookies (Web) ou les identifiants d'application (applications)) lié à l'analyse (par exemple, la durée des visites).
wait_for_update tout entier positif Définit le délai d'attente en millisecondes pour un appel de mise à jour du consentement.