API per il tagging lato server

Questo documento illustra le API per il tagging lato server.

addEventCallback

Registra una funzione di callback che verrà invocata alla fine di un evento. Il callback verrà invocato al termine dell'esecuzione di tutti i tag per l'evento. Al callback vengono passati due valori: l'ID del contenitore che invoca la funzione e un oggetto contenente informazioni sull'evento.

Quando questa API viene utilizzata in un tag, viene associata all'evento corrente. Quando questa API viene utilizzata in un client, deve essere associata a un evento specifico utilizzando la funzione bindToEvent dell'API runContainer. Per maggiori dettagli, consulta l'esempio.

Sintassi

const addEventCallback = require('addEventCallback');

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

Parametri

L'oggetto eventData contiene i seguenti dati:

Esempio

In 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();
    }
  });
});

In un tag:

const addEventCallback = require('addEventCallback');

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

Autorizzazioni associate

read_event_metadata

callLater

Pianifica una chiamata a una funzione in modo che venga eseguita in modo asincrono. La funzione verrà chiamata dopo il ritorno del codice corrente. Questo è equivalente a setTimeout(<function>, 0).

Esempio

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

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

Sintassi

callLater(function)

Parametri

Autorizzazioni associate

Nessuno.

claimRequest

Utilizza questa API in un client per rivendicare la richiesta. Una volta acquisita una richiesta, il contenitore non esegue altri client.

Questa API genera un'eccezione se viene chiamata in un tag o una variabile. Questa API genera un'eccezione se viene chiamata dopo il ritorno del client (ad es. se viene chiamata in un callback asincrono come in callLater o nella funzione runContainer onComplete).

Un client deve rivendicare la richiesta utilizzando questa API prima di chiamare l'APIrunContainer.

Esempio

const claimRequest = require('claimRequest');

claimRequest();

Sintassi

claimRequest();

Autorizzazioni associate

Nessuno.

computeEffectiveTldPlusOne

Restituisce il dominio di primo livello effettivo + 1 (eTLD+1) del dominio o dell'URL specificato. L'eTLD+1 viene calcolato valutando il dominio in base alle regole dell'elenco dei suffissi pubblici. L'eTLD+1 è in genere il dominio di primo livello su cui puoi impostare un cookie.

Se l'argomento è nullo o non definito, il valore dell'argomento viene restituito immutato. In caso contrario, l'argomento viene forzato in una stringa. Se l'argomento non è un dominio o un URL valido, viene restituita una stringa vuota. Se il server non è in grado di recuperare l'elenco dei suffissi pubblici, il valore dell'argomento viene restituito invariato.

Esempio

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

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

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

Sintassi

computeEffectiveTldPlusOne(domainOrUrl);

Parametri

Autorizzazioni associate

Nessuno.

createRegex

Crea una nuova istanza regex e la restituisce racchiusa in un oggetto. Non puoi accedere direttamente alla regex. Tuttavia, puoi trasmetterlo all'API testRegex, String.replace(), String.match() e String.search().

Restituisce null se la regex non è valida o se Re2 non è disponibile sul server.

Questa API utilizza un'implementazione di Re2. L'immagine Docker del server deve essere della versione 2.0.0 o successiva.

Esempio

const createRegex = require('createRegex');

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

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

Sintassi

createRegex(pattern, flags);

Parametri

Autorizzazioni associate

Nessuno.

Versione minima dell'immagine

2.0.0

decodeUri

Decodifica tutti i caratteri codificati nell'URI fornito. Restituisce una stringa che rappresenta l'URI decodificato. Restituisce undefined se viene fornito un input non valido.

Esempio

const decodeUri = require('decodeUri');

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

Sintassi

decodeUri(encoded_uri);

Parametri

Autorizzazioni associate

Nessuno.

decodeUriComponent

Decodifica tutti i caratteri codificati nel componente URI fornito. Restituisce una stringa che rappresenta il componente URI decodificato. Restituisce undefined se viene fornito un input non valido.

Esempio

const decodeUriComponent = require('decodeUriComponent');

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

Sintassi

decodeUriComponent(encoded_uri_component);

Parametri

Autorizzazioni associate

Nessuno.

encodeUri

Restituisce un URI (Uniform Resource Identifier) codificato eseguendo la fuga dei caratteri speciali. Restituisce una stringa che rappresenta la stringa fornita codificata come URI.

Esempio

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

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

Sintassi

encodeUri(uri);

Parametri

Autorizzazioni associate

Nessuno.

encodeUriComponent

Restituisce un URI (Uniform Resource Identifier) codificato eseguendo la fuga dei caratteri speciali. Restituisce una stringa che rappresenta la stringa fornita codificata come URI.

