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> correspond à l'une des commandes suivantes :
  • config
  • get
  • set
  • event
  • consent
• <command parameters> correspondent aux paramètres que vous pouvez transmettre à gtag(). Les paramètres de commande varient en fonction de la commande. Consultez la référence de commande 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 de code à une page, consultez le guide d'installation.

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 spécifique <TARGET_ID>, ou globalement à 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 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 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 différentes valeurs sont attribuées au même paramètre dans différents champs d'application, 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 limités globalement à 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 n'avez besoin de 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 ID de balise qui identifie l'endroit où gtag.js doit envoyer les données d'événement. Il peut s'agir d'une destination telle qu'une propriété Google Analytics ou un compte Google Ads, ou d'une balise Google comportant plusieurs destinations. <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 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 send_page_view paramètre qui transmet la valeur false, et un groups paramètre qui transmet la valeur '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 set commande.

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

FieldName

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

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 à plusieurs balises sur la même page.

L'exemple ci-dessous illustre la définition d'un nom et d'un ID de campagne pour un événement d'achat du Black Friday. Comme vous avez utilisé set, toutes les autres balises, par exemple 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> correspond à l'un des éléments suivants :

• 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 créez, 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'
});

consent

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 à '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 :