APIs de etiquetado del servidor

En este documento, se describen las APIs para el etiquetado del servidor.

addEventCallback

Registra una función de devolución de llamada que se invocará al final de un evento. La devolución de llamada se invocará cuando se hayan ejecutado todas las etiquetas del evento. La devolución de llamada recibe dos valores: el ID del contenedor que invoca la función y un objeto que contiene información sobre el evento.

Cuando se usa esta API en una etiqueta, se asocia al evento actual. Cuando se usa esta API en un cliente, debe vincularse a un evento específico con la función bindToEvent de la API de runContainer. Consulta el ejemplo para obtener más detalles.

Sintaxis

const addEventCallback = require('addEventCallback');

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

Parámetros

El objeto eventData contiene los siguientes datos:

Ejemplo

En un cliente:

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

En una etiqueta:

const addEventCallback = require('addEventCallback');

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

Permisos asociados

read_event_metadata

callLater

Programa una llamada a una función para que se produzca de forma asíncrona. Se llamará a la función después de que se muestre el código actual. Esto equivale a setTimeout(<function>, 0).

Ejemplo

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

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

Sintaxis

callLater(function)

Parámetros

Permisos asociados

Ninguno

claimRequest

Usa esta API en un cliente para reclamar la solicitud. Una vez que se reclama una solicitud, el contenedor no ejecuta clientes adicionales.

Esta API arroja una excepción si se la llama en una etiqueta o variable. Esta API arroja una excepción si se la llama después de que el cliente devuelve un valor (p.ej., si se la llama en una devolución de llamada asíncrona, como en callLater o en la función runContainer onComplete).

Un cliente debe reclamar la solicitud con esta API antes de llamar a la API de runContainer.

Ejemplo

const claimRequest = require('claimRequest');

claimRequest();

Sintaxis

claimRequest();

Permisos asociados

Ninguno

computeEffectiveTldPlusOne

Devuelve el dominio de nivel superior efectivo más 1 (eTLD+1) del dominio o la URL proporcionados. El eTLD+1 se calcula evaluando el dominio según las reglas de la Lista de sufijos públicos. Por lo general, el eTLD + 1 es el dominio de nivel más alto en el que puedes establecer una cookie.

Si el argumento es nulo o indefinido, se devuelve el valor del argumento sin modificar. De lo contrario, el argumento se coerciona a una cadena. Si el argumento no es un dominio o una URL válidos, se devuelve una cadena vacía. Si el servidor no puede recuperar la lista de sufijos públicos, el valor del argumento se devuelve sin modificar.

Ejemplo

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

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

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

Sintaxis

computeEffectiveTldPlusOne(domainOrUrl);

Parámetros

Permisos asociados

Ninguno

createRegex

Crea una instancia de regex nueva y la devuelve encapsulada en un objeto. No puedes acceder a la expresión regular directamente. Sin embargo, puedes pasarla a las APIs de testRegex, String.replace(), String.match() y String.search().

Devuelve null si la expresión regular no es válida o si Re2 no está disponible en el servidor.

Esta API usa una implementación de Re2. La imagen de Docker del servidor debe ser de la versión 2.0.0 o posterior.

Ejemplo

const createRegex = require('createRegex');

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

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

Sintaxis

createRegex(pattern, flags);

Parámetros

Permisos asociados

Ninguno

Versión mínima de la imagen

2.0.0

decodeUri

Decodifica los caracteres codificados en el URI proporcionado. Devuelve una cadena que representa el URI decodificado. Devuelve undefined cuando se proporciona una entrada no válida.

Ejemplo

const decodeUri = require('decodeUri');

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

Sintaxis

decodeUri(encoded_uri);

Parámetros

Permisos asociados

Ninguno

decodeUriComponent

Decodifica los caracteres codificados en el componente de URI proporcionado. Devuelve una cadena que representa el componente de URI decodificado. Devuelve undefined cuando se proporciona una entrada no válida.

Ejemplo

const decodeUriComponent = require('decodeUriComponent');

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

Sintaxis

decodeUriComponent(encoded_uri_component);

Parámetros

Permisos asociados

Ninguno

encodeUri

Devuelve un identificador uniforme de recursos (URI) codificado con caracteres especiales de escape. Devuelve una cadena que representa la cadena proporcionada codificada como un URI.

Ejemplo

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

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

Sintaxis

encodeUri(uri);

Parámetros

Permisos asociados

Ninguno

encodeUriComponent

Devuelve un identificador uniforme de recursos (URI) codificado con caracteres especiales de escape. Devuelve una cadena que representa la cadena proporcionada codificada como un URI.