Esempio

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

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

Sintassi

encodeUriComponent(str);

Parametri

Autorizzazioni associate

Nessuno.

extractEventsFromMpv1

Tradisce una richiesta Measurement Protocol V1 in arrivo in un elenco di eventi in formato schema unificato. Restituisce l'elenco degli eventi estratti. Viene generato un errore se la richiesta non è nel formato corretto.

Esempio

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.
  }
}

Sintassi

extractEventsFromMpv1();

Autorizzazioni associate

Richiede l'autorizzazione read_request. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• body
• query parameters

extractEventsFromMpv2

Tradisce una richiesta Measurement Protocol V2 in arrivo in un elenco di eventi in formato schema unificato. Restituisce l'elenco degli eventi estratti. Viene generato un errore se la richiesta non è nel formato corretto.

Esempio

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.
  }
}

Sintassi

extractEventsFromMpv2();

Autorizzazioni associate

Richiede l'autorizzazione read_request. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• body
• query parameters

fromBase64

Decodifica una stringa con codifica base64. Restituisce undefined se l'input non è valido.

Sintassi

fromBase64(base64EncodedString);

Parametri

Esempio

const fromBase64 = require('fromBase64');

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

Autorizzazioni associate

Nessuno.

generateRandom

Restituisce un numero (intero) casuale nell'intervallo specificato.

Esempio

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Sintassi

generateRandom(min, max);

Parametri

Autorizzazioni associate

Nessuno.

getAllEventData

Restituisce una copia dei dati dell'evento.

Sintassi

getAllEventData();

Autorizzazioni associate

read_event_data

getClientName

Restituisce una stringa contenente il nome del client corrente.

Sintassi

getClientName();

Autorizzazioni associate

read_container_data

getContainerVersion

Restituisce un oggetto contenente i dati del contenitore corrente. L'oggetto restituito avrà i seguenti campi:

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

Esempio

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Sintassi

getContainerVersion();

Autorizzazioni associate

read_container_data

getCookieValues

Restituisce un array contenente i valori di tutti i cookie con il nome specificato.

Esempio

const getCookieValues = require('getCookieValues');

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

Sintassi

getCookieValues(name[, noDecode]);

Parametri

Autorizzazioni associate

get_cookies

getEventData

Restituisce una copia del valore nel percorso specificato nei dati dell'evento. Restituisce undefined se non sono presenti dati sugli eventi o se non è presente alcun valore nel percorso specificato.

Esempio

const getEventData = require('getEventData');

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

Parametri

Sintassi

getEventData(keyPath);

Autorizzazioni associate

read_event_data

getGoogleAuth

Restituisce un oggetto di autorizzazione che, se utilizzato con sendHttpGet o sendHttpRequest, includerà un'intestazione di autorizzazione per le API Google Cloud. Questa API utilizza le credenziali predefinite dell'applicazione per trovare automaticamente le credenziali dall'ambiente del server.

Esempio

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

Sintassi

getGoogleAuth(scopes);

Parametri

Autorizzazioni associate

Richiede l'autorizzazione use_google_credentials. L'autorizzazione deve essere configurata con uno o più ambiti consentiti.

getGoogleScript

Recupera una risorsa da un insieme predeterminato di script Google e restituisce un promise con lo script e i metadati di memorizzazione nella cache associati.

La promessa verrà risolta in un oggetto contenente due chiavi: script e metadata. Se la richiesta non va a buon fine, la promessa viene rifiutata con una chiave reason.

L'oggetto metadata conterrà i seguenti metadati di memorizzazione nella cache in base alle intestazioni di risposta della risorsa. Ogni campo sarà presente solo se l'intestazione corrispondente è presente nella risposta della risorsa.

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

Esempio

const getGoogleScript = require('getGoogleScript');

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

Sintassi

getGoogleScript(script[, options]);

Parametri

Opzioni

Le chiavi di opzione non riconosciute vengono ignorate.

Autorizzazioni associate

Richiede l'autorizzazione send_http. L'autorizzazione deve essere configurata per consentire l'accesso almeno a:

• Consenti domini Google

getRemoteAddress

Restituisce una rappresentazione in stringa dell'indirizzo IP da cui ha avuto origine la richiesta, ad esempio 12.345.67.890 per IPv4 o 2001:0db8:85a3:0:0:8a2e:0370:7334 per IPv6, leggendo le intestazioni di richiesta come Forwarded e X-Forwarded-For. Nota: questa API tenta di rilevare l'IP di origine secondo il criterio del massimo impegno, ma non può garantire che il risultato sia accurato.

Sintassi

getRemoteAddress();

Autorizzazioni associate

