API de taggage côté serveur

Ce document décrit les API pour le taggage côté serveur.

addEventCallback

Enregistre une fonction de rappel qui sera appelée à la fin d'un événement. Le rappel est appelé lorsque tous les tags de l'événement ont été exécutés. Le rappel reçoit deux valeurs: l'ID du conteneur qui appelle la fonction et un objet contenant des informations sur l'événement.

Lorsqu'elle est utilisée dans une balise, elle est associée à l'événement en cours. Lorsque cette API est utilisée dans un client, elle doit être liée à un événement spécifique à l'aide de la fonction bindToEvent de l'API runContainer. Pour en savoir plus, consultez l'exemple.

Syntaxe

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

Paramètres

L'objet eventData contient les données suivantes :

Exemple

Dans un client :

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

Dans une balise:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

Autorisations associées

read_event_metadata

callLater

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

Exemple

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

Syntaxe

callLater(function)

Paramètres

Autorisations associées

Aucune.

claimRequest

Utilisez cette API dans un client pour revendiquer la requête. Une fois une requête revendiquée, le conteneur n'exécute pas de clients supplémentaires.

Cette API génère une exception si elle est appelée dans une balise ou une variable. Cette API génère une exception si elle est appelée après le retour du client (par exemple, si elle est appelée dans un rappel asynchrone tel que dans callLater ou la fonction onComplete runContainer).

Un client doit revendiquer la requête à l'aide de cette API avant d'appeler l'API runContainer.

Exemple

const claimRequest = require('claimRequest');

claimRequest();

Syntaxe

claimRequest();

Autorisations associées

Aucune.

computeEffectiveTldPlusOne

Renvoie le domaine de premier niveau effectif (eTLD+1) du domaine ou de l'URL donnés. L'eTLD+1 est calculé en évaluant le domaine par rapport aux règles de la liste des suffixes publics. L'eTLD+1 est généralement le domaine de premier niveau le plus élevé sur lequel vous pouvez définir un cookie.

Si l'argument est nul ou non défini, sa valeur est renvoyée sans modification. Sinon, l'argument est converti en chaîne. Si l'argument n'est pas un domaine ou une URL valide, une chaîne vide est renvoyée. Si le serveur ne parvient pas à extraire la liste des suffixes publics, la valeur de l'argument est renvoyée sans modification.

Exemple

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

Syntaxe

computeEffectiveTldPlusOne(domainOrUrl);

Paramètres

Autorisations associées

Aucune.

createRegex

Crée une instance d'expression régulière et la renvoie encapsulée dans un objet. Vous ne pouvez pas accéder directement à l'expression régulière. Toutefois, vous pouvez le transmettre à l'API testRegex, String.replace(), String.match() et String.search().

Renvoie null si l'expression régulière n'est pas valide ou si Re2 n'est pas disponible sur le serveur.

Cette API utilise une implémentation Re2. L'image Docker du serveur doit être la version 2.0.0 ou ultérieure.

Exemple

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

Syntaxe

createRegex(pattern, flags);

Paramètres

Autorisations associées

Aucune.

Version minimale de l'image

2.0.0

decodeUri

Décode tous les caractères encodés dans l'URI fourni. Renvoie une chaîne qui représente l'URI décodé. Renvoie undefined lorsqu'une entrée non valide est fournie.

Exemple

const decodeUri = require('decodeUri');