Ejemplo

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

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

Sintaxis

encodeUriComponent(str);

Parámetros

Permisos asociados

Ninguno

extractEventsFromMpv1

Traduce una solicitud entrante de Measurement Protocol V1 en una lista de eventos en formato de esquema unificado. Devuelve la lista de eventos extraídos. Se arroja un error si la solicitud no tiene el formato correcto.

Ejemplo

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

Sintaxis

extractEventsFromMpv1();

Permisos asociados

Requiere el permiso read_request. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• body
• query parameters

extractEventsFromMpv2

Traduce una solicitud entrante de Measurement Protocol v2 en una lista de eventos en formato de esquema unificado. Devuelve la lista de eventos extraídos. Se arroja un error si la solicitud no tiene el formato correcto.

Ejemplo

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

Sintaxis

extractEventsFromMpv2();

Permisos asociados

Requiere el permiso read_request. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• body
• query parameters

fromBase64

Decodifica una cadena codificada en Base64. Muestra undefined si la entrada no es válida.

Sintaxis

fromBase64(base64EncodedString);

Parámetros

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno

generateRandom

Devuelve un número (entero) aleatorio dentro del rango determinado.

Ejemplo

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Sintaxis

generateRandom(min, max);

Parámetros

Permisos asociados

Ninguno

getAllEventData

Devuelve una copia de los datos del evento.

Sintaxis

getAllEventData();

Permisos asociados

read_event_data

getClientName

Devuelve una cadena que contiene el nombre del cliente actual.

Sintaxis

getClientName();

Permisos asociados

read_container_data

getContainerVersion

Devuelve un objeto que contiene datos sobre el contenedor actual. El objeto devuelto tendrá los siguientes campos:

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

Ejemplo

const getContainerVersion = require('getContainerVersion');

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

Sintaxis

getContainerVersion();

Permisos asociados

read_container_data

getCookieValues

Devuelve un array que contiene los valores de todas las cookies con el nombre determinado.

Ejemplo

const getCookieValues = require('getCookieValues');

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

Sintaxis

getCookieValues(name[, noDecode]);

Parámetros

Permisos asociados

get_cookies

getEventData

Devuelve una copia del valor en la ruta de acceso determinada en los datos del evento. Devuelve undefined si no hay datos del evento o si no hay ningún valor en la ruta de acceso proporcionada.

Ejemplo

const getEventData = require('getEventData');

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

Parámetros

Sintaxis

getEventData(keyPath);

Permisos asociados

read_event_data

getGoogleAuth

Devuelve un objeto de autorización que, cuando se usa con sendHttpGet o sendHttpRequest, incluirá un encabezado de autorización para las APIs de Google Cloud. Esta API usa credenciales predeterminadas de la aplicación para encontrar credenciales automáticamente desde el entorno del servidor.

Ejemplo

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

Sintaxis

getGoogleAuth(scopes);

Parámetros

Permisos asociados

Requiere el permiso use_google_credentials. El permiso debe configurarse con uno o más permisos permitidos.

getGoogleScript

Recupera un recurso de un conjunto predeterminado de secuencias de comandos de Google y devuelve una promesa con la secuencia de comandos y los metadatos de almacenamiento en caché asociados.

La promesa se resolverá en un objeto que contiene dos claves: script y metadata. Si la solicitud falla, la promesa se rechazará con una clave reason.

El objeto metadata contendrá los siguientes metadatos de almacenamiento en caché según los encabezados de respuesta del recurso. Cada campo solo estará presente si el encabezado correspondiente está presente en la respuesta del recurso.

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

Ejemplo

const getGoogleScript = require('getGoogleScript');

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

Sintaxis

getGoogleScript(script[, options]);

Parámetros

Opciones

Se ignoran las claves de opciones no reconocidas.

Permisos asociados

Requiere el permiso send_http. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• Permitir Google Domains

getRemoteAddress

Devuelve una representación de cadena de la dirección IP desde la que se originó la solicitud, p.ej., 12.345.67.890 para IPv4 o 2001:0db8:85a3:0:0:8a2e:0370:7334 para IPv6, leyendo los encabezados de solicitud, como Forwarded y X-Forwarded-For. Nota: Esta API hace su mejor esfuerzo para descubrir la IP de origen, pero no puede garantizar que el resultado sea preciso.

Sintaxis

getRemoteAddress();

Permisos asociados

Requiere el permiso read_request. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• Encabezados Forwarded y X-Forwarded-For
• Dirección IP remota

getRequestBody