Richiede l'autorizzazione read_request. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• Intestazioni Forwarded e X-Forwarded-For
• Indirizzo IP remoto

getRequestBody

Restituisce il corpo della richiesta come stringa, se presente, o undefined in caso contrario.

Sintassi

getRequestBody();

Autorizzazioni associate

read_request

getRequestHeader

Restituisce il valore dell'intestazione di richiesta denominata come stringa, se presente, o undefined in caso contrario. Se l'intestazione viene ripetuta, i valori restituiti vengono uniti con ', '.

Esempio

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Sintassi

getRequestHeader(headerName);

Parametri

Autorizzazioni associate

read_request

getRequestMethod

Restituisce il metodo di richiesta, ad esempio 'GET' o 'POST', come stringa.

Esempio

const getRequestMethod = require('getRequestMethod');

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

Sintassi

getRequestMethod();

Autorizzazioni associate

Nessuno.

getRequestPath

Restituisce il percorso della richiesta senza la stringa di query. Ad esempio, se l'URL è '/foo?id=123', viene restituito '/foo'. Rimuove automaticamente il prefisso dell'URL del contenitore del server dal percorso. Ad esempio, se l'URL contenitore del server è https://example.com/analytics e il percorso della richiesta è '/analytics/foo', viene visualizzato'/foo'.

Esempio

const getRequestPath = require('getRequestPath');

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

Sintassi

getRequestPath();

Autorizzazioni associate

read_request

getRequestQueryParameter

Restituisce il valore decodificato del parametro della stringa di query denominato come stringa o undefined se il parametro non è presente. Se il parametro viene ripetuto nella stringa di query, verrà restituito il primo valore visualizzato nella stringa di query.

Esempio

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Sintassi

getRequestQueryParameter(name);

Parametri

Autorizzazioni associate

read_request

getRequestQueryParameters

Restituisce i parametri di query della richiesta HTTP in arrivo come oggetto che mappa i nomi dei parametri di query al valore o ai valori corrispondenti. I nomi e i valori dei parametri vengono decodificati.

Esempio

const getRequestQueryParameters = require('getRequestQueryParameters');

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

Sintassi

getRequestQueryParameters();

Autorizzazioni associate

read_request

getRequestQueryString

Restituisce la query di richiesta come stringa, senza il punto interrogativo iniziale, o una stringa vuota se l'URL della richiesta non include una stringa di query.

Esempio

const getRequestQueryString = require('getRequestQueryString');

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

Sintassi

getRequestQueryString();

Autorizzazioni associate

read_request

getTimestamp

Ritiro. Preferisci getTimestampMillis.

Restituisce un numero che rappresenta l'ora corrente in millisecondi dall'epoch di Unix, come restituito da Date.now().

Sintassi

getTimestamp();

Autorizzazioni associate

Nessuno.

getTimestampMillis

Restituisce un numero che rappresenta l'ora corrente in millisecondi dall'epoch di Unix, come restituito da Date.now().

Sintassi

getTimestampMillis();

Autorizzazioni associate

Nessuno.

getType

Restituisce una stringa che descrive il tipo del valore specificato.

Esempio

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

Sintassi

getType(value);

Parametri

Autorizzazioni associate

Nessuno.

hmacSha256

Calcola una firma codificata utilizzando un codice HMAC (Hash-based Message Authentication Code) con SHA-256. Il valore predefinito è la codifica base64url.

Per utilizzare questa API, imposta la variabile di ambiente SGTM_CREDENTIALS sul server sul percorso di un file di chiavi JSON codificato in UTF-8 con il seguente formato:

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

I valori sono chiavi HMAC con codifica Base64. Il testo JSON non deve iniziare con un indicatore di ordine dei byte.

Esempio

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;

Sintassi

hmacSha256(data, keyId, options)

Parametri

Opzioni

Autorizzazioni associate

use_custom_private_keys

Versione minima dell'immagine

1.0.0

isRequestMpv1

Restituisce true se la richiesta in arrivo è una richiesta Measurement Protocol V1 o false in caso contrario.

Esempio

const isRequestMpv1 = require('isRequestMpv1');

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

Sintassi

isRequestMpv1();

Autorizzazioni associate

Nessuno.

isRequestMpv2

Restituisce true se la richiesta in arrivo è una richiesta Measurement Protocol V2 o false in caso contrario.

Esempio

const isRequestMpv2 = require('isRequestMpv2');

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

Sintassi

isRequestMpv2();

Autorizzazioni associate

Nessuno.

logToConsole

Registra i relativi argomenti nella console.

Questi log sono visibili in Esplora log nella console Google Cloud. Da Esplora log, esegui la query logName =~ "stdout" per visualizzare le voci di log create da questa API.

