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: <ph type="x-smartling-placeholder">
  • <command parameters> correspond aux paramètres que vous pouvez transmettre à gtag(). Commande les paramètres varient selon la commande ; consultez la documentation de référence sur les commandes, ci-dessous.

Vous pouvez appeler des commandes gtag() n'importe où sur votre page, à condition que vos commandes sous l'extrait de code de la balise Google. Pour découvrir comment ajouter l'extrait 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 une <TARGET_ID> spécifique , ou globalement à 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 les valeurs définies pour dans un champ d'application différent. Dans l'exemple ci-dessous, la commande config effectue ne pas modifier la valeur globale de campaign_id précédemment attribuée avec set . Une fois les deux commandes exécutées, la valeur globale de campaign_id est '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 des portées différentes, une seule valeur est utilisée lors du traitement des événements. Valeurs de paramètre appliquées à event sera prioritaire sur les paramètres limités à config et config Les paramètres prévalent sur ceux dont le champ d'application est défini à l'échelle mondiale à 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. C'est généralement une configuration spécifique à un produit, mais vous n'avez qu'à configurer cette option 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.

Dans l'exemple ci-dessous, une balise est configurée pour envoyer des données à un compte Google Ads:

gtag('config', 'TAG_ID');

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

Voici un exemple illustrant comment envoyer des informations de configuration supplémentaires qui configure une balise pour envoyer des données à un compte Analytics Un paramètre send_page_view qui transmet une valeur de false et un groups qui transmet la valeur 'agency'.

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

get

Permet d'obtenir différentes valeurs à partir de gtag.js, y compris celles définies avec le paramètre set.

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

Cible à partir de laquelle récupérer les valeurs.
&lt;field_name&gt; 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 s'il n'est pas défini.

FieldName

Le nom du champ peut être le nom d'un champ personnalisé que vous définissez avec 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

Une promesse de valeur ajoutée 

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', '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 définissez 

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 l'événement suivant sur la page.

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

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

L'exemple ci-dessous montre comment définir le nom et l'ID d'une campagne pour le Black Friday. d'achat. Comme vous avez utilisé set, tous les autres tags, 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> est soit:

<event_params> correspond à une ou plusieurs paires paramètre/valeur. Chaque paire séparée par un 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>});

Consultez la section Consentement dans le centre d'aide pour en savoir plus sur le comportement configurer les paramètres.

<consent_arg> correspond aux 'default' ou 'update'. 'default' permet de définir les paramètres de consentement par défaut à utiliser, et 'update' permet 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 lié à la publicité, comme les cookies (Web) ou les identifiants d'appareil (applications).
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 lié aux données analytiques, comme les cookies (Web) ou les identifiants d'application (applications), par exemple la durée des visites.
wait_for_update tout entier positif Définit le délai d'attente en millisecondes avant un appel de mise à jour du consentement.