Devuelve el cuerpo de la solicitud como una cadena, si está presente, o undefined de lo contrario.

Sintaxis

getRequestBody();

Permisos asociados

read_request

getRequestHeader

Devuelve el valor del encabezado de solicitud con nombre como una cadena, si está presente, o undefined de lo contrario. Si se repite el encabezado, los valores devueltos se unen con ', '.

Ejemplo

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Sintaxis

getRequestHeader(headerName);

Parámetros

Permisos asociados

read_request

getRequestMethod

Devuelve el método de solicitud, p.ej., 'GET' o 'POST', como una cadena.

Ejemplo

const getRequestMethod = require('getRequestMethod');

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

Sintaxis

getRequestMethod();

Permisos asociados

Ninguno

getRequestPath

Devuelve la ruta de la solicitud sin la cadena de consulta. Por ejemplo, si la URL es '/foo?id=123', se devuelve '/foo'. Quita automáticamente el prefijo de la URL del contenedor de servidor de la ruta. Por ejemplo, si la URL del contenedor del servidor es https://example.com/analytics y la ruta de la solicitud es '/analytics/foo', se devuelve '/foo'.

Ejemplo

const getRequestPath = require('getRequestPath');

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

Sintaxis

getRequestPath();

Permisos asociados

read_request

getRequestQueryParameter

Devuelve el valor decodificado del parámetro de cadena de consulta con nombre como una cadena o undefined si el parámetro no está presente. Si el parámetro se repite en la cadena de consulta, se devolverá el primer valor que aparezca en la cadena de consulta.

Ejemplo

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Sintaxis

getRequestQueryParameter(name);

Parámetros

Permisos asociados

read_request

getRequestQueryParameters

Devuelve los parámetros de búsqueda de la solicitud HTTP entrante como un objeto que asigna los nombres de los parámetros de búsqueda a los valores correspondientes. Los nombres y valores de los parámetros se decodifican.

Ejemplo

const getRequestQueryParameters = require('getRequestQueryParameters');

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

Sintaxis

getRequestQueryParameters();

Permisos asociados

read_request

getRequestQueryString

Devuelve la consulta de la solicitud como una cadena, sin el signo de interrogación inicial, o una cadena vacía si la URL de la solicitud no incluye una cadena de consulta.

Ejemplo

const getRequestQueryString = require('getRequestQueryString');

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

Sintaxis

getRequestQueryString();

Permisos asociados

read_request

getTimestamp

Obsoleto. Es preferible usar getTimestampMillis.

Devuelve un número que representa la hora actual en milisegundos desde la época de Unix, como lo devuelve Date.now().

Sintaxis

getTimestamp();

Permisos asociados

Ninguno

getTimestampMillis

Devuelve un número que representa la hora actual en milisegundos desde la época de Unix, como lo devuelve Date.now().

Sintaxis

getTimestampMillis();

Permisos asociados

Ninguno

getType

Devuelve una cadena que describe el tipo del valor determinado.

Ejemplo

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

Sintaxis

getType(value);

Parámetros

Permisos asociados

Ninguno

hmacSha256

Calcula una firma codificada con el código de autenticación de mensajes basado en hash (HMAC) con SHA-256. La configuración predeterminada es la codificación base64url.

Para usar esta API, configura la variable de entorno SGTM_CREDENTIALS en el servidor con la ruta de acceso a un archivo de claves JSON codificado en UTF-8 con el siguiente formato:

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

Los valores son claves HMAC codificadas en base64. El texto JSON no debe comenzar con una marca de orden de bytes.

Ejemplo

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;

Sintaxis

hmacSha256(data, keyId, options)

Parámetros

Opciones

Permisos asociados

use_custom_private_keys

Versión mínima de la imagen

1.0.0

isRequestMpv1

Devuelve true si la solicitud entrante es una solicitud del Protocolo de medición, versión 1, o false en caso contrario.

Ejemplo

const isRequestMpv1 = require('isRequestMpv1');

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

Sintaxis

isRequestMpv1();

Permisos asociados

Ninguno

isRequestMpv2

Devuelve true si la solicitud entrante es una solicitud del Protocolo de medición, versión 2, o false en caso contrario.

Ejemplo

const isRequestMpv2 = require('isRequestMpv2');

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

Sintaxis

isRequestMpv2();

Permisos asociados

Ninguno

logToConsole

Registra sus argumentos en la consola.

Estos registros se pueden ver en el Explorador de registros de la consola de Google Cloud. En el Explorador de registros, ejecuta la consulta logName =~ "stdout" para ver las entradas de registro creadas por esta API.