Esempio

const logToConsole = require('logToConsole');

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

Sintassi

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

Parametri

L'API accetta uno o più argomenti, ciascuno dei quali viene convertito in una stringa, se necessario, e registrato nella console.

Autorizzazioni associate

logging

makeInteger

Converte il valore specificato in un numero (intero).

Sintassi

makeInteger(value);

Parametri

Autorizzazioni associate

Nessuno.

makeNumber

Converte il valore specificato in un numero.

Sintassi

makeNumber(value);

Parametri

Autorizzazioni associate

Nessuno.

makeString

Restituisce il valore specificato come stringa.

Sintassi

makeString(value);

Parametri

Autorizzazioni associate

Nessuno.

makeTableMap

Converte un semplice oggetto tabella con due colonne in un Map. Viene utilizzato per trasformare un campo del modello SIMPLE_TABLE con due colonne in un formato più gestibile.

Ad esempio, questa funzione potrebbe convertire un oggetto tabella:

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

in una mappa:

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

Restituisce un oggetto: le Map coppie chiave-valore convertite sono state aggiunte o null in caso contrario.

Sintassi

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parametri

Autorizzazioni associate

Nessuno.

parseUrl

Restituisce un oggetto contenente tutti i componenti di un determinato URL, in modo simile all'oggetto URL.

Questa API restituirà undefined per qualsiasi URL non valido. Per gli URL con formato corretto, i campi non presenti nella stringa dell'URL avranno un valore di stringa vuota o, nel caso di searchParams, un oggetto vuoto.

L'oggetto restituito avrà i seguenti campi:

{
  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,
}

Esempio

const parseUrl = require('parseUrl');

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

Sintassi

parseUrl(url);

Parametri

Autorizzazioni associate

Nessuno.

returnResponse

Svuota la risposta impostata in precedenza da altri modelli utilizzando le API che modificano la risposta, tra cui setCookie, setPixelResponse, setResponseBody, setResponseHeader e setResponseStatus. Il valore predefinito è un codice di stato HTTP 200, un corpo vuoto e nessuna intestazione.

Ti consigliamo di utilizzare questa API da un modello client.

Sintassi

returnResponse();

Esempio

Vedi l'esempio runContainer.

Autorizzazioni associate

return_response

runContainer

Esegue la logica del contenitore (variabili, attivatori, tag) nell'ambito di un evento. Se questa API viene chiamata durante l'esecuzione del contenitore, il contenitore viene eseguito di nuovo.

I callback onComplete e onStart ricevono una funzione chiamata bindToEvent. Usa bindToEvent per eseguire un'API nel contesto dell'evento. Per maggiori dettagli, consulta l'esempio di addEventCallback.

Ti consigliamo di utilizzare questa API da un modello client.

Esempio

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());

Sintassi

runContainer(event, onComplete, onStart);

Parametri

Autorizzazioni associate

run_container

sendEventToGoogleAnalytics

Invia un singolo evento utilizzando i dati sugli eventi comuni a Google Analytics e restituisce un promessa che si risolve in un oggetto con una chiave location o rifiuta un oggetto con una chiave reason. La destinazione, Google Analytics 4, si basa sull'ID misurazione nei dati sugli eventi.

Il campo location è impostato sull'intestazione location, se presente.

Esempio

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

Sintassi

sendEventToGoogleAnalytics(event);

Parametri

Autorizzazioni associate

Richiede l'autorizzazione send_http. L'autorizzazione deve essere configurata per consentire l'accesso almeno a:

• Consenti domini Google

sendHttpGet

Invia una richiesta GET HTTP all'URL specificato e restituisce un promessa che si risolve con il risultato al termine della richiesta o al verificarsi di un timeout.