const decodedUrl = decodeUri(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 d'URI fourni. Renvoie une chaîne représentant le composant d'URI décodé. Renvoie undefined en cas d'entrée non valide.

Exemple

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

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 représentant la chaîne fournie encodée en tant qu'URI.

Exemple

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('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.

Exemple

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

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

Syntaxe

encodeUriComponent(str);

Paramètres

Autorisations associées

Aucune.

extractEventsFromMpv1

Convertit une requête entrante du protocole de mesure V1 en liste d'événements au format de schéma unifié. Renvoie la liste des événements extraits. Génère une erreur si le format de la requête n'est pas correct.

Exemple

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Syntaxe

extractEventsFromMpv1();

Autorisations associées

Autorisation read_request requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• body
• query parameters

extractEventsFromMpv2

Convertit une requête entrante du protocole de mesure V2 en liste d'événements au format de schéma unifié. Renvoie la liste des événements extraits. Génère une erreur si le format de la requête n'est pas correct.

Exemple

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Syntaxe

extractEventsFromMpv2();

Autorisations associées

Autorisation read_request requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• body
• query parameters

fromBase64

Décode une chaîne encodée en base64. Renvoie undefined si l'entrée est incorrecte.

Syntaxe

fromBase64(base64EncodedString);

Paramètres

Exemple

const fromBase64 = require('fromBase64');

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

Autorisations associées

Aucune.

generateRandom

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

Exemple

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Syntaxe

generateRandom(min, max);

Paramètres

Autorisations associées

Aucune.

getAllEventData

Renvoie une copie des données d'événement.

Syntaxe

getAllEventData();

Autorisations associées

read_event_data

getClientName

Renvoie une chaîne contenant le nom du client actuel.

Syntaxe

getClientName();

Autorisations associées

read_container_data

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 containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Syntaxe

getContainerVersion();

Autorisations associées

read_container_data

getCookieValues

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

Exemple

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

Syntaxe

getCookieValues(name[, noDecode]);

Paramètres

Autorisations associées

get_cookies

getEventData

Renvoie une copie de la valeur au chemin d'accès donné dans les données d'événement. Renvoie undefined s'il n'y a pas de données d'événement ou s'il n'y a pas de valeur au chemin d'accès donné.

Exemple

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

Paramètres

Syntaxe

getEventData(keyPath);

Autorisations associées

read_event_data

getGoogleAuth

Renvoie un objet d'autorisation qui, lorsqu'il est utilisé avec sendHttpGet ou sendHttpRequest, inclut un en-tête d'autorisation pour les API Google Cloud. Cette API utilise les identifiants par défaut de l'application pour rechercher automatiquement des identifiants dans l'environnement serveur.

Exemple

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

Syntaxe

getGoogleAuth(scopes);

Paramètres

Autorisations associées

Autorisation use_google_credentials requise. L'autorisation doit être configurée avec un ou plusieurs niveaux d'accès autorisés.

getGoogleScript

Récupère une ressource à partir d'un ensemble prédéterminé de scripts Google, puis renvoie une promesse avec le script et les métadonnées de mise en cache associées.

La promesse se résout en un objet contenant deux clés: script et metadata. Si la requête échoue, la promesse est rejetée avec une clé reason.

L'objet metadata contient les métadonnées de mise en cache suivantes en fonction des en-têtes de réponse de la ressource. Chaque champ ne sera présent que si l'en-tête correspondant est présent dans la réponse de la ressource.

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

Exemple

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

Syntaxe

getGoogleScript(script[, options]);

Paramètres

Options

Les clés d'option non reconnues sont ignorées.

Autorisations associées

Autorisation send_http requise. L'autorisation doit être configurée pour autoriser l'accès à au moins :

• Autoriser les domaines Google

getRemoteAddress

Renvoie une chaîne représentant l'adresse IP à partir de laquelle la requête a été émise, par exemple 12.345.67.890 pour IPv4 ou 2001:0db8:85a3:0:0:8a2e:0370:7334 pour IPv6, en lisant les en-têtes de requête tels que "Forwarded" et "X-Forwarded-For". Remarque: Cette API s'efforce de détecter l'adresse IP d'origine, mais ne peut pas garantir que le résultat est exact.

Syntaxe

getRemoteAddress();

Autorisations associées

Autorisation read_request requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• En-têtes Forwarded et X-Forwarded-For
• Adresse IP distante

getRequestBody

Renvoie le corps de la requête sous forme de chaîne, le cas échéant, ou undefined dans le cas contraire.

Syntaxe

getRequestBody();

Autorisations associées

read_request

getRequestHeader

Renvoie la valeur de l'en-tête de requête nommé sous forme de chaîne, le cas échéant, ou undefined dans le cas contraire. Si l'en-tête est répété, les valeurs renvoyées sont jointes avec ', '.

Exemple

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Syntaxe

getRequestHeader(headerName);

Paramètres

Autorisations associées

read_request

getRequestMethod

Renvoie la méthode de requête, par exemple 'GET' ou 'POST', sous forme de chaîne.

Exemple

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

Syntaxe

getRequestMethod();

Autorisations associées

Aucune.

getRequestPath

Renvoie le chemin de la requête sans la chaîne de requête. Par exemple, si l'URL est '/foo?id=123', la valeur renvoyée est '/foo'. Supprime automatiquement le préfixe de l'URL du conteneur de serveur du chemin. Par exemple, si l'URL du conteneur serveur est https://example.com/analytics et que le chemin de la requête est '/analytics/foo', la valeur renvoyée est '/foo'.

Exemple

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

Syntaxe

getRequestPath();

Autorisations associées

read_request

getRequestQueryParameter

Renvoie la valeur décodée du paramètre de chaîne de requête nommé sous forme de chaîne ou undefined si le paramètre n'est pas présent. Si le paramètre est répété dans la chaîne de requête, la première valeur qui apparaît dans la chaîne de requête est renvoyée.

Exemple

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

Syntaxe

getRequestQueryParameter(name);

Paramètres

Autorisations associées

read_request

getRequestQueryParameters

Renvoie les paramètres de requête de la requête HTTP entrante en tant qu'objet qui met en correspondance les noms de paramètres de requête avec la ou les valeurs correspondantes. Les noms et les valeurs des paramètres sont décodés.

Exemple

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

Syntaxe

getRequestQueryParameters();

Autorisations associées

read_request

getRequestQueryString

Renvoie la requête de la demande sous forme de chaîne, sans le point d'interrogation initial, ou une chaîne vide si l'URL de la requête n'inclut pas de chaîne de requête.

Exemple

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

Syntaxe

getRequestQueryString();

Autorisations associées

read_request

getTimestamp

Obsolète. Préférez getTimestampMillis.

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

Syntaxe

getTimestamp();

Autorisations associées

Aucune.

getTimestampMillis

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

Syntaxe

getTimestampMillis();

Autorisations associées

Aucune.

getType

Renvoie une chaîne décrivant le type de la valeur donnée.

Exemple

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

Syntaxe

getType(value);

Paramètres

Autorisations associées

Aucune.

hmacSha256

Calcule une signature encodée à l'aide d'un code d'authentification de message basé sur le hachage (HMAC) avec SHA-256. La valeur par défaut est l'encodage base64url.

Pour utiliser cette API, définissez la variable d'environnement SGTM_CREDENTIALS sur le serveur sur le chemin d'accès d'un fichier de clé JSON encodé en UTF-8 au format suivant:

{
  "keys": {
    "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
    "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
    ...
  }
}

Les valeurs sont des clés HMAC encodées en base64. Le texte JSON ne doit pas commencer par un indicateur d'ordre des octets.

Exemple

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

Syntaxe

hmacSha256(data, keyId, options)

Paramètres

Options

Autorisations associées

use_custom_private_keys

Version minimale de l'image

1.0.0

isRequestMpv1

Renvoie true si la requête entrante est une requête Measurement Protocol V1, ou false si ce n'est pas le cas.

Exemple

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

Syntaxe

isRequestMpv1();

Autorisations associées

Aucune.

isRequestMpv2

Renvoie true si la requête entrante est une requête Protocole de mesure (V2), ou false si ce n'est pas le cas.

Exemple

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

Syntaxe

isRequestMpv2();

Autorisations associées

Aucune.

logToConsole

Consigne son ou ses arguments dans la console.

Ces journaux sont visibles dans l'explorateur de journaux de la console Google Cloud. Dans l'explorateur de journaux, exécutez la requête logName =~ "stdout" pour afficher les entrées de journal créées par cette API.

Exemple

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

Syntaxe

logToConsole(argument1[, argument2, ...]);

Paramètres

L'API accepte un ou plusieurs arguments, chacun étant converti en chaîne, si nécessaire, et consigné dans la console.

Autorisations associées

logging

makeInteger

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

Syntaxe

makeInteger(value);

Paramètres

Autorisations associées

Aucune.

makeNumber

Convertit la valeur donnée en nombre.

Syntaxe

makeNumber(value);

Paramètres

Autorisations associées

Aucune.

makeString

Renvoie la valeur donné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. Il permet de convertir un champ de modèle SIMPLE_TABLE à deux colonnes en un format 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: les Map converties 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.

parseUrl

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

Cette API renvoie undefined pour toute URL mal formée. Pour les URL correctement formatées, les champs qui ne figurent pas dans la chaîne d'URL auront une valeur de chaîne vide ou, dans le cas de searchParams, d'objet vide.

L'objet renvoyé contient 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.

returnResponse

Efface la réponse précédemment définie par d'autres modèles à l'aide des API qui modifient la réponse, y compris setCookie, setPixelResponse, setResponseBody, setResponseHeader et setResponseStatus. Par défaut, le code d'état HTTP est 200, le corps est vide et il n'y a pas d'en-têtes.

Il est recommandé d'utiliser cette API à partir d'un modèle client.

Syntaxe

returnResponse();

Exemple

Consultez l'exemple runContainer.

Autorisations associées

return_response

runContainer

Exécute la logique du conteneur (variables, déclencheurs, balises) dans le champ d'application d'un événement. Si cette API est appelée pendant l'exécution du conteneur, celui-ci est exécuté à nouveau.

Les rappels onComplete et onStart reçoivent une fonction appelée bindToEvent. Utilisez bindToEvent pour exécuter une API dans le contexte de l'événement. Pour en savoir plus, consultez l'exemple addEventCallback.

Il est recommandé d'utiliser cette API à partir d'un modèle client.

Exemple

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

Syntaxe

runContainer(event, onComplete, onStart);

Paramètres

Autorisations associées

run_container

sendEventToGoogleAnalytics

Envoie un seul événement à l'aide de données d'événement communes à Google Analytics et renvoie une promesse qui se résout en un objet avec une clé location ou qui est rejetée en un objet avec une clé reason. La destination, Google Analytics 4, est basée sur l'ID de mesure dans les données d'événement.

Le champ location est défini sur l'en-tête location, le cas échéant.

Exemple

const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

Syntaxe

sendEventToGoogleAnalytics(event);

Paramètres

Autorisations associées

Autorisation send_http requise. L'autorisation doit être configurée pour autoriser l'accès à au moins :

• Autoriser les domaines Google

sendHttpGet

Envoie une requête HTTP GET à l'URL spécifiée et renvoie une promesse qui se résout avec le résultat une fois la requête terminée ou expirée.

Le résultat résolu est un objet contenant trois clés : statusCode, headers et body. Si la requête a échoué (par exemple, URL non valide, pas de route vers l'hôte, échec de la négociation SSL, etc.), la promesse est rejetée avec : {reason: 'failed'}. Si l'option timeout a été définie et que la requête a expiré, la promesse est rejetée avec : {reason: 'timed_out'}

Exemple

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

Syntaxe

sendHttpGet(url[, options]);

Paramètres

Options

Autorisations associées

send_http

sendHttpRequest

Envoie une requête HTTP à l'URL spécifiée et renvoie une promesse qui se résout avec la réponse une fois la requête terminée ou arrivée à expiration.

Le résultat résolu est un objet contenant trois clés : statusCode, headers et body. Si la requête a échoué (par exemple, URL non valide, pas de route vers l'hôte, échec de la négociation SSL, etc.), la promesse est rejetée avec : {reason: 'failed'}. Si l'option timeout a été définie et que la requête a expiré, la promesse est rejetée avec : {reason: 'timed_out'}

Exemple

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

Syntaxe

sendHttpRequest(url[, options[, body]]);

Paramètres

Options

Autorisations associées

send_http

sendPixelFromBrowser

Envoie une commande au navigateur pour charger l'URL fournie en tant que balise <img>. Ce protocole de commande est compatible avec la balise Google pour GA4 et les balises Web Google Analytics: Événement GA. Vous devez configurer l'URL du conteneur du serveur. Pour en savoir plus, consultez les instructions.

Cette API renvoie false si la requête entrante n'est pas compatible avec le protocole de commande ou si la réponse a déjà été effacée. Sinon, cette API renvoie true.

Exemple :

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

Syntaxe

sendPixelFromBrowser(url)

Paramètres

Autorisations associées

send_pixel_from_browser

setCookie

Définit ou supprime un cookie avec les options spécifiées.

Pour supprimer un cookie, vous devez définir un cookie avec le même chemin d'accès et le même domaine que celui avec lequel le cookie a été créé, et lui attribuer une valeur d'expiration passée (par exemple, "Thu, 01 Jan 1970 00:00:00 GMT").

Notez que returnResponse doit être appelé pour que la réponse soit renvoyée au client.

Exemple

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

Syntaxe

setCookie(name, value[, options[, noEncode]]);

Paramètres

Options

• domain : hôte auquel le cookie sera envoyé. S'il est défini sur la valeur spéciale "auto", l'hôte sera automatiquement calculé à l'aide de la stratégie suivante:

  • eTLD+1 de l'en-tête Forwarded, le cas échéant.
  • eTLD+1 de l'en-tête X-Forwarded-Host, le cas échéant.
  • eTLD+1 de l'en-tête Host.

• expires: durée de vie maximale du cookie. Il doit s'agir d'une chaîne de date au format UTC, par exemple "Sat, 26 Oct 1985 08:21:00 GMT". Si expires et max-age sont tous deux définis, max-age prévaut.

• httpOnly: interdit à JavaScript d'accéder au cookie si true.

• max-age: nombre de secondes avant l'expiration du cookie. Un nombre nul ou négatif entraîne l'expiration immédiate du cookie. Si expires et max-age sont tous deux définis, max-age prévaut.

• path: chemin d'accès qui doit exister dans l'URL demandée, sinon le navigateur n'enverra pas l'en-tête Cookie.

• secure: si la valeur est true, le cookie n'est envoyé au serveur que lorsqu'une requête est effectuée à partir d'un point de terminaison https:.

• sameSite: indique qu'un cookie ne doit pas être envoyé avec des requêtes inter-origines. La valeur doit être 'strict', 'lax' ou 'none'.

Autorisations associées

set_cookie

setPixelResponse

Définit le corps de la réponse sur un GIF 1x1, définit l'en-tête Content-Type sur "image/gif", définit les en-têtes de mise en cache de sorte que les agents utilisateur ne mettent pas en cache la réponse et définit l'état de la réponse sur 200.

Notez que returnResponse doit être appelé pour que la réponse soit renvoyée au client.

Syntaxe

setPixelResponse();

Autorisations associées

Autorisation access_response requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• headers : doit autoriser les clés suivantes
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

setResponseBody

Définit le corps de la réponse sur l'argument.

Notez que returnResponse doit être appelé pour que la réponse soit renvoyée au client.

Syntaxe

setResponseBody(body[, encoding]);

Paramètres

Autorisations associées

Autorisation access_response requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• body

setResponseHeader

Définit un en-tête dans la réponse qui sera renvoyée. Si un en-tête portant ce nom (insensible à la casse) a déjà été défini par cette API, cet appel remplacera ou effacera la valeur définie par l'appelant précédent.

Notez que returnResponse doit être appelé pour que la réponse soit renvoyée au client.

Syntaxe

setResponseHeader(name, value);

Paramètres

Autorisations associées

Autorisation access_response requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• headers

setResponseStatus

Définit le code d'état HTTP de la réponse qui sera renvoyée.

Notez que returnResponse doit être appelé pour que la réponse soit renvoyée au client.

Syntaxe

setResponseStatus(statusCode);

Paramètres

Autorisations associées

Autorisation access_response requise. L'autorisation doit être configurée pour autoriser l'accès à au moins:

• status

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 autre encodage de sortie.

La signature et le comportement de cette API correspondent à l'API sha256 pour les conteneurs Web. Toutefois, les modèles personnalisés dans les conteneurs serveur doivent utiliser l'API sha256Sync pour un code plus simple.

Exemple

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

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

Syntaxe

sha256(input, onSuccess, options = undefined);

Paramètres

Autorisations associées

Aucune.

sha256Sync

Calcule et renvoie le condensé SHA-256 de l'entrée, encodé en base64, sauf si l'objet options spécifie un autre encodage de sortie.

Exemple

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

Syntaxe

sha256Sync(input, options = undefined);

Paramètres

Autorisations associées

Aucune.

templateDataStorage

Renvoie un objet avec des méthodes permettant d'accéder au stockage des données de modèle. Le stockage des données de modèle permet de partager les données entre les exécutions d'un même modèle. Les données stockées dans le stockage de données de modèle persistent sur le serveur exécutant le conteneur. Dans la plupart des cas, plusieurs serveurs exécutent le conteneur. Le stockage de données dans le stockage de données de modèle ne garantit donc pas que chaque requête ultérieure aura accès aux données.

Le terme "données" dans le nom "templateDataStorage" fait référence au fait que seuls les types de données simples, non fonctionnels, peuvent être stockés à l'aide de cette API. Toutes les fonctions ou références à des fonctions transmises à l'API seront stockées en tant que null.

Syntaxe

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

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

Exemple

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

Autorisations associées

access_template_storage

testRegex

Teste une chaîne avec une expression régulière créée via l'API createRegex. Renvoie true si l'expression régulière correspond. Renvoie false dans les autres cas.

Une expression régulière créée avec l'indicateur global est à état. Pour en savoir plus, consultez la documentation sur RegExp.

Exemple

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

Syntaxe

testRegex(regex, string);

Paramètres

Autorisations associées

Aucune.

toBase64

Encode une chaîne en base64 ou en base64url. L'encodage par défaut est base64.

Syntaxe

toBase64(input, options);

Paramètres

Options

Exemple

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

Autorisations associées

Aucune.

BigQuery

Renvoie un objet qui fournit des fonctions BigQuery.

La fonction BigQuery.insert permet d'écrire des données dans une table BigQuery. Il renvoie une promesse qui se résout en cas d'insertion réussie ou qui est refusée en cas d'erreur.

Lorsque l'insertion aboutit, la promesse est résolue sans argument.

Lorsque l'insertion échoue, la promesse est rejetée avec une liste d'objets contenant la raison de l'erreur et éventuellement un objet ligne si une erreur se produit. Il est possible qu'une partie de la requête aboutisse, tandis que d'autres ne le fassent pas. Dans ce cas, la promesse est rejetée avec une liste d'erreurs pour chaque ligne avec un objet de ligne pour aider à distinguer les lignes insérées (voir Exemples d'erreurs ci-dessous). Pour en savoir plus, consultez la documentation de BigQuery sur les messages d'erreur.

Syntaxe

BigQuery.insert(connectionInfo, rows[, options]);

Paramètres

Options

Exemples d'erreurs

Une erreur de module introuvable signifie que votre conteneur serveur exécute probablement une ancienne version de notre image qui n'incluait pas encore le module BigQuery. Veuillez redéployer votre conteneur serveur avec les mêmes paramètres à l'aide de notre script de déploiement. Le module sera automatiquement inclus une fois l'opération terminée.

Une erreur de non-insertion comporte généralement un objet d'erreur avec une clé reason:

[{reason: 'invalid'}]

Une erreur d'insertion peut contenir plusieurs objets d'erreur avec un tableau errors et un objet row. Voici un exemple de réponse d'erreur lors de l'insertion de deux lignes, dont une seule comporte une erreur:

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

Exemple

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

Autorisations associées

access_bigquery

Firestore

Renvoie un objet qui fournit des fonctions Firestore.

Cette API n'est compatible qu'avec Firestore en mode natif, et non avec Firestore en mode Datastore. De plus, l'API n'est compatible qu'avec l'utilisation de la base de données par défaut.

Firestore.read

La fonction Firestore.read lit les données d'un document Firestore et renvoie une promesse qui se résout en un objet contenant deux clés : id et data. Si le document n'existe pas, la promesse est rejetée avec un objet contenant une clé reason égale à not_found.

Syntaxe

Firestore.read(path[, options]);

Paramètres

Options

Exemple

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

La fonction Firestore.write écrit des données dans un document ou une collection Firestore. S'il s'agit d'un chemin d'accès à une collection, un document sera créé avec un ID généré de manière aléatoire. Si le chemin d'accès mène à un document qui n'existe pas, il sera créé. Cette API renvoie une promesse qui se résout en tant qu'ID du document ajouté ou modifié. Si l'option de transaction est utilisée, l'API renvoie toujours une promesse, mais ne contient pas l'ID, car les écritures sont groupées.

Syntaxe

Firestore.write(path, input[, options]);

Paramètres

Options

Exemple

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

La fonction Firestore.query interroge la collection donnée et renvoie une promesse qui se résout en un tableau de documents Firestore correspondant aux conditions de la requête. L'objet de document Firestore est identique à celui indiqué ci-dessus dans Firestore.read. Si aucun document ne correspond aux conditions de la requête, la promesse renvoyée se résout en un tableau vide.

Syntaxe

Firestore.query(collection, queryConditions[, options]);

Paramètres

Options

Exemple

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

La fonction Firestore.runTransaction permet à l'utilisateur de lire et d'écrire de manière atomique à partir de Firestore. Si une écriture simultanée ou un autre conflit de transaction se produit, la transaction sera réessayée jusqu'à deux fois. Si elle échoue au bout de trois tentatives au total, l'API la rejette avec une erreur. Cette API renvoie une promesse qui se résout en un tableau d'ID de document, pour chaque opération d'écriture, si la transaction aboutit, et est rejetée avec l'erreur en cas d'échec.

Syntaxe

Firestore.runTransaction(callback[, options]);

Paramètres

Options

Exemple

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Exemple d'erreur

Les erreurs sont disponibles dans chaque fonction Firestore et sont rejetées avec un objet contenant une clé reason:

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

Les raisons d'erreur peuvent inclure, mais sans s'y limiter, les codes d'erreur de l'API REST Firestore.

Autorisations associées

access_firestore

JSON

Renvoie un objet qui fournit des fonctions JSON.

La fonction parse() analyse une chaîne JSON pour créer la valeur ou l'objet décrit 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 convertie en 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.

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

Syntaxe

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

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.

Messages

Les API suivantes fonctionnent ensemble pour permettre de transmettre des messages entre différentes parties d'un conteneur.

addMessageListener

Ajoute une fonction qui écoute un message d'un type particulier. Lorsqu'un message de ce type est envoyé à l'aide de l'API sendMessage (généralement par une balise), le rappel est exécuté de manière synchrone. Le rappel est exécuté avec deux paramètres:

1. messageType:string
2. message:Object

Si le rappel est ajouté dans un client, il recevra des messages pour tous les événements créés par le client. Si le rappel ne doit recevoir que des messages d'un événement spécifique, liez cette API à l'événement à l'aide de bindToEvent dans la fonction onStart de l'API runContainer. Voir l'exemple

Syntaxe

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

Paramètres

Exemple

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

Autorisations associées

Autorisation use_message requise. L'autorisation doit être configurée pour autoriser au moins les éléments suivants:

• Type de message avec Usage de listen ou listen_and_send.

hasMessageListener

Renvoie la valeur "true" si un écouteur de messages a été ajouté pour le type de message donné. Sinon, renvoie la valeur "false".

Syntaxe

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Autorisations associées

Aucune.

sendMessage

Envoie un message du type spécifié à un écouteur enregistré. Vous pouvez l'utiliser pour renvoyer des messages d'une balise au client qui a exécuté le conteneur.

Syntaxe

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

Paramètres

Autorisations associées

Autorisation use_message requise. L'autorisation doit être configurée pour autoriser au moins les éléments suivants:

• Type de message avec Usage de listen_and_send ou send.

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 convertie en objet.

La méthode values() fournit le comportement Object.values() de la bibliothèque standard. 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 convertie en objet.

La méthode entries() fournit le comportement Object.entries() de la bibliothèque standard. Il renvoie un tableau de paires [key, value] de la propriété énumérable 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 convertie en objet.

La méthode freeze() fournit le comportement Object.freeze() de la bibliothèque standard. Un objet congelé ne peut plus être modifié. Congeler 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 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 celui-ci est gelé. 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 qui n'est pas figé, même si la deuxième valeur d'entrée (keyToDelete) spécifie une clé qui n'existe pas. Elle renvoie false dans tous les autres cas. Cependant, il 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.

Promise

Renvoie un objet qui fournit des méthodes permettant d'interagir avec les promesses.

Les promesses sont fonctionnellement équivalentes aux promesses JavaScript. Chaque instance comporte trois méthodes qui renvoient une promesse, ce qui permet d'effectuer d'autres actions lorsqu'une promesse est résolue:

• .then() : gère les demandes résolues et refusées. Il accepte deux rappels comme paramètres: un pour le cas de réussite et un pour le cas d'échec.
• .catch() : ne gère que les demandes refusées. Accepte un rappel comme paramètre.
• .finally() : permet d'exécuter du code, que la promesse ait été résolue ou refusée. Accepte un rappel en tant que paramètre appelé sans argument.

Une variable qui renvoie une promesse est égale à la valeur résolue de la promesse, ou à false si la promesse est refusée.

Exemple

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

Renvoie une promesse qui:

• est résolue lorsque toutes les entrées ont été résolues ; ou
• est rejetée si l'une des entrées est rejetée.

Syntaxe

Promise.all(inputs);

Paramètres

Exemple

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

Autorisations associées

Aucune.

Promise.create

Crée une promesse fonctionnellement équivalente à une promesse JavaScript.

Syntaxe

Promise.create(resolver);

Paramètres

Exemple

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

Autorisations associées

Aucune.

Tester des API

Ces API fonctionnent avec les 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'une instruction require(). [En savoir plus sur les tests de modèles personnalisés]

assertApi

Renvoie un objet de mise en correspondance qui peut être utilisé pour émettre des assertions fluides sur l'API donnée.

Syntaxe

assertApi(apiName)

Paramètres

Outils de mise en correspondance

• 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 modélisée d'après la bibliothèque [Truth] de Google. Il renvoie un objet qui peut être utilisé pour émettre des assertions fluides sur la valeur d'un sujet. Un échec d'assertion arrête immédiatement le test et le marque 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

Outils de mise en correspondance

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

Fait échouer immédiatement le test en cours 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 placées dans un bac à sable. L'API fictive 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 simulations sont réinitialisées 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 placées dans un bac à sable qui renvoient un objet. L'API peut être utilisée en toute sécurité dans le code de modèle, mais elle n'est opérationnelle que en mode test. Les simulations sont réinitialisées avant l'exécution de chaque test.

Syntaxe

mockObject(apiName, objectMock);

Paramètres