Ejemplo

const logToConsole = require('logToConsole');

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

Sintaxis

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

Parámetros

La API toma uno o más argumentos, cada uno de los cuales se convierte en una cadena, si es necesario, y se registra en la consola.

Permisos asociados

logging

makeInteger

Convierte el valor proporcionado en un número (número entero).

Sintaxis

makeInteger(value);

Parámetros

Permisos asociados

Ninguno

makeNumber

Convierte el valor proporcionado en un número.

Sintaxis

makeNumber(value);

Parámetros

Permisos asociados

Ninguno

makeString

Devuelve el valor determinado como una cadena.

Sintaxis

makeString(value);

Parámetros

Permisos asociados

Ninguno

makeTableMap

Convierte un objeto de tabla simple con dos columnas en un Map. Se usa para cambiar un campo de plantilla SIMPLE_TABLE con dos columnas a un formato más fácil de administrar.

Por ejemplo, esta función podría convertir un objeto de tabla:

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

en un mapa:

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

Devuelve un Object: Se le agregó el Map convertido de pares clave-valor o null en otros casos.

Sintaxis

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parámetros

Permisos asociados

Ninguno

parseUrl

Devuelve un objeto que contiene todas las partes componentes de una URL determinada, de forma similar al objeto URL.

Esta API devolverá undefined para cualquier URL con formato incorrecto. En el caso de las URLs con el formato correcto, los campos que no estén presentes en la cadena de URL tendrán el valor de una cadena vacía o, en el caso de searchParams, un objeto vacío.

El objeto devuelto tendrá los siguientes campos:

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

Ejemplo

const parseUrl = require('parseUrl');

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

Sintaxis

parseUrl(url);

Parámetros

Permisos asociados

Ninguno

returnResponse

Descarga la respuesta que se estableció previamente con otras plantillas a través de las APIs que modifican la respuesta, incluidas setCookie, setPixelResponse, setResponseBody, setResponseHeader y setResponseStatus. De forma predeterminada, se establece en un código de estado HTTP 200, un cuerpo vacío y sin encabezados.

Se recomienda usar esta API desde una plantilla de cliente.

Sintaxis

returnResponse();

Ejemplo

Consulta el ejemplo de runContainer.

Permisos asociados

return_response

runContainer

Ejecuta la lógica del contenedor (variables, activadores, etiquetas) en el alcance de un evento. Si se llama a esta API durante la ejecución del contenedor, el contenedor se vuelve a ejecutar.

Las devoluciones de llamada onComplete y onStart reciben una función llamada bindToEvent. Usa bindToEvent para ejecutar una API en el contexto del evento. Consulta el ejemplo de addEventCallback para obtener más detalles.

Se recomienda usar esta API desde una plantilla de cliente.

Ejemplo

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

Sintaxis

runContainer(event, onComplete, onStart);

Parámetros

Permisos asociados

run_container

sendEventToGoogleAnalytics

Envía un solo evento con Datos de eventos comunes a Google Analytics y devuelve una promesa que se resuelve en un objeto con una clave location o se rechaza en un objeto con una clave reason. El destino, Google Analytics 4, se basa en el ID de medición de los datos del evento.

El campo location se establece en el encabezado location, si está presente.

Ejemplo

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

Sintaxis

sendEventToGoogleAnalytics(event);

Parámetros

Permisos asociados

Requiere el permiso send_http. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• Permitir Google Domains

sendHttpGet

Realiza una solicitud HTTP GET a la URL especificada y devuelve una promesa que se resuelve con el resultado una vez que se completa la solicitud o se agota el tiempo de espera.

El resultado resuelto es un objeto que contiene tres claves: statusCode, headers y body. Si la solicitud falló (p.ej., URL no válida, no hay ruta al host, falla en la negociación de SSL, etc.), la promesa se rechazará con {reason: 'failed'}. Si se configuró la opción timeout y se agotó el tiempo de espera de la solicitud, la promesa se rechazará con: {reason: 'timed_out'}

Ejemplo

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

Sintaxis

sendHttpGet(url[, options]);

Parámetros

Opciones

Permisos asociados

send_http

sendHttpRequest

Realiza una solicitud HTTP a la URL especificada y devuelve una promesa que se resuelve con la respuesta una vez que se completa la solicitud o se agota el tiempo de espera.

El resultado resuelto es un objeto que contiene tres claves: statusCode, headers y body. Si la solicitud falló (p.ej., URL no válida, no hay ruta al host, falla en la negociación de SSL, etc.), la promesa se rechazará con {reason: 'failed'}. Si se configuró la opción timeout y se agotó el tiempo de espera de la solicitud, la promesa se rechazará con: {reason: 'timed_out'}