Il risultato risolto è un oggetto contenente tre chiavi: statusCode, headers e body. Se la richiesta non va a buon fine (ad es. URL non valido, nessuna route all'host, fallimento della negoziazione SSL e così via), la promessa viene rifiutata con: {reason: 'failed'}. Se l'opzione timeout è stata impostata e la richiesta è scaduta, la promessa verrà rifiutata con: {reason: 'timed_out'}

Esempio

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

Sintassi

sendHttpGet(url[, options]);

Parametri

Opzioni

Autorizzazioni associate

send_http

sendHttpRequest

Effettua una richiesta HTTP all'URL specificato e restituisce una promessa che si risolve con la risposta al termine della richiesta o al verificarsi del timeout.

Il risultato risolto è un oggetto contenente tre chiavi: statusCode, headers e body. Se la richiesta non va a buon fine (ad es. URL non valido, nessuna route all'host, fallimento della negoziazione SSL e così via), la promessa viene rifiutata con: {reason: 'failed'}. Se l'opzione timeout è stata impostata e la richiesta è scaduta, la promessa verrà rifiutata con: {reason: 'timed_out'}

Esempio

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

Sintassi

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

Parametri

Opzioni

Autorizzazioni associate

send_http

sendPixelFromBrowser

Invia un comando al browser per caricare l'URL fornito come tag <img>. Questo protocollo di comandi è supportato nel tag Google per GA4 e nei tag web Google Analytics: evento GA. Devi configurare l'URL del contenitore del server. Per maggiori dettagli, consulta le istruzioni.

Questa API restituisce false se la richiesta in arrivo non supporta il protocollo di comando o se la risposta è già stata svuotata. In caso contrario, questa API restituisce true.

Esempio:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Sintassi

sendPixelFromBrowser(url)

Parametri

Autorizzazioni associate

send_pixel_from_browser

setCookie

Imposta o elimina un cookie con le opzioni specificate.

Per eliminare un cookie, devi impostare un cookie con lo stesso percorso e dominio con cui è stato creato e assegnargli un valore expires nel passato, ad esempio "Thu, 01 Jan 1970 00:00:00 GMT".

Tieni presente che returnResponse deve essere chiamato affinché la risposta venga inviata al client.

Esempio

const setCookie = require('setCookie');

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

Sintassi

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

Parametri

Opzioni

• domain: l'host a cui verrà inviato il cookie. Se impostato sul valore speciale "auto", l'host verrà calcolato automaticamente utilizzando la seguente strategia:

  • Dominio eTLD+1 dell'intestazione Forwarded, se presente.
  • Dominio eTLD+1 dell'intestazione X-Forwarded-Host, se presente.
  • eTLD+1 dell'intestazione Host.

• expires: la durata massima del cookie. Deve essere una stringa di data in formato UTC, ad esempio "Sab, 26 ott 1985 08:21:00 GMT". Se sono impostati sia expires che max-age, max-age ha la precedenza.

• httpOnly: impedisce a JavaScript di accedere al cookie se true.

• max-age: il numero di secondi che rimangono prima della scadenza del cookie. Un numero zero o negativo farà scadere immediatamente il cookie. Se sono impostati sia expires che max-age, max-age ha la precedenza.

• path: un percorso che deve esistere nell'URL richiesto, altrimenti il browser non invierà l'intestazione Cookie.

• secure: se impostato su true, il cookie viene inviato al server solo quando viene effettuata una richiesta da un endpoint https:.

• sameSite: verifica che un cookie non debba essere inviato con richieste cross-origin. Deve essere 'strict', 'lax' o 'none'.

Autorizzazioni associate

set_cookie

setPixelResponse

Imposta il corpo della risposta su una GIF 1x1, imposta l'intestazione Content-Type su "image/gif", imposta le intestazioni di memorizzazione nella cache in modo che gli user agent non memorizzino nella cache la risposta e imposta lo stato della risposta su 200.

Tieni presente che returnResponse deve essere chiamato affinché la risposta venga inviata al client.

Sintassi

setPixelResponse();

Autorizzazioni associate

Richiede l'autorizzazione access_response. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• headers - Deve consentire le seguenti chiavi
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

setResponseBody

Imposta il corpo della risposta sull'argomento.

Tieni presente che returnResponse deve essere chiamato affinché la risposta venga inviata al client.

Sintassi

setResponseBody(body[, encoding]);

Parametri

Autorizzazioni associate

Richiede l'autorizzazione access_response. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• body

setResponseHeader

Imposta un'intestazione nella risposta che verrà restituita. Se un'intestazione con questo nome (senza distinzione tra maiuscole e minuscole) è stata impostata in precedenza da questa API, la chiamata successiva sovrascriverà o cancellerà il valore impostato dall'autore della chiamata precedente.

Tieni presente che returnResponse deve essere chiamato affinché la risposta venga inviata al client.

Sintassi

setResponseHeader(name, value);

Parametri

Autorizzazioni associate

Richiede l'autorizzazione access_response. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• headers

setResponseStatus

Imposta il codice di stato HTTP della risposta che verrà restituita.

Tieni presente che returnResponse deve essere chiamato affinché la risposta venga inviata al client.

Sintassi

setResponseStatus(statusCode);

Parametri

Autorizzazioni associate

Richiede l'autorizzazione access_response. L'autorizzazione deve essere configurata in modo da consentire l'accesso ad almeno:

• status

sha256

Calcola il digest SHA-256 dell'input e richiama un callback con il digest codificato in base64, a meno che l'oggetto options non specifichi una codifica di output diversa.

La firma e il comportamento di questa API corrispondono a quelli dell'API sha256 per i contenitori web. Tuttavia, i modelli personalizzati nei contenitori del server devono utilizzare l'API sha256Sync per un codice più semplice.

Esempio

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

Sintassi

sha256(input, onSuccess, options = undefined);

Parametri

Autorizzazioni associate

Nessuno.

sha256Sync

Calcola e restituisce il digest SHA-256 dell'input, codificato in base64, a meno che l'oggetto options non specifichi una codifica di output diversa.

Esempio

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

Sintassi

sha256Sync(input, options = undefined);

Parametri

Autorizzazioni associate

Nessuno.

templateDataStorage

Restituisce un oggetto con metodi per accedere allo spazio di archiviazione dei dati dei modelli. Lo spazio di archiviazione dei dati dei modelli consente di condividere i dati tra le esecuzioni di un singolo modello. I dati archiviati nello spazio di archiviazione dei dati dei modelli vengono mantenuti sul server su cui è in esecuzione il container. Nella maggior parte dei casi sono presenti più server che eseguono il contenitore, pertanto l'archiviazione dei dati nello spazio di archiviazione dei dati dei modelli non garantisce che ogni richiesta successiva avrà accesso ai dati.

Il termine "data" nel nome "templateDataStorage" si riferisce al fatto che solo tipi di dati semplici e non funzionali possono essere archiviati utilizzando questa API. Eventuali funzioni o riferimenti a funzioni passati all'API verranno archiviati come null.

Sintassi

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();

Esempio

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

Autorizzazioni associate

access_template_storage

testRegex

Testa una stringa rispetto a una regex creata tramite l'API createRegex. Restituisce true se l'espressione regolare corrisponde. In caso contrario, restituisce false.

Una regex creata con il flag globale è stateful. Per maggiori dettagli, consulta la documentazione di RegExp.

Esempio

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

Sintassi

testRegex(regex, string);

Parametri

Autorizzazioni associate

Nessuno.

toBase64

Codifica una stringa in base64 o base64url. Il valore predefinito è la codifica Base64.

Sintassi

toBase64(input, options);

Parametri

Opzioni

Esempio

const toBase64 = require('toBase64');

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

Autorizzazioni associate

Nessuno.

BigQuery

Restituisce un oggetto che fornisce le funzioni BigQuery.

La funzione BigQuery.insert consente di scrivere dati in una tabella BigQuery. Restituisce un promise che si risolve in caso di inserimento riuscito o viene rifiutato in caso di errore.

Quando l'inserimento riesce, la promessa viene risolta senza argomenti.

Se l'inserimento non va a buon fine, la promessa viene rifiutata con un elenco di oggetti contenenti il motivo dell'errore e, eventualmente, un oggetto riga. È possibile che una parte della richiesta venga completata correttamente, mentre altre no. In questo caso, la promessa viene rifiutata con un elenco di errori per ogni riga con un oggetto riga per distinguere le righe inserite (vedi Esempi di errori di seguito). Per ulteriori informazioni, consulta la documentazione di BigQuery sui messaggi di errore.

Sintassi

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

Parametri

Opzioni

Esempi di errori

Un errore di modulo non trovato indica che nel contenitore del server è probabilmente in esecuzione una versione precedente della nostra immagine che non includeva ancora il modulo BigQuery. Esegui il redeployment del contenitore del server con le stesse impostazioni utilizzando il nostro script di deployment. Il modulo verrà incluso automaticamente al termine dell'operazione.

Un errore di mancata inserimento in genere ha un oggetto errore con una chiave reason:

[{reason: 'invalid'}]

Un errore di inserzione può contenere più oggetti errore con un array errors e un oggetto row. Di seguito è riportato un esempio di risposta di errore dall'inserimento di due righe in cui solo una riga presenta un errore:

[
  {
    "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
    }
  }
]

Esempio

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

Autorizzazioni associate

access_bigquery

Firestore

Restituisce un oggetto che fornisce le funzioni di Firestore.

Questa API supporta solo Firestore in modalità Native, non Firestore in modalità Datastore. Inoltre, l'API supporta solo l'utilizzo del database predefinito.

Firestore.read

La funzione Firestore.read legge i dati da un documento Firestore e restituisce una promessa che si risolve in un oggetto contenente due chiavi: id e data. Se il documento non esiste, la promessa viene rifiutata con un oggetto contenente una chiave reason uguale a not_found.

Sintassi

Firestore.read(path[, options]);

Parametri

Opzioni

Esempio

const Firestore = require('Firestore');

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

Firestore.write

La funzione Firestore.write scrive i dati in un documento o in una raccolta Firestore. Se il percorso è relativo a una raccolta, verrà creato un documento con un ID generato in modo casuale. Se il percorso è relativo a un documento e non esiste, verrà creato. Questa API restituisce una promessa che risolve l'ID del documento aggiunto o modificato. Se viene utilizzata l'opzione di transazione, l'API restituisce comunque una promessa, ma non conterrà l'ID poiché le scritture vengono raggruppate.

Sintassi

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

Parametri

Opzioni

Esempio

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 funzione Firestore.query esegue query sulla raccolta specificata e restituisce una promessa che risolve in un array di documenti Firestore corrispondenti alle condizioni di query. L'oggetto del documento Firestore è lo stesso elencato sopra in Firestore.read. Se non esistono documenti corrispondenti alle condizioni della query, la promessa restituita risolverà in un array vuoto.

Sintassi

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

Parametri

Opzioni

Esempio

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 funzione Firestore.runTransaction consente all'utente di leggere e scrivere in modo atomico da Firestore. Se si verifica una scrittura simultanea o un altro conflitto di transazioni, verrà riprovato fino a due volte. Se non va a buon fine dopo tre tentativi totali, l'API lo rifiuterà con un errore. Questa API restituisce una promessa che risolve in un array di ID documento, per ogni operazione di scrittura, se la transazione è andata a buon fine e viene rifiutata con l'errore se non va a buon fine.

Sintassi

Firestore.runTransaction(callback[, options]);

Parametri

Opzioni

Esempio

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

Esempio di errore

Gli errori disponibili in ogni funzione Firestore verranno rifiutati con un oggetto contenente una chiave reason:

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

I motivi di errore possono includere, a titolo esemplificativo, i codici di errore dell'API REST Firestore.

Autorizzazioni associate

access_firestore

JSON

Restituisce un oggetto che fornisce funzioni JSON.

La funzione parse() analizza una stringa JSON per costruire il valore o l'oggetto descritto dalla stringa. Se il valore non può essere analizzato (ad es. JSON con formato non corretto), la funzione restituirà undefined. Se il valore inserito non è una stringa, questo verrà forzato in una stringa.

La funzione stringify() converte l'input in una stringa JSON. Se il valore non può essere analizzato (ad es. l'oggetto contiene un ciclo), il metodo restituisce undefined.

