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 toutes les balises de l'événement ont été exécutées. Deux valeurs sont transmises au rappel : l'ID du conteneur qui appelle la fonction et un objet contenant des informations sur l'événement.

Lorsque cette API est utilisée dans une balise, elle est associée à l'événement actuel. 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 un tag :

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 l'appel d'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 récupérée, le conteneur n'exécute pas d'autres clients.

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 callLater ou la fonction runContainer onComplete).

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 + 1 (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 niveau le plus élevé sur lequel vous pouvez définir un cookie.

Si l'argument est nul ou non défini, la valeur de l'argument est renvoyée sans modification. Sinon, l'argument est converti en chaîne. Si l'argument n'est pas un domaine ou une URL valides, une chaîne vide est renvoyée. Si le serveur ne parvient pas à récupérer 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 aux 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 d'image minimale

2.0.0

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 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 qui représente le composant d'URI décodé. Renvoie undefined lorsqu'une entrée non valide est fournie.

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

Traduit une requête Measurement Protocol V1 entrante en une liste d'événements au format Unified Schema. Renvoie la liste des événements extraits. Génère une erreur si la requête n'est pas au bon format.

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

Nécessite l'autorisation read_request. L'autorisation doit être configurée pour permettre l'accès à au moins :

• body
• query parameters

extractEventsFromMpv2

Traduit une requête Measurement Protocol V2 entrante en une liste d'événements au format Unified Schema. Renvoie la liste des événements extraits. Génère une erreur si la requête n'est pas au bon format.

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

Nécessite l'autorisation read_request. L'autorisation doit être configurée pour permettre l'accès à au moins :

• body
• query parameters

fromBase64

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

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é comporte 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 trouver automatiquement les identifiants de l'environnement du 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

Nécessite l'autorisation use_google_credentials. L'autorisation doit être configurée avec un ou plusieurs champs d'application autorisés.

getGoogleScript

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

La promesse sera résolue 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 contiendra 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

Nécessite l'autorisation send_http. L'autorisation doit être configurée pour permettre l'accès à au moins :

• Autoriser les domaines Google

getRemoteAddress

Renvoie une représentation string de l'adresse IP à partir de laquelle la requête a été envoyée (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écouvrir l'adresse IP d'origine, mais elle ne peut pas garantir l'exactitude du résultat.

Syntaxe

getRemoteAddress();

Autorisations associées

Nécessite l'autorisation read_request. L'autorisation doit être configurée pour permettre 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, s'il est présent, 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 la forme d'une 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 fonction renvoie '/foo'. Supprime automatiquement le préfixe de l'URL du conteneur 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 sera 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 sous la forme d'un objet qui mappe les noms des paramètres de requête à la ou aux 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 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. Utilisez plutôt getTimestampMillis.

Renvoie un nombre qui représente l'heure actuelle en millisecondes depuis l'epoch Unix, comme 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.

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. L'encodage par défaut est 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 dans le cas contraire.

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 Measurement Protocol V2, ou false dans le cas contraire.

Exemple

const isRequestMpv2 = require('isRequestMpv2');

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

Syntaxe

isRequestMpv2();

Autorisations associées

Aucune.

logToConsole

Consigne 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 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 dans un format plus gérable.

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

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

en une Map :

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

Renvoie un objet : le Map converti de paires clé-valeur lui a été ajouté, ou null dans le cas contraire.

Syntaxe

makeTableMap(tableObj, keyColumnName, valueColumnName);

Paramètres

Autorisations associées

Aucune.

parseUrl

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

Cette API renverra undefined pour toute URL incorrecte. Pour les URL correctement formatées, les champs non 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é contiendra 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

Vide 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 réexécuté.

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 courantes à Google Analytics et renvoie une promesse qui se résout en un objet avec une clé location ou est rejetée en un objet avec une clé reason. La destination, Google Analytics, 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

Nécessite l'autorisation send_http. L'autorisation doit être configurée pour permettre 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 échoue (par exemple, URL non valide, aucune 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 sera 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 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 sera rejetée avec : {reason: 'failed'}. Si l'option timeout a été définie et que la requête a expiré, la promesse sera 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 Google Analytics et les balises Web Google Analytics : Événement GA. Vous devez configurer l'URL du conteneur 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é vidé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 ceux utilisés pour créer le cookie, 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 est prioritaire.

• httpOnly : interdit à JavaScript d'accéder au cookie si la valeur est 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 est prioritaire.

• 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 définie sur 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 interorigines. 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

Nécessite l'autorisation access_response. L'autorisation doit être configurée pour permettre 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

Nécessite l'autorisation access_response. L'autorisation doit être configurée pour permettre 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 (non sensible à la casse) a déjà été défini par cette API, l'appel ultérieur écrasera 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

Nécessite l'autorisation access_response. L'autorisation doit être configurée pour permettre 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

Nécessite l'autorisation access_response. L'autorisation doit être configurée pour permettre 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 encodage de sortie différent.

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 du modèle. Le stockage des données de modèle 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 données de modèle persistent sur le serveur exécutant le conteneur. Dans la plupart des cas, plusieurs serveurs exécutent le conteneur. Par conséquent, le stockage de données dans le datastore du modèle ne garantit pas que chaque requête ultérieure aura accès aux données.

Le terme "data" dans le nom "templateDataStorage" fait référence au fait que seuls les types de données simples et 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 par rapport à une expression régulière créée via l'API createRegex. Renvoie true si l'expression régulière correspond. Sinon, renvoie false.

Une expression régulière créée avec l'option globale est avec é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 base64url. La valeur par défaut est l'encodage en 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. Elle renvoie une promesse qui est résolue en cas d'insertion réussie ou rejetée en cas d'erreur.

Si l'insertion réussit, la promesse est résolue sans argument.

Lorsque l'insertion échoue, la promesse est rejetée avec une liste d'objets contenant le motif de l'erreur et éventuellement un objet de ligne si une erreur se produit. Il est possible qu'une partie de la demande soit traitée correctement, tandis que d'autres ne le sont 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 qui ont été insérées (voir Exemples d'erreurs ci-dessous). Pour en savoir plus, consultez la documentation 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. Si le chemin d'accès mène à 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 l'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 regroupé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. S'il n'y a aucun document correspondant aux conditions de la requête, la promesse renvoyée sera résolue 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. En cas de conflit d'écriture simultanée ou de transaction, la transaction sera réessayée jusqu'à deux fois. Si elle échoue après trois tentatives au total, l'API rejettera la requête et renverra 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 réussit, et qui 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 disponibles dans chaque fonction Firestore seront rejetées avec un objet contenant une clé reason :

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

Les motifs d'erreur peuvent inclure, 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 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.

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 la transmission de 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 un tag), 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 ce client. Si le rappel ne doit recevoir que les messages d'un certain événement, associez 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

Nécessite l'autorisation use_message. L'autorisation doit être configurée pour permettre au moins :

• Type de message avec un 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é. Renvoie "false" dans le cas contraire.

Syntaxe

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Autorisations associées

Aucune.

sendMessage

Envoie un message du type spécifié à un écouteur enregistré. Cela peut être utilisé pour envoyer 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

Nécessite l'autorisation use_message. L'autorisation doit être configurée pour permettre au moins :

• Type de message avec un 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. Elle 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 Object.values() de la bibliothèque standard. Elle renvoie un tableau des valeurs des 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 entries() fournit le comportement Object.entries() de la bibliothèque standard. Elle renvoie un tableau des 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 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 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. Toutefois, il diffère de l'opérateur de suppression de la bibliothèque standard de la manière suivante :

• 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 pour interagir avec les promesses.

Les promesses sont fonctionnellement équivalentes aux promesses JavaScript. Chaque instance dispose de 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 traite 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 rejetée. Accepte un rappel comme 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
• rejette lorsque 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 qui est 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 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 ne nécessitent pas d'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 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 modélisée d'après la bibliothèque [Truth] de Google. Elle renvoie un objet qui peut être utilisé pour effectuer des assertions 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

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 le 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 en 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 en 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