Ejemplo

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

Sintaxis

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

Parámetros

Opciones

Permisos asociados

send_http

sendPixelFromBrowser

Envía un comando al navegador para cargar la URL proporcionada como una etiqueta <img>. Este protocolo de comandos se admite en la etiqueta de Google para GA4 y en las etiquetas web Google Analytics: Evento de GA. Debes configurar la URL del contenedor del servidor. Consulta las instrucciones para obtener más detalles.

Esta API devuelve false si la solicitud entrante no admite el protocolo de comandos o si la respuesta ya se vació. De lo contrario, esta API devuelve true.

Ejemplo:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Sintaxis

sendPixelFromBrowser(url)

Parámetros

Permisos asociados

send_pixel_from_browser

setCookie

Establece o borra una cookie con las opciones especificadas.

Para borrar una cookie, se debe establecer una cookie con la misma ruta de acceso y el mismo dominio con los que se creó la cookie, y asignarle un valor de vencimiento que esté en el pasado, p.ej., "Thu, 01 Jan 1970 00:00:00 GMT".

Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de vuelta al cliente.

Ejemplo

const setCookie = require('setCookie');

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

Sintaxis

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

Parámetros

Opciones

• domain: Es el host al que se enviará la cookie. Si se establece en el valor especial "auto", el host se calculará automáticamente con la siguiente estrategia:

  • eTLD+1 del encabezado Forwarded, si está presente.
  • eTLD+1 del encabezado X-Forwarded-Host, si está presente.
  • eTLD+1 del encabezado Host

• expires: Es la vida útil máxima de la cookie. Debe ser una cadena de fecha con formato UTC, p. ej., "sáb., 26 de oct. de 1985, 08:21:00 GMT". Si se configuran expires y max-age, max-age tiene prioridad.

• httpOnly: Prohíbe que JavaScript acceda a la cookie si true.

• max-age: Cantidad de segundos hasta que vence la cookie. Si se ingresa un número cero o negativo, la cookie vencerá de inmediato. Si se configuran expires y max-age, max-age tiene prioridad.

• ruta: Es una ruta de acceso que debe existir en la URL solicitada; de lo contrario, el navegador no enviará el encabezado de Cookie.

• secure: Si se establece en true, la cookie solo se envía al servidor cuando se realiza una solicitud desde un extremo https:.

• sameSite: Afirma que no se debe enviar una cookie con solicitudes de origen cruzado. Debe ser 'strict', 'lax' o 'none'.

Permisos asociados

set_cookie

setPixelResponse

Establece el cuerpo de la respuesta en un GIF de 1 x 1, establece el encabezado Content-Type en "image/gif", establece encabezados de almacenamiento en caché de modo que los agentes de usuario no almacenen en caché la respuesta y establece el estado de la respuesta en 200.

Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de vuelta al cliente.

Sintaxis

setPixelResponse();

Permisos asociados

Requiere el permiso access_response. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• headers: Debe permitir las siguientes claves
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

setResponseBody

Establece el cuerpo de la respuesta en el argumento.

Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de vuelta al cliente.

Sintaxis

setResponseBody(body[, encoding]);

Parámetros

Permisos asociados

Requiere el permiso access_response. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• body

setResponseHeader

Establece un encabezado en la respuesta que se devolverá. Si esta API estableció previamente un encabezado con este nombre (sin distinción entre mayúsculas y minúsculas), la última llamada sobrescribirá o borrará el valor establecido por el llamador anterior.

Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de vuelta al cliente.

Sintaxis

setResponseHeader(name, value);

Parámetros

Permisos asociados

Requiere el permiso access_response. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• headers

setResponseStatus

Establece el código de estado HTTP de la respuesta que se devolverá.

Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de vuelta al cliente.

Sintaxis

setResponseStatus(statusCode);

Parámetros

Permisos asociados

Requiere el permiso access_response. El permiso debe configurarse para permitir el acceso a, al menos, lo siguiente:

• status

sha256

Calcula el resumen SHA-256 de la entrada y llama a una devolución de llamada con el resumen codificado en Base64, a menos que el objeto options especifique una codificación de salida diferente.

La firma y el comportamiento de esta API coinciden con la API de sha256 para contenedores web. Sin embargo, las plantillas personalizadas en contenedores de servidor deben usar la API de sha256Sync para un código más simple.

Ejemplo

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

Sintaxis

sha256(input, onSuccess, options = undefined);

Parámetros