Esempio

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

Sintassi

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

Autorizzazioni associate

Nessuno.

Math

Un oggetto che fornisce funzioni Math.

Sintassi

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

Parametri

I parametri delle funzioni matematiche vengono convertiti in numeri.

Autorizzazioni associate

Nessuno.

Messages

Le seguenti API collaborano per consentire il passaggio di messaggi tra diverse parti di un contenitore.

addMessageListener

Aggiunge una funzione che ascolta un messaggio di un determinato tipo. Quando un messaggio di questo tipo viene inviato utilizzando l'API sendMessage (in genere da un tag), il callback verrà eseguito in modo sincrono. Il callback viene eseguito con due parametri:

1. messageType:string
2. message:Object

Se il callout viene aggiunto in un client, riceverà i messaggi in tutti gli eventi creati dal client. Se il callback deve ricevere messaggi solo da un determinato evento, associa questa API all'evento utilizzando bindToEvent nella funzione onStart dell'API runContainer. Guarda l'esempio.

Sintassi

const addMessageListener = require('addMessageListener');

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

Parametri

Esempio

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

Autorizzazioni associate

Richiede l'autorizzazione use_message. L'autorizzazione deve essere configurata in modo da consentire almeno:

• Un tipo di messaggio con Usage di listen o listen_and_send.

