API de modèles personnalisés

API principales

Ces API fonctionnent avec le code JavaScript en bac à sable pour créer des modèles personnalisés dans Google Tag Manager. Chaque API est ajoutée avec une instruction require(), par exemple :

const myAPI = require('myAPI');

addConsentListener

Enregistre une fonction d'écouteur à exécuter lorsque l'état du type de consentement spécifié change.

L'écouteur donné sera appelé chaque fois que l'état du type de consentement spécifié passera de "Refusé" à "Accordé" ou de "Accordé" à "Refusé". Un type de consentement sans état est considéré comme accordé. L'écouteur ne sera donc pas appelé si un type de consentement non défini est mis à jour et passe à "accordé". Les fonctions d'écouteur seront chargées de s'assurer que leur code s'exécute le nombre de fois approprié.

Exemple :

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

Syntaxe

addConsentListener(consentType, listener)

Paramètres

Lorsqu'un écouteur est appelé, le type de consentement qui est modifié et la nouvelle valeur de ce type de consentement lui sont transmis :

Autorisations associées

Autorisation access_consent avec accès en lecture pour le type de consentement.

addEventCallback

L'API addEventCallback vous permet d'enregistrer une fonction de rappel qui sera appelée à la fin d'un événement. Le rappel sera appelé lorsque tous les tags de l'événement auront été exécutés ou si un délai d'expiration d'événement sur la page est atteint. Le rappel reçoit deux valeurs : l'ID du conteneur qui appelle la fonction et un objet contenant des informations sur l'événement.

Syntaxe

addEventCallback(callback)

Paramètres

L'objet eventData contient les données suivantes :

Exemple

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

Autorisations associées

read_event_metadata

aliasInWindow

L'API aliasInWindow vous permet de créer un alias (par exemple, window.foo = window.bar), ce qui permet de prendre en charge certains tags qui nécessitent un alias. Attribue la valeur de l'objet window trouvé à fromPath à la clé de l'objet window à toPath. Renvoie true en cas de réussite, ou false dans le cas contraire.

Syntaxe

aliasInWindow(toPath, fromPath)

Paramètres

Exemple

aliasInWindow('foo.bar', 'baz.qux')

Autorisations associées

access_globals est requis pour toPath et fromPath. toPath nécessite un accès en écriture, tandis que fromPath nécessite un accès en lecture.

callInWindow

Vous permet d'appeler des fonctions à partir d'un chemin d'accès à l'objet window, de manière contrôlée par une règle. Appelle la fonction au chemin d'accès donné dans window avec les arguments donnés et renvoie la valeur. Si le type de retour ne peut pas être directement mappé à un type compatible avec JavaScript en bac à sable, undefined est renvoyé. Les huit types acceptés dans le JavaScript en bac à sable sont null, undefined, boolean, number, string, Array, Object et function. Si le chemin d'accès indiqué n'existe pas ou ne fait pas référence à une fonction, undefined est renvoyé.

Syntaxe

callInWindow(pathToFunction, argument [, argument2,... argumentN])

Paramètres

Autorisations associées

access_globals avec l'autorisation execute activée.

callLater

Planifie un appel à une fonction pour qu'il se produise de manière asynchrone. La fonction sera appelée après le retour du code actuel. Cela équivaut à setTimeout(<function>, 0).

Syntaxe

callLater(function)

Paramètres

copyFromDataLayer

Renvoie la valeur actuellement attribuée à la clé donnée dans la couche de données : la valeur trouvée à la clé donnée si elle est de type primitif, fonction ou littéral d'objet, ou undefined dans le cas contraire.

Syntaxe

copyFromDataLayer(key[, dataLayerVersion])

Paramètres

Autorisations associées

read_data_layer

copyFromWindow

Copie une variable à partir de l'objet window. Si la valeur dans window ne peut pas être directement mappée à un type compatible avec le JavaScript en bac à sable, undefined sera renvoyé. Les huit types acceptés dans le JavaScript en bac à sable sont null, undefined, boolean, number, string, Array, Object et function. Renvoie la valeur récupérée (et forcée).