Permisos asociados

Ninguno

sha256Sync

Calcula y devuelve el resumen SHA-256 de la entrada, codificado en Base64, a menos que el objeto options especifique una codificación de salida diferente.

Ejemplo

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

Sintaxis

sha256Sync(input, options = undefined);

Parámetros

Permisos asociados

Ninguno

templateDataStorage

Devuelve un objeto con métodos para acceder al almacenamiento de datos de la plantilla. El almacenamiento de datos de plantillas permite que los datos se compartan entre las ejecuciones de una sola plantilla. Los datos almacenados en el almacenamiento de datos de la plantilla persisten en el servidor que ejecuta el contenedor. En la mayoría de los casos, hay varios servidores que ejecutan el contenedor, por lo que almacenar datos en el almacenamiento de datos de la plantilla no garantiza que cada solicitud posterior tendrá acceso a los datos.

La palabra "data" en el nombre "templateDataStorage" hace referencia al hecho de que solo se pueden almacenar tipos de datos simples y no funcionales con esta API. Las funciones o las referencias a funciones que se pasen a la API se almacenarán como null.

Sintaxis

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

Ejemplo

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

Permisos asociados

access_template_storage

testRegex

Prueba una cadena con una regex creada a través de la API de createRegex. Devuelve true si la regex coincide. De lo contrario, devuelve false.

Una regex creada con la marca global tiene estado. Consulta la documentación de RegExp para obtener más detalles.

Ejemplo

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

Sintaxis

testRegex(regex, string);

Parámetros

Permisos asociados

Ninguno

toBase64

Codifica una cadena como base64 o base64url. El valor predeterminado es la codificación en base64.

Sintaxis

toBase64(input, options);

Parámetros

Opciones

Ejemplo

const toBase64 = require('toBase64');

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

Permisos asociados

Ninguno

BigQuery

Devuelve un objeto que proporciona funciones de BigQuery.

La función BigQuery.insert permite escribir datos en una tabla de BigQuery. Devuelve una promesa que se resuelve cuando se inserta correctamente o se rechaza cuando se produce un error.

Cuando la inserción se realiza correctamente, la promesa se resuelve sin argumentos.

Cuando falla la inserción, la promesa se rechaza con una lista de objetos que contienen el motivo del error y, posiblemente, un objeto de fila si se produce un error. Es posible que una parte de la solicitud se complete correctamente, mientras que otras partes no. En este caso, la promesa se rechaza con una lista de errores para cada fila con un objeto de fila que ayuda a distinguir qué filas se insertaron (consulta los ejemplos de errores a continuación). Consulta la documentación de BigQuery sobre los mensajes de error para obtener más información.

Sintaxis

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

Parámetros

Opciones

Ejemplos de errores

Un error de módulo no encontrado significa que es probable que tu contenedor del servidor esté ejecutando una versión anterior de nuestra imagen que aún no incluía el módulo de BigQuery. Vuelve a implementar tu contenedor de servidor con la misma configuración usando nuestro script de implementación. El módulo se incluirá automáticamente una vez que finalice la operación.

Por lo general, un error de no inserción tiene un objeto de error con una clave reason:

[{reason: 'invalid'}]

Un error de inserción puede contener varios objetos de error con un array errors y un objeto row. A continuación, se muestra un ejemplo de una respuesta de error por la inserción de dos filas en la que solo una de ellas tiene un error:

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

Ejemplo

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

Permisos asociados

access_bigquery

Firestore

Devuelve un objeto que proporciona funciones de Firestore.

Esta API solo admite Firestore en modo nativo, no Firestore en modo Datastore. Además, la API solo admite el uso de la base de datos predeterminada.

Firestore.read

La función Firestore.read lee datos de un documento de Firestore y devuelve una promesa que se resuelve en un objeto que contiene dos claves: id y data. Si el documento no existe, la promesa se rechaza con un objeto que contiene una clave reason igual a not_found.

Sintaxis

Firestore.read(path[, options]);

Parámetros

Opciones

Ejemplo

const Firestore = require('Firestore');

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

Firestore.write

La función Firestore.write escribe datos en un documento o una colección de Firestore. Si la ruta es a una colección, se creará un documento con un ID generado de forma aleatoria. Si la ruta de acceso es a un documento y este no existe, se creará. Esta API devuelve una promesa que se resuelve en el ID del documento agregado o modificado. Si se usa la opción de transacción, la API seguirá devolviendo una promesa, pero no contendrá el ID, ya que las escrituras se agrupan en lotes.

Sintaxis

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

Parámetros

Opciones