hasMessageListener

Restituisce true se è stato aggiunto un ascoltatore di messaggi per il tipo di messaggio specificato. Restituisce false altrimenti.

Sintassi

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Autorizzazioni associate

Nessuno.

sendMessage

Invia un messaggio del tipo specificato a un ascoltatore registrato. Questo può essere utilizzato per inviare messaggi da un tag al client che ha eseguito il contenitore.

Sintassi

const sendMessage = require('sendMessage');

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

Parametri

Autorizzazioni associate

Richiede l'autorizzazione use_message. L'autorizzazione deve essere configurata in modo da consentire almeno:

• Un tipo di messaggio con Usage di listen_and_send o send.

Object

Restituisce un oggetto che fornisce i metodi Object.

Il metodo keys() fornisce il comportamento della libreria standard Object.keys(). Restituisce un array dei nomi delle proprietà enumerabili di un determinato oggetto nello stesso ordine di un ciclo for...in.... Se il valore inserito non è un oggetto, verrà forzato in un oggetto.

Il metodo values() fornisce il comportamento di Object.values() della libreria standard. Restituisce un array dei valori delle proprietà enumerabili di un determinato oggetto nello stesso ordine di un ciclo for...in.... Se il valore inserito non è un oggetto, verrà forzato in un oggetto.