Syntaxe

copyFromWindow(key)

Paramètres

Autorisations associées

access_globals

createArgumentsQueue

Crée une file d'attente qui est remplie d'objets d'arguments, pour prendre en charge les solutions de tag qui en ont besoin.

Crée une fonction dans le champ d'application global (c'est-à-dire window) à l'aide de l'argument fnKey (même sémantique que createQueue). Une fois la fonction créée, cette API crée ensuite un tableau dans window (s'il n'existe pas déjà) à l'aide de l'argument arrayKey.

Lorsque la fonction créée sous fnKey est appelée, elle transmet son objet d'arguments au tableau créé sous arrayKey. La valeur renvoyée par l'API est la fonction créée sous fnKey.

Cette fonction nécessite le paramètre de lecture et d'écriture pour fnKey et arrayKey dans l'autorisation access_globals.

Exemple :

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

Syntaxe

createArgumentsQueue(fnKey, arrayKey)

Paramètres

Autorisations associées

access_globals

createQueue

Crée un tableau dans window (s'il n'existe pas déjà) et renvoie une fonction qui insère des valeurs dans ce tableau.

Cette fonction nécessite le paramètre de lecture et d'écriture pour arrayKey sur l'autorisation access_globals.

Exemple :

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

Syntaxe

createQueue(arrayKey)

Paramètres

Autorisations associées

access_globals

decodeUri

Décode tous les caractères encodés dans l'URI fourni. Renvoie une chaîne représentant l'URI décodé. Renvoie undefined lorsque l'entrée fournie n'est pas valide.

Exemple :

const decode = require('decodeUri');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Syntaxe

decodeUri(encoded_uri)

Paramètres

Autorisations associées

Aucune.

decodeUriComponent

Décode tous les caractères encodés dans le composant URI fourni. Renvoie une chaîne représentant le composant URI décodé. Renvoie undefined lorsque l'entrée fournie n'est pas valide.

Exemple :

const decode = require('decodeUriComponent');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Syntaxe

decodeUriComponent(encoded_uri_component)

Paramètres

Autorisations associées

Aucune.

encodeUri

Renvoie un URI (Uniform Resource Identifier) encodé en échappant les caractères spéciaux. Renvoie une chaîne qui représente la chaîne fournie encodée en tant qu'URI. Renvoie undefined lorsqu'une entrée non valide (un substitut isolé) est fournie.

Exemple :

sendPixel('https://www.example.com/' + encodeUri(pathInput));

Syntaxe

encodeUri(uri)

Paramètres

Autorisations associées

Aucune.

encodeUriComponent

Renvoie un URI (Uniform Resource Identifier) encodé en échappant les caractères spéciaux. Renvoie une chaîne qui représente la chaîne fournie encodée en tant qu'URI. Renvoie undefined lorsqu'une entrée non valide (un substitut isolé) est fournie.

Exemple :

sendPixel('https://www.example.com/?' + encodeUriComponent(queryInput));

Syntaxe

encodeUriComponent(str)

Paramètres

Autorisations associées

Aucune.

fromBase64

L'API fromBase64 vous permet de décoder des chaînes à partir de leur représentation en base64. Renvoie undefined lorsque l'entrée fournie n'est pas valide.

Syntaxe

fromBase64(base64EncodedString)

Paramètres

Exemple

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

Autorisations associées

Aucun

generateRandom

Renvoie un nombre (entier) aléatoire dans la plage donnée.

Syntaxe

generateRandom(min, max)

Paramètres

Autorisations associées

Aucune.

getContainerVersion

Renvoie un objet contenant des données sur le conteneur actuel. L'objet renvoyé contient les champs suivants :

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

Exemple

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

Syntaxe

getContainerVersion();

Autorisations associées

read_container_data

getCookieValues

Renvoie les valeurs de tous les cookies portant le nom donné.

Syntaxe

getCookieValues(name[, decode])

Paramètres

Autorisations associées

get_cookies

getQueryParameters