Ejemplo

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 función Firestore.query consulta la colección determinada y devuelve una promesa que se resuelve en un array de documentos de Firestore que coinciden con las condiciones de la consulta. El objeto de documento de Firestore es el mismo que se indicó anteriormente en Firestore.read. Si no hay documentos que coincidan con las condiciones de la consulta, la promesa devuelta se resolverá en un array vacío.

Sintaxis

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

Parámetros

Opciones

Ejemplo

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 función Firestore.runTransaction permite que el usuario lea y escriba en Firestore de forma atómica. Si se produce una escritura simultánea o algún otro conflicto de transacción, se volverá a intentar la transacción hasta dos veces. Si falla después de tres intentos en total, la API rechazará la solicitud con un error. Esta API devuelve una promesa que se resuelve en un array de IDs de documentos, para cada operación de escritura, si la transacción se realiza correctamente, y se rechazará con el error si falla.

Sintaxis

Firestore.runTransaction(callback[, options]);

Parámetros

Opciones

Ejemplo

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

Ejemplo de error

Los errores disponibles en cada función de Firestore se rechazarán con un objeto que contenga una clave reason:

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

Los motivos del error pueden incluir, sin limitaciones, los códigos de error de la API de REST de Firestore.

Permisos asociados

access_firestore

JSON

Devuelve un objeto que proporciona funciones JSON.

La función parse() analiza una cadena JSON para construir el valor o el objeto que describe la cadena. Si el valor no se puede analizar (p.ej., JSON con formato incorrecto), la función devolverá undefined. Si el valor de entrada no es una cadena, se forzará a que sea una cadena.

La función stringify() convierte la entrada en una cadena JSON. Si el valor no se puede analizar (p.ej., el objeto tiene un ciclo), el método devolverá undefined.

Ejemplo

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

Sintaxis

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

Permisos asociados

Ninguno

Math

Objeto que proporciona funciones Math.

Sintaxis

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

Parámetros

Los parámetros de las funciones matemáticas se convierten en números.

Permisos asociados

Ninguno

Messages

Las siguientes APIs funcionan en conjunto para permitir el paso de mensajes entre diferentes partes de un contenedor.

addMessageListener

Agrega una función que detecta un mensaje de un tipo en particular. Cuando se envía un mensaje de ese tipo con la API de sendMessage (generalmente, a través de una etiqueta), la devolución de llamada se ejecutará de forma síncrona. La devolución de llamada se ejecuta con dos parámetros:

1. messageType:string
2. message:Object

Si se agrega la devolución de llamada en un cliente, esta recibirá mensajes en todos los eventos que cree el cliente. Si la devolución de llamada solo debe recibir mensajes de un evento determinado, vincula esta API al evento con bindToEvent en la función onStart de la API de runContainer. Consulta el ejemplo.

Sintaxis

const addMessageListener = require('addMessageListener');

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

Parámetros

Ejemplo

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

Permisos asociados

Requiere el permiso use_message. El permiso debe configurarse para permitir, al menos, lo siguiente:

• Es un tipo de mensaje con Usage de listen o listen_and_send.

hasMessageListener

Devuelve verdadero si se agregó un objeto de escucha de mensajes para el tipo de mensaje determinado. De lo contrario, devuelve false.

Sintaxis

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Permisos asociados

Ninguno

sendMessage

Envía un mensaje del tipo especificado a un objeto de escucha registrado. Se puede usar para enviar mensajes desde una etiqueta al cliente que ejecutó el contenedor.

Sintaxis

const sendMessage = require('sendMessage');

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

Parámetros

Permisos asociados

Requiere el permiso use_message. El permiso debe configurarse para permitir, al menos, lo siguiente:

• Es un tipo de mensaje con Usage de listen_and_send o send.

Object

Devuelve un objeto que proporciona métodos Object.

El método keys() proporciona el comportamiento de la biblioteca estándar Object.keys(). Devuelve un array de los nombres de las propiedades enumerables propias de un objeto determinado en el mismo orden en que lo haría un bucle for...in.... Si el valor de entrada no es un objeto, se forzará a que lo sea.

El método values() proporciona el comportamiento de Object.values() de la biblioteca estándar. Devuelve un array de los valores de las propiedades enumerables propias de un objeto determinado en el mismo orden en que lo haría un bucle for...in.... Si el valor de entrada no es un objeto, se forzará a que lo sea.

El método entries() proporciona el comportamiento de Object.entries() de la biblioteca estándar. Devuelve un array de pares [key, value] de propiedades enumerables propias de un objeto determinado en el mismo orden en que lo haría un bucle for...in.... Si el valor de entrada no es un objeto, se forzará a que sea un objeto.

