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 :
- config
- get
- set
- event
- consent
<command parameters> correspond aux paramètres que vous pouvez transmettre à gtag(). Les paramètres de commande varient en fonction de la commande. Consultez la documentation de référence sur les commandes.

Vous pouvez appeler les 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 à une page, consultez le guide d'installation.

Champ d'application du paramètre

Vous pouvez définir la portée des valeurs de paramètres sur des événements individuels, sur tous les événements envoyés à un <TARGET_ID> spécifique ou de manière globale sur 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 celles définies pour le même paramètre dans un autre champ d'application. Dans l'exemple suivant, la commande config ne modifie pas la valeur globale de campaign_id précédemment attribuée avec la commande set. Une fois les deux commandes exécutées, la valeur globale de campaign_id reste '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 différentes valeurs 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 sont prioritaires sur les paramètres limités à config, et les paramètres config sont prioritaires sur les paramètres de portée globale utilisant 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>});

Points clés concernant <TARGET_ID> :

Le <TARGET_ID> de la commande gtag('config', <TARGET_ID>, ...) est un ID de balise qui indique à gtag.js où envoyer les données d'événement. Il peut s'agir d'une destination telle qu'une propriété Google Analytics, un compte Google Ads, une configuration Floodlight ou une balise Google comportant plusieurs destinations.
Un ID de balise (par exemple, GT-XXXXXX, G-XXXXXX ou AW-YYYYYY) est un identifiant pour votre balise Google. Vous ajoutez cet ID au code de votre site Web pour charger la balise Google.
Une même balise Google (identifiée par son ID) peut être configurée pour envoyer des données à plusieurs destinations. Bien que certains ID de balise puissent sembler identiques aux ID de destination (par exemple, G-XXXXXX pour une propriété Google Analytics ou AW-YYYYYY pour un compte Google Ads), le <TARGET_ID> dans la commande config fait référence à l'instance particulière de la balise Google chargée sur la page.
La commande gtag('config', ...) configure le comportement de la balise Google associée à ce <TARGET_ID> spécifique. Bien que l'ID de balise inclus dans le script src charge généralement la balise Google, vous pouvez utiliser n'importe quel ID de balise valide associé à votre compte dans la commande gtag('config').
Une même balise Google peut être associée à plusieurs ID de balise, souvent en raison de la fusion de balises. Vous pouvez utiliser l'un de ces ID associés dans le paramètre src du script pour charger la balise Google.
Si vous envoyez des données vers plusieurs destinations ou si vous utilisez plusieurs balises, il vous suffit d'inclure un seul extrait de balise Google avec un ID de balise dans le script src. Vous incluez ensuite une commande gtag('config') pour chaque ID de tag ou destination supplémentaire.

<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 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`

Elle vous permet d'obtenir différentes valeurs auprès de gtag.js, y compris celles définies avec la commande set.

gtag('get', '<target>', '<field_name>', callback)

Argument	Type	Exemple	Description
<target>	`string`	G-XXXXXXXXXX	Cible à partir de laquelle les valeurs doivent être extraites
<field_name>	Nom du champ	client_id	Nom du champ à obtenir
callback	`Function`	`(field) => console.log(field)`	Fonction qui sera appelée avec le champ demandé (ou `undefined` s'il n'est pas défini)

Nom du champ

Le nom du champ peut être celui d'un champ personnalisé que vous avez défini 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
session_number	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 que plusieurs balises sur la même page puissent y accéder.

L'exemple suivant illustre la définition d'un nom et d'un ID de campagne pour un événement shopping du Black Friday. Comme vous avez utilisé set, tous les autres tags (par exemple, les tags d'événement GA4 ou les tags 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> peut être l'une des valeurs suivantes :

Un événement recommandé. Chaque événement recommandé peut accepter des paramètres recommandés.
Un événement personnalisé. Un événement personnalisé est un nom d'événement arbitraire que vous inventez, avec des paramètres arbitraires. Pour en savoir plus, consultez Configurer des événements.

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

Important : L'extrait de la balise Google doit figurer sur la même page, au-dessus des commandes event, sinon vos données ne seront pas envoyées.

`consent`

Utilisez la commande consent pour configurer le consentement.

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

Pour en savoir plus sur le comportement que ces paramètres configurent, 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 indiqué son consentement.

Les <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 pour le Web ou les identifiants d'application pour les applications) lié à l'analyse (par exemple, la durée des visites).
`wait_for_update`	tout entier positif	Définit un délai en millisecondes pour l'appel de mise à jour du consentement.