Il metodo entries() fornisce il comportamento di Object.entries() della libreria standard. Restituisce un array di coppie [key, value] della proprietà enumerabile di un determinato oggetto nello stesso ordine di un ciclo for...in.... Se il valore inserito non è un oggetto, verrà forzato in un oggetto.

Il metodo freeze() fornisce il comportamento Object.freeze() della libreria standard. Un oggetto bloccato non può più essere modificato. Il blocco di un oggetto impedisce di aggiungervi nuove proprietà, di rimuoverne quelle esistenti e di modificare i valori delle proprietà esistenti. freeze() restituisce lo stesso oggetto passato. Un argomento primitivo o nullo verrà trattato come se fosse un oggetto bloccato e verrà restituito.

Il metodo delete() fornisce il comportamento dell'operatore delete della libreria standard. Rimuove la chiave specificata dall'oggetto, a meno che non sia bloccato. Come l'operatore di eliminazione della libreria standard, restituisce true se il primo valore di input (objectInput) è un oggetto non congelato anche se il secondo valore di input (keyToDelete) specifica una chiave inesistente. Restituisce false in tutti gli altri casi. Tuttavia, si differenzia dall'operatore di eliminazione della libreria standard per i seguenti aspetti:

• keyToDelete non può essere una stringa delimitata da punti che specifica una chiave nidificata.
• delete() non può essere utilizzato per rimuovere elementi da un array.
• delete() non può essere utilizzato per rimuovere proprietà dall'ambito globale.

Sintassi

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

Parametri

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Esempio

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

Restituisce un oggetto che fornisce metodi per interagire con le promesse.

Le promesse sono funzionalmente equivalenti alle promesse JavaScript. Ogni istanza ha tre metodi che restituiscono una promessa che consente ulteriori azioni quando una promessa viene risolta:

• .then(): gestisce le richieste risolte e rifiutate. Richiede due callback come parametri: uno per il caso di successo e uno per il caso di fallimento.
• .catch(): gestisce solo le richieste rifiutate. Accetta un callback come parametro.
• .finally(): consente di eseguire il codice indipendentemente dal fatto che la promessa sia stata risolta o rifiutata. Accetta un callback come parametro che viene invocato senza argomento.

Una variabile che restituisce una promessa è uguale al valore risolto della promessa o false se la promessa viene rifiutata.

Esempio

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

Restituisce una promessa che:

• si risolve quando tutti gli input sono stati risolti oppure
• rifiuta quando uno degli input viene rifiutato

Sintassi

Promise.all(inputs);

Parametri

Esempio

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

Autorizzazioni associate

Nessuno.

Promise.create

Crea una promessa funzionalmente equivalente a una promessa JavaScript.

Sintassi

Promise.create(resolver);

Parametri

Esempio

const Promise = require('Promise');

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

Autorizzazioni associate

Nessuno.

Testare le API

Queste API funzionano con i test JavaScript in sandbox per creare test per i modelli personalizzati in Google Tag Manager. Queste API di test non richiedono un'istruzione require(). [Scopri di più sui test dei modelli personalizzati].

assertApi

Restituisce un oggetto matcher che può essere utilizzato per fare affermazioni in modo fluido sulla data API.

Sintassi

assertApi(apiName)

Parametri

Matcher

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

Esempi

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

assertThat

L'API assertThat è modellata sulla libreria [Truth] di Google. Restituisce un oggetto che può essere utilizzato per fare affermazioni fluide sul valore di un soggetto. Un errore di asserzione interrompe immediatamente il test e lo contrassegna come non riuscito. Tuttavia, un errore in un test non influisce sugli altri casi di test.

Sintassi

assertThat(actual, opt_message)

Parametri

Matcher

Esempi

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

Il test corrente non va a buon fine immediatamente e viene stampato il messaggio specificato, se fornito.

Sintassi

fail(opt_message);

Parametri

Esempio

fail('This test has failed.');

mock

L'API mock ti consente di ignorare il comportamento delle API in sandbox. L'API simulata è sicura da utilizzare nel codice del modello, ma è operativa solo in modalità di test. I mock vengono reimpostati prima dell'esecuzione di ogni test.

Sintassi

mock(apiName, returnValue);

Parametri

Esempi

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

mockObject

L'API mockObject ti consente di ignorare il comportamento delle API in sandbox che retiranno un oggetto. L'API è sicura da utilizzare nel codice del modello, ma è operativa solo in modalità di test. I mock vengono reimpostati prima dell'esecuzione di ogni test.

Sintassi

mockObject(apiName, objectMock);

Parametri