Renvoie le premier ou tous les paramètres du queryKey de l'URL actuelle. Renvoie la première valeur de queryKey ou un tableau de valeurs de queryKey.

Syntaxe

getQueryParameters(queryKey[, retrieveAll])

Paramètres

Par exemple, si l'URL actuelle est https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, alors :

• getQueryParameters('var') == 'foo'
• getQueryParameters('var', false) == 'foo'
• getQueryParameters('var', null) == 'foo'
• getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Autorisations associées

get_url doit autoriser le composant query et spécifier queryKey dans les clés de requête autorisées (ou autoriser n'importe quelle clé de requête).

getReferrerQueryParameters

L'API getReferrerQueryParameters fonctionne de la même manière que getQueryParameters, sauf qu'elle agit sur le referrer au lieu de l'URL actuelle. Renvoie le premier ou tous les paramètres du queryKey du referrer donné. Renvoie la première valeur de queryKey ou un tableau de valeurs de queryKey.

Syntaxe

getReferrerQueryParameters(queryKey[, retrieveAll])

Paramètres

Par exemple, si l'URL de provenance est https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, alors :

• getReferrerQueryParameters('var') == 'foo'
• getReferrerQueryParameters('var', false) == 'foo'
• getReferrerQueryParameters('var', null) == 'foo'
• getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Autorisations associées

get_referrer doit autoriser le composant query et spécifier queryKey dans les clés de requête autorisées (ou autoriser n'importe quelle clé de requête).

getReferrerUrl

Étant donné un type de composant, l'API lit l'objet de document pour le referrer et renvoie une chaîne représentant une partie du referrer. Si aucun composant n'est spécifié, l'URL complète du site référent est renvoyée.

Syntaxe

getReferrerUrl([component])

Paramètres

Autorisations associées

get_referrer doit autoriser le composant query et spécifier queryKey dans les clés de requête autorisées (ou autoriser n'importe quelle clé de requête).

getTimestamp

Obsolète. Préférez getTimestampMillis.

Renvoie un nombre représentant l'heure actuelle en millisecondes depuis l'epoch Unix, tel que renvoyé par Date.now().

Syntaxe

getTimestamp();

Autorisations associées

Aucune.

getTimestampMillis

Renvoie un nombre représentant l'heure actuelle en millisecondes depuis l'epoch Unix, tel que renvoyé par Date.now().

Syntaxe

getTimestampMillis();

Autorisations associées

Aucune.

getType

Renvoie une chaîne décrivant le type de la valeur donnée. Contrairement à typeof, getType fait la distinction entre array et object.

Syntaxe

getType(data.someField)

Remarques

Le tableau suivant liste les chaînes renvoyées pour chaque valeur d'entrée.

Autorisations associées

Aucune.

getUrl

Renvoie une chaîne représentant tout ou partie de l'URL actuelle, en fonction d'un type de composant et de certains paramètres de configuration.

Syntaxe

getUrl(component)

Paramètres

Autorisations associées

get_url

gtagSet

Envoie une commande gtag set à la couche de données, qui sera traitée dès que possible une fois que l'événement actuel et les balises qu'il a déclenchées auront fini d'être traités (ou que le délai de traitement des balises aura expiré). La mise à jour est garantie d'être traitée dans ce conteneur avant tout élément en file d'attente dans la file d'attente de la couche de données.

Par exemple, si elle est appelée par une balise déclenchée sur Initialisation du consentement, la mise à jour sera appliquée avant le traitement de l'événement d'initialisation. Par exemple, ads_data_redaction peut être défini sur true ou false, ou url_passthrough peut être défini sur true ou false.

Exemples :

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

Syntaxe

gtagSet(object)

Paramètres

Autorisations associées

write_data_layer vérifie l'autorisation d'écriture sur dataLayer pour toutes les clés spécifiées. Si l'entrée de gtagSet est un objet simple, l'API vérifie l'autorisation d'écriture pour toutes les clés aplaties à l'intérieur de cet objet. Par exemple, pour gtagSet({foo: {bar: 'baz'}}), l'API vérifie l'autorisation d'écriture pour foo.bar.

Si l'entrée de gtagSet est une clé et une valeur d'objet non simple, l'API vérifie l'autorisation d'écriture pour cette clé. Par exemple, pour gtagSet('abc', true) , l'API vérifie l'autorisation d'écriture pour 'abc'.

Notez que s'il existe un cycle dans l'objet d'entrée, seules les clés avant d'atteindre le même objet seront vérifiées.

injectHiddenIframe

Ajoute un iFrame invisible à la page.

Les rappels sont fournis sous forme d'instances de fonction et sont encapsulés dans des fonctions JavaScript qui les appellent.

Syntaxe

injectHiddenIframe(url, onSuccess)

Paramètres

Autorisations associées

inject_hidden_iframe

injectScript

Ajoute une balise de script à la page pour charger l'URL donnée de manière asynchrone. Les rappels sont fournis sous forme d'instances de fonction et sont encapsulés dans des fonctions JavaScript qui les appellent.

Syntaxe

injectScript(url, onSuccess, onFailure[, cacheToken])

Paramètres

Autorisations associées

inject_script

isConsentGranted

Renvoie "true" si le type d'autorisation spécifié est accordé.

Le consentement pour un type de consentement spécifique est considéré comme accordé si le type de consentement a été défini sur "accordé" ou n'a pas été défini du tout. Si le type de consentement est défini sur une autre valeur, il sera considéré comme non accordé.

L'interface utilisateur de Tag Manager pour les paramètres de balise proposera une option de déclenchement systématique. Si une balise avec l'option "Toujours déclencher" activée utilise cette API, le consentement est considéré comme accordé et true est renvoyé, quel que soit l'état réel du consentement.

Exemple :

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

Syntaxe

isConsentGranted(consentType)

Paramètres

Autorisations associées

Autorisation access_consent avec accès en lecture pour le type de consentement.

JSON

Renvoie un objet qui fournit des fonctions JSON.

La fonction parse() analyse une chaîne JSON pour construire la valeur ou l'objet décrits par la chaîne. Si la valeur ne peut pas être analysée (par exemple, si le format JSON est incorrect), la fonction renvoie undefined. Si la valeur d'entrée n'est pas une chaîne, elle sera forcée à devenir une chaîne.

La fonction stringify() convertit l'entrée en chaîne JSON. Si la valeur ne peut pas être analysée (par exemple, si l'objet comporte un cycle), la méthode renvoie undefined.

Syntaxe

JSON.parse(stringInput)
JSON.stringify(value);

Paramètres

JSON.parse

JSON.stringify

Exemple

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

localStorage

Renvoie un objet avec des méthodes d'accès au stockage local.

Syntaxe

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

Autorisations associées

access_local_storage

Exemple

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

Consigne les arguments dans la console du navigateur.

Syntaxe

logToConsole(obj1 [, obj2,... objN])

Paramètres

Autorisations associées

logging

makeInteger

Convertit la valeur indiquée en nombre (entier).

Syntaxe

makeInteger(value)

Paramètres

Autorisations associées

Aucune.

makeNumber

Convertit la valeur indiquée en nombre.

Syntaxe

makeNumber(value)

Paramètres

Autorisations associées

Aucune.

makeString

Renvoie la valeur indiquée sous forme de chaîne.

Syntaxe

makeString(value)

Paramètres

Autorisations associées

Aucune.

makeTableMap

Convertit un objet de table simple à deux colonnes en Map. Cette option permet de modifier un champ de modèle SIMPLE_TABLE à deux colonnes pour le rendre plus facile à gérer.

Par exemple, cette fonction peut convertir un objet de table :

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

dans une carte :

{
  'k1': 'v1',
  'k2': 'v2'
}

Renvoie un objet : Map converti si des paires clé-valeur y ont été ajoutées, ou null dans le cas contraire.

Syntaxe

makeTableMap(tableObj, keyColumnName, valueColumnName)

Paramètres

Autorisations associées

Aucune.

Math

Objet fournissant des fonctions Math.

Syntaxe

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

Paramètres

Les paramètres des fonctions mathématiques sont convertis en nombres.

Autorisations associées

Aucune.

Object

Renvoie un objet qui fournit des méthodes Object.

La méthode keys() fournit le comportement Object.keys() de la bibliothèque standard. Il renvoie un tableau des noms de propriétés énumérables d'un objet donné dans le même ordre qu'une boucle for...in.... Si la valeur d'entrée n'est pas un objet, elle sera forcée à devenir un objet.

La méthode values() fournit le comportement de la bibliothèque standard Object.values(). Il renvoie un tableau des valeurs de propriété énumérables d'un objet donné dans le même ordre qu'une boucle for...in.... Si la valeur d'entrée n'est pas un objet, elle sera forcée à devenir un objet.

La méthode entries() fournit le comportement Object.entries() de la bibliothèque standard. Il renvoie un tableau de paires [key, value] de propriétés énumérables d'un objet donné dans le même ordre qu'une boucle for...in.... Si la valeur d'entrée n'est pas un objet, elle sera forcée à devenir un objet.

La méthode freeze() fournit le comportement Object.freeze() de la bibliothèque standard. Un objet figé ne peut plus être modifié. La fige d'un objet empêche l'ajout de nouvelles propriétés, la suppression de propriétés existantes et la modification des valeurs des propriétés existantes. freeze() renvoie le même objet que celui qui a été transmis. Un argument primitif ou nul sera traité comme s'il s'agissait d'un objet figé et sera renvoyé.

La méthode delete() fournit le comportement de l'opérateur de suppression de la bibliothèque standard. Elle supprime la clé donnée de l'objet, sauf si l'objet est figé. Comme l'opérateur de suppression de la bibliothèque standard, il renvoie true si la première valeur d'entrée (objectInput) est un objet non figé, même si la deuxième valeur d'entrée (keyToDelete) spécifie une clé qui n'existe pas. Dans tous les autres cas, elle renvoie false. Toutefois, elle diffère de l'opérateur de suppression de la bibliothèque standard sur les points suivants :

• keyToDelete ne peut pas être une chaîne délimitée par des points qui spécifie une clé imbriquée.
• delete() ne peut pas être utilisé pour supprimer des éléments d'un tableau.
• delete() ne peut pas être utilisé pour supprimer des propriétés de la portée globale.

Syntaxe

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

Paramètres

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Exemple

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

parseUrl

Renvoie un objet contenant tous les composants d'une URL donnée, semblable à l'objet URL.

Cette API renverra undefined pour toute URL mal formée. Pour les URL correctement mises en forme, les champs qui ne sont pas présents dans la chaîne d'URL auront une valeur de chaîne vide ou, dans le cas de searchParams, un objet vide.

L'objet renvoyé comportera les champs suivants :

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

Exemple

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

Syntaxe

parseUrl(url);

Paramètres

Autorisations associées

Aucune.

queryPermission

Interrogez les autorisations autorisées et limitées. Renvoie une valeur booléenne : true si une autorisation est accordée, false sinon.

Syntaxe

queryPermission(permission, functionArgs*)

Paramètres

Arguments de fonction

sendPixel, injectScript, injectHiddenIframe : le deuxième paramètre doit être une chaîne d'URL.

writeGlobals, readGlobals : le deuxième paramètre doit être la clé en cours d'écriture ou de lecture.

readUrl : aucun argument supplémentaire n'est nécessaire pour déterminer si l'intégralité de l'URL peut être lue. Pour savoir si un composant donné peut être lu, transmettez le nom du composant comme deuxième argument :

if (queryPermission('readUrl','port')) {
  // read the port
}

Pour vérifier si une clé de requête spécifique est lisible, transmettez-la en tant que troisième paramètre :

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

Autorisations associées

Aucune.

readAnalyticsStorage

Récupère les données stockées pour l'analyse et renvoie un objet avec client_id et sessions.

• client_id : chaîne représentant l'ID client utilisé pour l'analyse.
• sessions : tableau d'objets contenant des informations sur les sessions en cours. Chaque objet inclut les éléments suivants :
  • measurement_id : chaîne représentant l'ID de mesure de la destination Analytics.
  • session_id : chaîne représentant le code temporel qui identifie la session en cours.
  • session_number : nombre représentant le nombre de sessions qu'un utilisateur a démarrées jusqu'à la session en cours.

Syntaxe

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

Paramètres

Autorisations associées

read_analytics_storage

Exemple

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

Renvoie la valeur de document.characterSet.

Syntaxe

readCharacterSet()

Paramètres

Aucune.

Autorisations associées

read_character_set

readTitle

Renvoie la valeur de document.title.

Syntaxe

readTitle()

Paramètres

Aucune.

Autorisations associées

read_title

require

Importe une fonction intégrée par son nom. Renvoie une fonction ou un objet pouvant être appelé depuis votre programme. Renvoie undefined lorsque le navigateur ne prend pas en charge la fonction intégrée.

Syntaxe

require(name)

Paramètres

Exemple

const getUrl = require('getUrl');
const url = getUrl();

Autorisations associées

Aucune.

sendPixel

Effectue une requête GET à un point de terminaison d'URL spécifié.

Syntaxe

sendPixel(url, onSuccess, onFailure)

Paramètres

Autorisations associées

send_pixel

setCookie

Définit ou supprime le cookie avec le nom, la valeur et les options spécifiés.

Syntaxe

setCookie(name, value[, options, encode])

Paramètres

Options

• Domaine : défini par la propriété options['domain'], le cas échéant. Définissez cette valeur sur 'auto' pour essayer d'écrire le cookie en utilisant le domaine le plus large possible, en fonction de l'emplacement du document. Si cela échoue, il essaiera successivement des sous-domaines plus spécifiques. Si toutes ces tentatives échouent, il essaiera d'écrire le cookie sans domaine. Si aucune valeur n'est définie, le cookie sera écrit sans domaine spécifié. Remarque : Lorsqu'un cookie sans domaine spécifié est écrit dans document.cookie, l'agent utilisateur définit par défaut le domaine du cookie sur l'hôte de l'emplacement actuel du document.
• Chemin d'accès défini par options['path'], le cas échéant. Lorsqu'un cookie sans chemin spécifié est écrit dans document.cookie, le user-agent définit par défaut le chemin du cookie sur celui de l'emplacement du document actuel.
• Max-Age : défini par options['max-age'], le cas échéant.
• Expiration : définie par options['expires'], le cas échéant. Si elle est présente, il doit s'agir d'une chaîne de date au format UTC. Date.toUTCString() peut être utilisé pour mettre en forme un Date pour ce paramètre.
• Secure : défini par options['secure'], le cas échéant.
• SameSite : défini par options['samesite'], le cas échéant.

Autorisations associées

set_cookies

setDefaultConsentState

Envoie une mise à jour du consentement par défaut à la couche de données, qui sera traitée dès que possible après l'événement actuel et toutes les balises qu'il a déclenchées auront fini d'être traitées (ou lorsque le délai de traitement des balises sera atteint). La mise à jour est garantie d'être traitée dans ce conteneur avant tout élément en file d'attente dans la couche de données. En savoir plus sur le consentement

Exemple :

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

Syntaxe

setDefaultConsentState(consentSettings)

Paramètres

L'objet consentSettings est un mappage de chaînes de type de consentement arbitraires à l'une des valeurs 'granted' ou 'denied'. Il est compatible avec les valeurs suivantes :

Autorisations associées

Autorisation access_consent avec accès en écriture pour tous les types de consentement dans l'objet consentSettings.

setInWindow

Définit la valeur donnée dans window à la clé donnée. Par défaut, cette méthode ne définit pas la valeur dans window si une valeur est déjà présente. Définissez overrideExisting sur true pour définir la valeur dans window, quelle que soit la présence d'une valeur existante. Renvoie une valeur booléenne : true si la valeur a été définie correctement, et false dans le cas contraire.

Syntaxe

setInWindow(key, value, overrideExisting)

Paramètres

Autorisations associées

access_globals

sha256

Calcule le condensé SHA-256 de l'entrée et appelle un rappel avec le condensé encodé en base64, sauf si l'objet options spécifie un encodage de sortie différent.

Exemple :

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

Syntaxe

sha256(input, onSuccess, onFailure = undefined, options = undefined)

Paramètres

Autorisations associées

Aucune.

templateStorage

Renvoie un objet avec des méthodes permettant d'accéder au stockage de modèles. Le stockage de modèles permet de partager des données entre les exécutions d'un même modèle. Les données stockées dans l'espace de stockage des modèles sont conservées pendant toute la durée de vie de la page.

Syntaxe

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

// Deletes all stored values for the template.
templateStorage.clear();

Autorisations associées

access_template_storage

Exemple

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

L'API toBase64 vous permet d'encoder une chaîne en représentation base64.

Syntaxe

toBase64(input)

Paramètres

Exemple

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Autorisations associées

Aucun

updateConsentState

Envoie une mise à jour du consentement à la couche de données, qui sera traitée dès que possible après la fin du traitement de l'événement actuel et des balises qu'il a déclenchées (ou lorsque le délai de traitement des balises est atteint). La mise à jour est garantie d'être traitée dans ce conteneur avant tout élément en file d'attente dans la couche de données. En savoir plus sur le consentement

Exemple :

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

Syntaxe

updateConsentState(consentSettings)

Paramètres

L'objet consentSettings est un mappage de chaînes de type de consentement arbitraires à l'une des valeurs 'granted' ou 'denied'. Il est compatible avec les valeurs suivantes :

Autorisations associées

Autorisation access_consent avec accès en écriture pour tous les types de consentement dans l'objet consentSettings.

Tester les API

Ces API fonctionnent avec des tests JavaScript en bac à sable pour créer des tests pour les modèles personnalisés dans Google Tag Manager. Ces API de test n'ont pas besoin d'instruction require(). En savoir plus sur les tests de modèles personnalisés

assertApi

Renvoie un objet de correspondance qui peut être utilisé pour effectuer des assertions de manière fluide sur l'API donnée.

Syntaxe

assertApi(apiName)

Paramètres

Matchers

• Subject.wasCalled()
• Subject.wasNotCalled()
• Subject.wasCalledWith(...expected)
• Subject.wasNotCalledWith(...expected)

Exemples

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

assertThat

L'API assertThat est calquée sur la bibliothèque [Truth] de Google. Il renvoie un objet qui peut être utilisé pour faire des assertions de manière fluide sur la valeur d'un sujet. En cas d'échec d'une assertion, le test s'arrête immédiatement et est marqué comme ayant échoué. Toutefois, l'échec d'un test n'affectera pas les autres scénarios de test.

Syntaxe

assertThat(actual, opt_message)

Paramètres

Matchers

Exemples

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

Échoue immédiatement au test actuel et affiche le message donné, le cas échéant.

Syntaxe

fail(opt_message);

Paramètres

Exemple

fail('This test has failed.');

mock

L'API mock vous permet de remplacer le comportement des API mises en bac à sable. L'API fictive peut être utilisée dans le code du modèle, mais elle n'est opérationnelle qu'en mode test. Les mocks sont réinitialisés avant l'exécution de chaque test.

Syntaxe

mock(apiName, returnValue);

Paramètres

Exemples

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

mockObject

L'API mockObject vous permet de remplacer le comportement des API bac à sable qui renvoient un objet. L'API peut être utilisée en toute sécurité dans le code du modèle, mais elle n'est opérationnelle qu'en mode test. Les mocks sont réinitialisés avant l'exécution de chaque test.

Syntaxe

mockObject(apiName, objectMock);

Paramètres

Exemples

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

Exécute le code du modèle (c'est-à-dire le contenu de l'onglet Code) dans l'environnement de test actuel avec un objet de données d'entrée donné.

Syntaxe

runCode(data)

Paramètres

Valeur renvoyée

Renvoie la valeur d'une variable pour les modèles de variables. Renvoie undefined pour tous les autres types de modèles.

Exemple

runCode({field1: 123, field2: 'value'});