El método freeze() proporciona el comportamiento de Object.freeze() de la biblioteca estándar. Un objeto congelado ya no se puede cambiar. Congelar un objeto evita que se le agreguen propiedades nuevas, que se quiten propiedades existentes y que se cambien los valores de las propiedades existentes. freeze() devuelve el mismo objeto que se pasó. Un argumento primitivo o nulo se tratará como si fuera un objeto inmutable y se devolverá.

El método delete() proporciona el comportamiento del operador de eliminación de la biblioteca estándar. Quita la clave proporcionada del objeto, a menos que el objeto esté congelado. Al igual que el operador de eliminación de la biblioteca estándar, devuelve true si el primer valor de entrada (objectInput) es un objeto que no está inmovilizado, incluso si el segundo valor de entrada (keyToDelete) especifica una clave que no existe. En todos los demás casos, devuelve false. Sin embargo, se diferencia del operador de eliminación de la biblioteca estándar de las siguientes maneras:

• keyToDelete no puede ser una cadena delimitada por puntos que especifique una clave anidada.
• delete() no se puede usar para quitar elementos de un array.
• delete() no se puede usar para quitar propiedades del alcance global.

Sintaxis

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

Parámetros

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Ejemplo

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

Devuelve un objeto que proporciona métodos para interactuar con promesas.

Las promesas son funcionalmente equivalentes a las promesas de JavaScript. Cada instancia tiene tres métodos que devuelven una promesa que permite realizar más acciones cuando se resuelve una promesa:

• .then(): Controla los casos resueltos y rechazados. Toma dos devoluciones de llamada como parámetros: una para el caso de éxito y otra para el caso de falla.
• .catch(): Solo maneja los casos rechazados. Toma una devolución de llamada como parámetro.
• .finally(): Proporciona una forma de ejecutar código, ya sea que la promesa se haya resuelto o rechazado. Toma una devolución de llamada como parámetro que se invoca sin argumentos.

Una variable que devuelve una promesa es igual al valor resuelto de la promesa o false si la promesa se rechaza.

Ejemplo

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

Devuelve una promesa que puede hacer lo siguiente:

• Se resuelve cuando se resolvieron todas las entradas.
• Se rechaza cuando se rechaza alguna de las entradas.

Sintaxis

Promise.all(inputs);

Parámetros

Ejemplo

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

Permisos asociados

Ninguno

Promise.create

Crea una promesa que es funcionalmente equivalente a una promesa de JavaScript.

Sintaxis

Promise.create(resolver);

Parámetros

Ejemplo

const Promise = require('Promise');

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

Permisos asociados

Ninguno

APIs de prueba

Estas APIs funcionan con pruebas de JavaScript en zona de pruebas para crear pruebas de plantillas personalizadas en Google Tag Manager. Estas APIs de prueba no necesitan una declaración de require(). [Obtén más información sobre las pruebas de plantillas personalizadas].

assertApi

Devuelve un objeto de comparador que se puede usar para realizar aserciones de forma fluida sobre la API determinada.

Sintaxis

assertApi(apiName)

Parámetros

Matchers

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

Ejemplos

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

assertThat

La API de assertThat se basa en la biblioteca [Truth] de Google. Devuelve un objeto que se puede usar para realizar aserciones de forma fluida sobre el valor de un sujeto. Una falla de aserción detendrá de inmediato la prueba y la marcará como fallida. Sin embargo, si falla una prueba, no se verán afectados otros casos de prueba.

Sintaxis

assertThat(actual, opt_message)

Parámetros

Matchers

Ejemplos

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

Falla inmediatamente la prueba actual y, si se proporciona, imprime el mensaje determinado.

Sintaxis

fail(opt_message);

Parámetros

Ejemplo

fail('This test has failed.');

mock

La API de mock te permite anular el comportamiento de las APIs de Sandboxed. La API simulada se puede usar de forma segura en el código de la plantilla, pero solo funciona en el modo de prueba. Los simulacros se restablecen antes de que se ejecute cada prueba.

Sintaxis

mock(apiName, returnValue);

Parámetros

Ejemplos

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

mockObject

La API de mockObject te permite anular el comportamiento de las APIs de Sandboxed que devuelven un objeto. La API se puede usar de forma segura en el código de la plantilla, pero solo funciona en el modo de prueba. Los simulacros se restablecen antes de que se ejecute cada prueba.

Sintaxis

mockObject(apiName, objectMock);

Parámetros

Ejemplos