APIs de etiquetado en el servidor

En este documento se describen las APIs que se pueden usar para el etiquetado en el servidor.

---

addEventCallback

Registra la función de retrollamada que se invoca al final de un evento. La retrollamada se invoca cuando se han ejecutado todas las etiquetas del evento. A la retrollamada se le transfieren dos valores: el ID del contenedor que invoca la función y un objeto que contiene información sobre el evento.

Cuando esta API se usa en una etiqueta, se asocia al evento concreto. Cuando se usa en un cliente, hay que vincularla con un evento concreto a través de la función bindToEvent de la API runContainer. Consulta más detalles en el ejemplo.

Sintaxis

const addEventCallback = require('addEventCallback');

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

Parámetros

Parámetro	Tipo	Descripción
callback	function	Es la función que se invoca al final del evento.

El objeto eventData contiene los siguientes datos:

Nombre de clave	Tipo	Descripción
tags	Array	Es un array de objetos de datos de etiqueta. Cada etiqueta que se activa durante el evento tiene una entrada en este array. El objeto de datos de etiqueta contiene el ID de la etiqueta (id), el estado de su ejecución (status) y la hora de su ejecución (executionTime). Los datos de la etiqueta también incluyen los metadatos de etiqueta adicionales que se han configurado en la etiqueta.

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 asíncrona a una función. Esta llamada se ejecutará cuando se haya devuelto el código vigente. Equivale a setTimeout(<function>, 0).

Ejemplo

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

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

Sintaxis

callLater(function)

Parámetros

Parámetro	Tipo	Descripción
function	function	Es la función a la que se debe llamar.

Permisos asociados

Ninguno.

---

claimRequest

Usa esta API en un cliente para reclamar la solicitud. Cuando se reclama una solicitud, el contenedor no ejecuta más clientes.

Esta API produce una excepción si se invoca en una etiqueta o en una variable. Produce una excepción si se invoca después de que el cliente ha devuelto un resultado (por ejemplo, si se invoca en una retrollamada asíncrona, como en callLater o la función runContainer onComplete).

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

Ejemplo

const claimRequest = require('claimRequest');

claimRequest();

Sintaxis

claimRequest();

Permisos asociados

Ninguno.

---

computeEffectiveTldPlusOne

Devuelve el dominio de nivel superior efectivo +1 (eTLD+1) de la URL o del dominio especificados. El eTLD+1 se obtiene evaluando el dominio según las reglas de la lista de sufijos públicos. Suele ser el dominio de nivel más alto en el que puedes usar cookies.

Si el argumento es nulo o no se ha definido, se devuelve el valor del argumento sin modificar. De lo contrario, el argumento se convierte en una cadena. Si el argumento no es un dominio o una URL válidos, se devuelve una cadena en blanco. Si el servidor no puede obtener la lista de sufijos públicos, se devuelve el valor del argumento 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

Parámetro	Tipo	Descripción
domainOrUrl	string	Es el dominio o la URL de los que se obtiene el eTLD+1.

Permisos asociados

Ninguno.

---

decodeUri

Decodifica los caracteres codificados del URI proporcionado. Devuelve una cadena que representa el URI decodificado. Devuelve undefined cuando se le proporciona un valor no válido.

Ejemplo

const decodeUri = require('decodeUri');

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

Sintaxis

decodeUri(encoded_uri);

Parámetros

Parámetro	Tipo	Descripción
encoded_uri	string	URI codificado por encodeUri() o por otros medios.

Permisos asociados

Ninguno.

---

decodeUriComponent

Decodifica los caracteres codificados del componente de URI proporcionado. Devuelve una cadena que representa el componente de URI decodificado. Devuelve undefined cuando se le proporciona un valor no válido.

Ejemplo

const decodeUriComponent = require('decodeUriComponent');

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

Sintaxis

decodeUriComponent(encoded_uri_component);

Parámetros

Parámetro	Tipo	Descripción
encoded_uri_component	string	Es un componente URI codificado por encodeUriComponent() o por otros medios.

Permisos asociados

Ninguno.

---

encodeUri

Devuelve un URI codificado escapando los caracteres especiales. Devuelve una cadena que representa la cadena que se ha facilitado, 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

Parámetro	Tipo	Descripción
uri	string	Es el URI completo.

Permisos asociados

Ninguno.

---

encodeUriComponent

Devuelve un URI codificado escapando los caracteres especiales. Devuelve una cadena que representa la cadena que se ha facilitado, 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

Parámetro	Tipo	Descripción
str	string	Es un componente de un URI.

Permisos asociados

Ninguno.

---

extractEventsFromMpv1

Traduce una solicitud entrante de Measurement Protocol V1 a una lista con eventos en formato de esquema unificado. Devuelve la lista de eventos extraídos. Si la solicitud no tiene el formato correcto, se produce un error.

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 se debe configurar para permitir al menos el acceso a:

• body
• query parameters

---

extractEventsFromMpv2

Traduce una solicitud entrante de Measurement Protocol V2 a una lista con eventos en formato de esquema unificado. Devuelve la lista de eventos extraídos. Si la solicitud no tiene el formato correcto, se produce un error.

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 se debe configurar para permitir al menos el acceso a:

• body
• query parameters

---

fromBase64

Decodifica una cadena codificada en base64. Devuelve undefined si el valor introducido no es válido.

Sintaxis

fromBase64(base64EncodedString);

Parámetros

Parámetro	Tipo	Descripción
base64EncodedString	string	Cadena codificada en base64.

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno.

---

generateRandom

Devuelve un número (entero) aleatorio del intervalo que se indique.

Ejemplo

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Sintaxis

generateRandom(min, max);

Parámetros

Parámetro	Tipo	Descripción
min	number	Es el valor mínimo posible del número entero que se devuelve (incluido).
max	number	Es el valor máximo posible del número entero que se devuelve (incluido).

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 en cuestión.

Sintaxis

getClientName();

Permisos asociados

read_container_data

---

getContainerVersion

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

{
  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 especificado.

Ejemplo

const getCookieValues = require('getCookieValues');

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

Sintaxis

getCookieValues(name[, noDecode]);

Parámetros

Parámetro	Tipo	Descripción
name	string	Es el nombre de la cookie.
noDecode	boolean	Si es true, los valores de la cookie no se decodifican antes de devolverlos. El valor predeterminado es false.

Permisos asociados

get_cookies

---

getEventData

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

Ejemplo

const getEventData = require('getEventData');

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

Parámetros

Parámetro	Tipo	Descripción
keyPath	any	Ruta de la clave, con los componentes de la ruta separados por puntos. Los componentes de la ruta pueden ser las claves de un objeto o los índices de un array. Si keyPath no es una cadena, se convierte en una.

Sintaxis

getEventData(keyPath);

Permisos asociados

read_event_data

---

getGoogleScript

Obtiene 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 no se ejecuta correctamente, la promesa se rechazará con una clave reason.

El objeto metadata contendrá los metadatos de almacenamiento en caché que se indican a continuación. Estos metadatos se basan en los encabezados de respuesta del recurso. Cada uno de los campos aparecerá solo 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

Parámetro	Tipo	Descripción
script	string	Nombre de la secuencia de comandos. Las secuencias de comandos admitidas son 'ANALYTICS', 'GTAG' y 'GTM'. La opción 'ANALYTICS' obtiene la secuencia de comandos de Google Analytics de https://www.google-analytics.com/analytics.js. La opción 'GTAG' obtiene la secuencia de comandos de la etiqueta global de sitio web (gtag.js) de https://www.googletagmanager.com/gtag/js. La opción 'GTM' obtiene la secuencia de comandos de Google Tag Manager de https://www.googletagmanager.com/gtm.js.
options	object	Opciones de solicitud alternativas. Consulta a continuación las opciones compatibles.

Opciones

Opción	Tipo	Descripción
id	string	Se aplica a 'GTAG' con el ID de medición de gtag y a 'GTM' con el ID de contenedor web (por ejemplo, GTM-XXXX).
debug	any	Si el valor es verdadero, solicita y devuelve la versión de depuración de la secuencia de comandos de medición.
timeout	number	Es el tiempo de espera de la solicitud expresado en milisegundos; los valores no positivos no se tienen en cuenta. Si se agota el tiempo de espera de la solicitud, la retrollamada se invoca con undefined en el caso del valor de la secuencia de comandos y con {} en el caso del objeto de metadatos.

Las claves de opción no reconocidas no se tienen en cuenta.

Permisos asociados

Requiere el permiso send_http. El permiso se debe configurar para permitir al menos el acceso a:

• Permitir Google Domains.

---

getRemoteAddress

Devuelve una representación en una cadena de la dirección IP donde se originó la solicitud (por ejemplo, 12.345.67.890 en el caso de IPv4 o 2001:0db8:85a3:0:0:8a2e:0370:7334 en el caso de IPv6), leyendo encabezados de solicitud como "Forwarded" y "X-Forwarded-For". Nota: Esta API hace todo lo posible por 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 se debe configurar para permitir al menos el acceso a:

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

---

getRequestBody

Devuelve el cuerpo de la solicitud en forma de cadena si está presente; de lo contrario, devuelve undefined.

Sintaxis

getRequestBody();

Permisos asociados

read_request

---

getRequestHeader

Devuelve el valor del encabezado de la solicitud en cuestión en forma de cadena si está presente. De lo contrario, devuelve undefined. Si el encabezado se repite, los valores devueltos se unen con ', '.

Ejemplo

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Sintaxis

getRequestHeader(headerName);

Parámetros

Parámetro	Tipo	Descripción
headerName	string	Es el nombre del encabezado. En lo que respecta a este valor, no se distingue entre mayúsculas y minúsculas.

Permisos asociados

read_request

---

getRequestMethod

Devuelve el método de solicitud (por ejemplo, 'GET' o 'POST') en forma de cadena.

Ejemplo

const getRequestMethod = require('getRequestMethod');

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

Sintaxis

getRequestMethod();

Permisos asociados

Ninguno.

---

getRequestPath

Devuelve la ruta de solicitud sin la cadena de consulta. Por ejemplo, si la URL es '/foo?id=123', devuelve '/foo'. Elimina automáticamente de la ruta el prefijo de URL del contenedor del servidor. Por ejemplo, si la URL del contenedor del servidor es https://example.com/analytics y la ruta de solicitud es '/analytics/foo', 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 la cadena de consulta en cuestión en forma de cadena si está presente. De lo contrario, devuelve undefined. Si el parámetro se repite en la cadena de consulta, se devolverá el primer valor que aparezca en dicha cadena.

Ejemplo

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Sintaxis

getRequestQueryParameter(name);

Parámetros

Parámetro	Tipo	Descripción
name	string	Es el nombre del parámetro de consulta.

Permisos asociados

read_request

---

getRequestQueryParameters

Devuelve los parámetros de consulta de la solicitud HTTP entrante como un objeto que mapea nombres de parámetros de consulta al valor o los valores correspondientes. Los nombres y los valores de los parámetros están decodificados.

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 en forma de cadena, sin el signo de interrogación inicial, o una cadena vacía si la URL de solicitud no contiene ninguna cadena de consulta.

Ejemplo

const getRequestQueryString = require('getRequestQueryString');

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

Sintaxis

getRequestQueryString();

Permisos asociados

read_request

---

getTimestamp

Obsoleta. Es preferible utilizar getTimestampMillis.

Devuelve un número que representa el tiempo transcurrido (en milisegundos) desde el inicio del registro de tiempo Unix, tal y como lo devuelve Date.now().

Sintaxis

getTimestamp();

Permisos asociados

Ninguno.

---

getTimestampMillis

Devuelve un número que representa el tiempo transcurrido (en milisegundos) desde el inicio del registro de tiempo Unix, tal y como lo devuelve Date.now().

Sintaxis

getTimestampMillis();

Permisos asociados

Ninguno.

---

getType

Devuelve una cadena que describe el tipo de valor proporcionado.

Tipo de entrada	Valor devuelto
string	'string'
number	'number'
boolean	'boolean'
null	'null'
undefined	'undefined'
Array	'array'
Object	'object'
Function	'function'

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

Parámetro	Tipo	Descripción
value	any	Es un valor de entrada.

Permisos asociados

Ninguno.

---

isRequestMpv1

Devuelve true si la solicitud entrante es una solicitud de Measurement Protocol V1. De lo contrario, devuelve false.

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 de Measurement Protocol V2. De lo contrario, devuelve false.

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.

Puedes consultar estos registros 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 varios argumentos que, si fuera necesario, se convierten en cadenas, y se registran en la consola.

Permisos asociados

logging

---

makeInteger

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

Sintaxis

makeInteger(value);

Parámetros

Parámetro	Tipo	Descripción
value	cualquier tipo	Es el valor que se convertirá.

Permisos asociados

Ninguno.

---

makeNumber

Convierte el valor en un número.

Sintaxis

makeNumber(value);

Parámetros

Parámetro	Tipo	Descripción
value	cualquier tipo	Es el valor que se convertirá.

Permisos asociados

Ninguno.

---

makeString

Devuelve el valor proporcionado como una cadena.

Sintaxis

makeString(value);

Parámetros

Parámetro	Tipo	Descripción
value	cualquier tipo	Es el valor que se convertirá.

Permisos asociados

Ninguno.

---

makeTableMap

Convierte un objeto de tabla sencilla con dos columnas en un objeto Map. Esta función se usa para convertir un campo de plantilla SIMPLE_TABLE con dos columnas en un formato más manejable.

Por ejemplo, esta función podría convertir este objeto "table":

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

en este de mapeo:

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

Devuelve un objeto: si se han añadido pares clave-valor al objeto Map, devuelve ese objeto convertido; de lo contrario, devuelve null.

Sintaxis

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parámetros

Parámetro	Tipo	Descripción
tableObj	List	Es el objeto "table" que se convertirá; una lista con mapeos donde cada fila está representada por un objeto Map. Cada nombre de propiedad que aparece en un objeto de fila es el nombre de columna, y el valor de la propiedad es el valor de columna de la fila.
keyColumnName	string	Es el nombre de la columna cuyos valores se convertirán en claves dentro del objeto Map convertido.
valueColumnName	string	Es el nombre de la columna cuyos valores se convertirán en valores dentro del objeto Map convertido.

Permisos asociados

Ninguno.

---

parseUrl

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

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

El objeto devuelto tendrá los campos siguientes:

{
  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:[e-mail]:8080/foo?param=val%2Cue#bar');

Sintaxis

parseUrl(url);

Parámetros

Parámetro	Tipo	Descripción
url	string	La URL completa que se va a analizar.

Permisos asociados

Ninguno.

---

returnResponse

Vacía la respuesta que otras plantillas han definido previamente mediante las APIs que modifican la respuesta, como setCookie, setPixelResponse, setResponseBody, setResponseHeader y setResponseStatus. El valor predeterminado es un código de estado HTTP 200, con el cuerpo vacío y sin encabezados.

Se recomienda utilizar 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 y etiquetas) en el ámbito de un evento. Si se llama a esta API durante la ejecución del contenedor, el contenedor se vuelve a ejecutar.

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

Se recomienda utilizar 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

Parámetro	Tipo	Descripción
event	object	Son los parámetros de evento.
onComplete	function	Retrollamada que se invoca después de que todas las etiquetas terminan de activarse.
onStart	function	Retrollamada que se invoca inmediatamente, antes de que las etiquetas empiecen a activarse.

Permisos asociados

run_container

---

sendEventToGoogleAnalytics

Envía un único evento que usa datos de eventos habituales a Google Analytics y devuelve una promesa que se resuelve con un objeto que contiene una clave location o se rechaza con un objeto que contiene una clave reason. El destino, Universal Analytics o Google Analytics 4, se basa en el ID de medición de los datos de eventos.

Al campo location se le asigna el encabezado location, si está presente.

Ejemplo

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();
}, (err) => {
  setResponseStatus(500);
  data.gtmOnFailure();
});

Sintaxis

sendEventToGoogleAnalytics(event);

Parámetros

Parámetro	Tipo	Descripción
event	object	Evento en formato de esquema unificado.

Permisos asociados

Requiere el permiso send_http. El permiso se debe configurar para permitir al menos el acceso a:

• Permitir Google Domains.

---

sendHttpGet

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

El resultado resuelto es un objeto que contiene tres claves: statusCode, headers y body. Si se produce un error en la solicitud (por ejemplo, si la URL no es válida, no hay ruta al host, se produce un fallo en la negociación de SSL, etc.), la promesa se rechazará con {reason: 'failed'}. Si se ha asignado la opción timeout y se ha agotado 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

Parámetro	Tipo	Descripción
url	string	URL de la solicitud.
options	object	Opciones de solicitud alternativas. Las opciones admitidas son headers y timeout. Las claves de opción desconocidas no se tienen en cuenta. Consulta la sección Opciones más abajo.

Opciones

• headers: encabezados de solicitud adicionales representados como un objeto.
• timeout: el tiempo de espera, expresado en milisegundos, antes de que se anule la solicitud. El valor predeterminado es 15000.

Permisos asociados

send_http

---

sendHttpRequest

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

El resultado resuelto es un objeto que contiene tres claves: statusCode, headers y body. Si se produce un error en la solicitud (por ejemplo, si la URL no es válida, no hay ruta al host, se produce un fallo en la negociación de SSL, etc.), la promesa se rechazará con {reason: 'failed'}. Si se ha asignado la opción timeout y se ha agotado 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

Parámetro	Tipo	Descripción
url	string	URL de la solicitud.
options	object	Opciones de solicitud alternativas. Las opciones admitidas son: headers, method y timeout. Las claves de opción desconocidas no se tienen en cuenta. Consulta la sección Opciones más abajo.
body	string	Cuerpo de la solicitud opcional.

Opciones

• headers: encabezados de solicitudes adicionales.
• method: el método de solicitud; el valor predeterminado es "GET".
• timeout: el tiempo de espera, expresado en milisegundos, antes de que se anule la solicitud. El valor predeterminado es 15000.

Permisos asociados

send_http

---

sendPixelFromBrowser

Envía un comando al navegador para que cargue la URL proporcionada como una etiqueta <img>. El protocolo de este comando se puede usar en las etiquetas web Google Analytics: configuración de GA4 y Google Analytics: evento de GA4. Debes habilitar la opción Enviar a contenedor de servidor en la etiqueta de configuración. Consulta más información en las instrucciones.

Esta API devuelve false si la solicitud entrante no admite el protocolo del comando o si la respuesta ya se ha eliminado. De lo contrario, devuelve true.

Ejemplo:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Sintaxis

sendPixelFromBrowser(url)

Parámetros

Parámetro	Tipo	Descripción
url	string	Es la URL que se enviará al navegador.

Permisos asociados

send_pixel_from_browser

---

setCookie

Configura o elimina una cookie con las opciones especificadas.

Para eliminar una cookie, debes definir otra con la misma ruta y el mismo dominio con los que se creó la primera, y asignarle un valor "expires" que ya haya pasado, como "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 nuevo 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

Parámetro	Tipo	Descripción
name	string	Nombre de la cookie. No se distingue entre mayúsculas y minúsculas.
value	string	Es el valor de la cookie.
options	object	Atributos opcionales de la cookie: domain, expires, fallbackDomain, httpOnly, max-age, path, secure y sameSite. Consulta la sección Opciones más abajo.
noEncode	boolean	Si el valor de la cookie es "true", no se codifica. El valor predeterminado es false.

Opciones

• domain: el host al que se enviará la cookie. Si se le asigna el valor especial "auto", el host se calculará automáticamente siguiendo esta 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: el tiempo de vida máximo de la cookie. Debe tener una cadena de fecha con formato UTC como, por ejemplo, "Sat, 26 oct 1985 08:21:00 GMT". Si se han configurado expires y max-age, max-age tiene prioridad.

• httpOnly: impide que JavaScript acceda a la cookie si el valor es true.

• max-age: indica los segundos que faltan para que caduque la cookie. Si el valor es cero o un número negativo, la cookie caducará inmediatamente. Si se han configurado expires y max-age, max-age tiene prioridad.

• path: una ruta que debe haber en la URL solicitada; de lo contrario, el navegador no enviará el encabezado "Cookie".

• secure:: si esta opción se define como true, la cookie solo se envía al servidor cuando se hace una solicitud desde un punto de conexión https:.

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

Permisos asociados

set_cookie

---

setPixelResponse

Asigna un GIF de 1x1 como cuerpo de respuesta, especifica "image/gif" como encabezado "Content-Type", configura los encabezados de almacenamiento en caché de manera que los user-agents no almacenen la respuesta en caché y asigna un estado de respuesta 200.

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

Sintaxis

setPixelResponse();

Permisos asociados

Requiere el permiso access_response. El permiso se debe configurar para permitir al menos el acceso a:

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

---

setResponseBody

Asigna el cuerpo de la respuesta al argumento.

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

Sintaxis

setResponseBody(body[, encoding]);

Parámetros

Parámetro	Tipo	Descripción
body	string	Es el valor que se va a asignar como cuerpo de la respuesta.
encoding	string	Codificación de caracteres del cuerpo de la respuesta (de forma predeterminada es 'utf8'). Los valores admitidos son 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' y 'hex'.

Permisos asociados

Requiere el permiso access_response. El permiso se debe configurar para permitir al menos el acceso a:

• body

---

setResponseHeader

Asigna un encabezado a la respuesta que se devuelve. Si la API ha definido anteriormente un encabezado con este nombre (no se distingue entre mayúsculas y minúsculas), la última llamada sobrescribirá o borrará el valor asignado por la llamada anterior.

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

Sintaxis

setResponseHeader(name, value);

Parámetros

Parámetro	Tipo	Descripción
name	string	Es el nombre del encabezado. En los nombres de los encabezados HTTP, no se distingue entre mayúsculas y minúsculas, por lo que el nombre del encabezado aparecerá en minúsculas.
value	cadena no definida	Valor del encabezado. Si es nulo o no se ha definido, se borra el encabezado indicado de la respuesta que se devuelve.

Permisos asociados

Requiere el permiso access_response. El permiso se debe configurar para permitir al menos el acceso a:

• headers

---

setResponseStatus

Asigna el código de estado HTTP de la respuesta que se devuelve.

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

Sintaxis

setResponseStatus(statusCode);

Parámetros

Parámetro	Tipo	Descripción
statusCode	number	El código de estado HTTP que se devuelve.

Permisos asociados

Requiere el permiso access_response. El permiso se debe configurar para permitir al menos el acceso a:

• status

---

sha256

Calcula la síntesis SHA-256 de la entrada e invoca una retrollamada con la síntesis codificada en base64, a menos que el objeto options especifique una codificación de salida diferente.

El comportamiento y la sintaxis de esta API coinciden con los de la API sha256 de los contenedores web. Sin embargo, es mejor que en las plantillas personalizadas de los contenedores de servidor se use la API sha256Sync para simplificar el código.

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

Parámetro	Tipo	Descripción
input	string	La cadena que se va a comprimir.
onSuccess	function	Función a la que se hace una llamada usando la síntesis resultante, codificada en base64, a menos que el objeto options especifique una codificación de salida diferente.
options	object	Opcional para que el objeto especifique la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding, con el valor base64 o hex.

Permisos asociados

Ninguno.

---

sha256Sync

Calcula y devuelve la síntesis SHA-256 de la entrada, codificada 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

Parámetro	Tipo	Descripción
input	string	La cadena que se va a comprimir.
options	object	Opcional para que el objeto especifique la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding, con el valor base64 o hex.

Permisos asociados

Ninguno.

---

templateDataStorage

Devuelve un objeto que contiene métodos para acceder al almacenamiento de datos de la plantilla. Este almacenamiento permite compartir datos entre diversas ejecuciones de una sola plantilla. Los datos almacenados en el almacenamiento de datos de plantilla se conservan en el servidor que ejecuta el contenedor. En la mayoría de los casos, hay varios servidores que ejecutan el contenedor, por lo que el almacenamiento de datos de plantilla no garantiza que cada solicitud posterior vaya a tener acceso a los datos.

El término "Data" (datos) del nombre "templateDataStorage" indica que solo los tipos de datos simples, que no son funciones o no hacen referencia a funciones, se pueden almacenar mediante esta API. Todas las funciones o referencias a funciones que se transmiten a la API se almacenan como null.

Nota: Las solicitudes que proceden del modo de depuración o de vista previa, o del editor de plantillas, tienen acceso al almacenamiento de datos de la plantilla que se inicializa para vaciarse y se conserva solo durante la vida útil de la solicitud (por ejemplo, para no mezclar datos de prueba o de depuración con datos de producción).

Nota: A diferencia de la API de almacenamiento web, templateDataStorage no serializa ni deserializa datos en cadenas.

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 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, (statusCode, headers, body) => {
  if (status >= 200 && status < 300) {
    setResponseBody(body);
    templateDataStorage.setItemCopy(data.key, body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(statusCode);
});

Permisos asociados

access_template_storage

---

toBase64

Codifica una cadena en base64.

Sintaxis

toBase64(input);

Parámetros

Parámetro	Tipo	Descripción
input	string	Cadena que se codificará.

Ejemplo

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Permisos asociados

Ninguno.

---

BigQuery

Devuelve un objeto que proporciona funciones BigQuery.

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

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

Cuando no se puede realizar la inserción, se rechaza la promesa 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 y otras partes, no. En ese caso se rechaza la promesa con una lista de errores para cada fila con un objeto de fila que permite identificar qué filas se han insertado. Consulta la sección Ejemplos de errores que aparece más abajo. 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

Parámetro	Tipo	Descripción
connectionInfo	object	Define la información necesaria para conectarse a una tabla de BigQuery. Hay un parámetro opcional y dos obligatorios: projectId - Opcional ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_bigquery correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud. datasetId - ID del conjunto de datos de BigQuery. tableId - ID de la tabla de BigQuery.
rows	Array	Filas que se van a insertar en la tabla.
options	object	Opciones de solicitud alternativas. Las opciones admitidas son: ignoreUnknownValues y skipInvalidRows. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo.

Opciones

Parámetro	Tipo	Descripción
ignoreUnknownValues	boolean	Si es true, acepta filas que contengan valores que no coincidan con el esquema. Se ignoran los valores desconocidos. El valor predeterminado es false.
skipInvalidRows	boolean	Si es true, inserta todas las filas válidas de una solicitud, aunque haya filas no válidas. El valor predeterminado es false.

Ejemplos de errores

El error de módulo no encontrado puede deberse a que tu contenedor del servidor esté ejecutando una versión anterior de nuestra imagen que todavía no incluya el módulo de BigQuery. Vuelve a desplegar tu contenedor del servidor con la misma configuración usando nuestra secuencia de comandos de despliegue. El módulo se incluirá automáticamente cuando termine la operación.

Los errores que no son de inserción suelen incluir un objeto de error con una clave reason:

[{reason: 'invalid'}]

Los errores de inserción pueden 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 obtenida tras insertar dos filas, donde solo una de las filas contiene 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 permite usar Firestore en modo nativo, no en modo de almacén de datos.

Firestore.read

La función Firestore.read lee los 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 rechaza la operación y envía un objeto que contiene una clave reason igual a not_found.

Nota: Firestore.read guarda en caché la respuesta de forma predeterminada mientras se ejecuta el contenedor. Para inhabilitar el almacenamiento en caché, consulta la sección Opciones más abajo. El almacenamiento en caché se inhabilita automáticamente durante cualquier transacción.

Sintaxis

Firestore.read(path[, options]);

Parámetros

Parámetro	Tipo	Descripción
path	string	La ruta al documento o a la colección. No puede empezar ni terminar con una barra diagonal (/).
options	object	Opciones de solicitud alternativas. Las opciones admitidas son: projectId, disableCache y transaction. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo.

Opciones

Parámetro	Tipo	Descripción
projectId	string	Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud.
disableCache	boolean	Opcional. Determina si se inhabilita la caché. El almacenamiento en caché está habilitado de forma predeterminada, por lo que se almacenan en caché los resultados mientras dura la solicitud.
transaction	string	Opcional. El valor obtenido de Firestore.runTransaction(). Marca la operación que se usará en una transacción.

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 lleva a una colección, se creará un documento con un ID generado de manera aleatoria. Si la ruta lleva a un documento y no existe, se creará. Esta API devuelve una promesa que se resuelve en el ID del documento añadido o modificado. Si se utiliza la opción de transacción, la API devuelve una promesa igualmente, pero no contendrá el ID, ya que las escrituras se realizan por lotes.

Sintaxis

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

Parámetros

Parámetro	Tipo	Descripción
path	string	La ruta al documento o a la colección. No puede empezar ni terminar con una barra diagonal (/).
input	object	El valor que se debe escribir en el documento. Si se define la opción de combinación, la API combinará las claves de la entrada en el documento.
options	object	Opciones de solicitud alternativas. Las opciones admitidas son: projectId, merge y transaction. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo.

Opciones

Parámetro	Tipo	Descripción
projectId	string	Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud.
merge	boolean	Opcional. Si se asigna el valor true, combina las claves de la entrada en el documento. De lo contrario, el método anulará todo el documento. El valor predeterminado es false.
transaction	string	Opcional. El valor obtenido de Firestore.runTransaction(). Marca la operación que se usará en una transacción.

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 especificada y devuelve una promesa que da como resultado un array de documentos de Firestore que cumplen las condiciones de la consulta. El objeto de documento de Firestore es el mismo que se ha indicado anteriormente en Firestore.read. Si no hay documentos que cumplan las condiciones de la consulta, la promesa devuelta dará como resultado un array vacío.

Nota: Firestore.query guarda en caché la respuesta de forma predeterminada mientras se ejecuta el contenedor. Para inhabilitar el almacenamiento en caché, consulta la sección Opciones más abajo. El almacenamiento en caché se inhabilita automáticamente durante cualquier transacción.

Nota: Firestore crea automáticamente un índice para cada campo. Para enviar consultas de varios campos, puede que tengas que crear un índice compuesto para la colección especificada. Consulta más información en la documentación de Firestore sobre índices compuestos.

Sintaxis

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

Parámetros

Parámetro	Tipo	Descripción
collection	string	Es la ruta de la colección. No puede empezar ni terminar con una barra diagonal (/).
queryConditions	Array	Array de las condiciones de consulta. Cada consulta tiene el formato de un array con tres valores: key, operator y expectedValue. Por ejemplo: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. Las condiciones se unen mediante el operador AND para crear el resultado de la consulta. Consulta los operadores de Firestore para saber qué operadores de consulta se admiten.
options	object	Opciones de solicitud alternativas. Las opciones admitidas son: projectId, disableCache, limit y transaction. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo.

Opciones

Parámetro	Tipo	Descripción
projectId	string	Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud.
disableCache	boolean	Opcional. Determina si se inhabilita la caché. El almacenamiento en caché está habilitado de forma predeterminada, por lo que se almacenan en caché los resultados mientras dura la solicitud.
limit	number	Opcional. Cambia el número máximo de resultados que devuelve la consulta. El valor predeterminado es 5.
transaction	string	Opcional. El valor obtenido de Firestore.runTransaction(). Marca la operación que se usará en una transacción.

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 al usuario leer y escribir atómicamente desde Firestore. Si se produce un conflicto de escritura simultánea o de otro tipo, se volverá a intentar la transacción hasta dos veces. Si falla después de tres intentos, la API rechazará la operación y mostrará un error. Esta API devuelve una promesa que se resuelve en un array de ID de documento, para cada operación de escritura, si la transacción se realiza correctamente y, si no se puede realizar, la rechazará.

Sintaxis

Firestore.runTransaction(callback[, options]);

Parámetros

Parámetro	Tipo	Descripción
callback	function	Retrollamada que se invoca con un ID de transacción de cadena. El ID de transacción se puede transferir a las llamadas a la API de lectura, escritura y consulta. Esta función de retrollamada debe devolver una promesa. La retrollamada puede ejecutarse hasta tres veces antes de fallar.
options	object	Opciones de solicitud alternativas. La única opción admitida es projectId. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo.

Opciones

Parámetro	Tipo	Descripción
projectId	string	Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud.

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 de error pueden incluir códigos de error de la API REST de Firestore, entre otros.

Permisos asociados

access_firestore

---

JSON

Devuelve un objeto que proporciona funciones JSON.

La función parse() analiza una cadena JSON para crear el valor u objeto descrito por la cadena. Si no se puede analizar el valor (por ejemplo, si el formato de JSON no es correcto), la función devolverá undefined. Si el valor de entrada no es una cadena, la entrada se convertirá en una cadena.

La función stringify() convierte la entrada en una cadena JSON. Si el valor no se puede analizar (por ejemplo, si 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

Un objeto que proporciona funciones matemáticas 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 juntas para permitir que se transfieran mensajes entre diferentes partes de un contenedor.

---

addMessageListener

Añade una función que detecta mensajes de un tipo determinado. Cuando se envía un mensaje de ese tipo usando la API sendMessage (suele hacerlo una etiqueta), la retrollamada se ejecuta de forma síncrona. La retrollamada se ejecuta con dos parámetros:

1. messageType:string
2. message:Object

Si la retrollamada se añade a un cliente, recibe mensajes en todos los eventos que crea el cliente. Si la retrollamada debe recibir mensajes de un solo evento, vincula esta API con el evento usando bindToEvent en la función onStart de la API 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

Parámetro	Tipo	Descripción
messageType	string	Tipo de mensaje que se procesa para detectarlo. Si el valor no es una cadena, se convierte en una cadena.
callback	function	Retrollamada que se ejecuta cuando se envía un mensaje del tipo especificado. Si la retrollamada no es una función, la API no hace nada.

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 se debe configurar para permitir al menos:

• Un tipo de mensaje con Usage de listen o listen_and_send.

---

hasMessageListener

Devuelve el valor "true" si se ha añadido un procesador de mensajes para el tipo de mensaje especificado. En caso contrario, devuelve el valor "false".

Sintaxis

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Permisos asociados

Ninguno.

---

sendMessage

Envía un mensaje del tipo especificado a un procesador registrado. Esta función puede usarse para enviar mensajes desde una etiqueta al cliente que ha ejecutado el contenedor.

Sintaxis

const sendMessage = require('sendMessage');

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

Parámetros

Parámetro	Tipo	Descripción
messageType	string	El tipo de mensaje que se va a enviar. Si el valor no es una cadena, se convertirá en una cadena.
message	object	El mensaje que se va a enviar. Si el mensaje no es un objeto, la API no hará nada.

Permisos asociados

Requiere el permiso use_message. El permiso se debe configurar para permitir al menos:

• 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 Object.keys() de la biblioteca estándar. Devuelve un array de los propios nombres de propiedades que se pueden enumerar 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 convertirá en un objeto.

El método values() proporciona el comportamiento Object.values() de la biblioteca estándar. Devuelve un array de los propios valores de propiedades que se pueden enumerar 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 convertirá en un objeto.

El método entries() proporciona el comportamiento Object.entries() de la biblioteca estándar. Devuelve un array de los propios pares [key, value] de propiedades que se pueden enumerar 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 convertirá en un objeto.

El método freeze() proporciona el comportamiento Object.freeze() de la biblioteca estándar. Un objeto inmovilizado ya no se puede cambiar. Inmovilizar un objeto impide que se le añadan nuevas propiedades, que se eliminen las propiedades que ya tenga y que se modifiquen los valores de dichas propiedades. freeze() devuelve el mismo objeto que se ha transferido. Un argumento primitivo o nulo se trata como si fuera un objeto inmovilizado y se devuelve.

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 se inmovilice. 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 se inmoviliza, aunque el segundo valor de entrada (keyToDelete) especifique una clave que no existe. Devuelve false en los demás casos. Sin embargo, se diferencia del operador de eliminación de la biblioteca estándar en lo siguiente:

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

Sintaxis

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

Parámetros

Object.keys

Parámetro	Tipo	Descripción
objectInput	any	Es el objeto cuyas claves se van a enumerar. Si la entrada no es un objeto, se convertirá en un objeto.

Object.values

Parámetro	Tipo	Descripción
objectInput	any	Es el objeto cuyos valores se van a enumerar. Si la entrada no es un objeto, se convertirá en un objeto.

Object.entries

Parámetro	Tipo	Descripción
objectInput	any	Es el objeto cuyos pares clave-valor se van a enumerar. Si la entrada no es un objeto, se convertirá en un objeto.

Object.freeze

Parámetro	Tipo	Descripción
objectInput	any	Es el objeto que se va a inmovilizar. Si la entrada no es un objeto, se tratará como un objeto inmovilizado.

Object.delete

Parámetro	Tipo	Descripción
objectInput	any	Es el objeto cuya clave se va a eliminar.
keyToDelete	string	Es la clave de nivel superior que se va a eliminar.

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.

En términos de funcionalidad, estas promesas son equivalentes a las promesas de JavaScript. Cada instancia tiene tres métodos que devuelven una promesa, lo que permite realizar más acciones cuando se determina una promesa:

• .then(): gestiona los casos resueltos y los casos rechazados. Utiliza dos retrollamadas como parámetros (una para usar en caso de éxito y otra para usar si se producen fallos).
• .catch(): solo gestiona los casos rechazados. Utiliza una retrollamada como parámetro.
• .finally(): proporciona una forma de ejecutar el código tanto si la promesa se ha resuelto como si se ha rechazado. Utiliza una retrollamada como parámetro, que se invoca sin argumento.

Una variable que devuelve una promesa equivale al valor resuelto de la promesa, o bien false si la promesa agota el tiempo de espera (rechazo).

Nota: El tiempo de espera de una promesa de JS en entorno aislado se agota al cabo de 5 segundos si no se ha resuelto.

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:

• Se resuelve cuando se han resuelto todas las entradas.
• Se rechaza cuando se rechaza cualquiera de las entradas.

Sintaxis

Promise.all(inputs);

Parámetros

Parámetro	Tipo	Descripción
inputs	Array	Array de valores o promesas. Si una entrada no es una promesa, la entrada se envía como si fuera el valor resuelto de una promesa. Devuelve un error si la entrada no es un array.

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 con funciones equivalentes a las de una promesa de JavaScript.

Sintaxis

Promise.create(resolver);

Parámetros

Parámetro	Tipo	Descripción
resolver	function	Función que se invoca con dos funciones: resolve y reject. La promesa devuelta se resuelve o se rechaza cuando se invoca el parámetro correspondiente. Devuelve un error si la resolución no es una función.

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 junto con pruebas de JavaScript en entorno aislado para probar plantillas personalizadas en Google Tag Manager. Estas APIs para pruebas no necesitan una instrucción require(). [Más información sobre las pruebas de plantillas personalizadas]

---

assertApi

Devuelve un objeto de comparación que se puede usar para comprobar de manera fluida si determinados valores de la API en cuestión son verdaderos.

Sintaxis

assertApi(apiName)

Parámetros

Parámetro	Tipo	Descripción
apiName	string	Nombre de la API que se va a comprobar. Es la misma cadena que se ha enviado a require().

Objetos de comparación

• 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 assertThat se basa en la biblioteca [Truth] de Google. Devuelve un objeto que se puede utilizar para comprobar de manera fluida que el valor de un sujeto es verdadero. Si no se puede hacer la verificación, la prueba se detendrá inmediatamente y se marcará como incompleta. No obstante, si no se puede hacer una prueba, los otros casos de prueba no se verán afectados.

Sintaxis

assertThat(actual, opt_message)

Parámetros

Parámetro	Tipo	Descripción
actual	any	El valor que se debe utilizar en las comprobaciones.
opt_message	string	Mensaje opcional que se mostrará si no se puede hacer la verificación.

Objetos de comparación

Objeto de comparación	Descripción
isUndefined()	Verifica que el sujeto es undefined.
isDefined()	Verifica que el sujeto no es undefined.
isNull()	Verifica que el sujeto es null.
isNotNull()	Verifica que el sujeto no es null.
isFalse()	Verifica que el sujeto es false.
isTrue()	Verifica que el sujeto es true.
isFalsy()	Verifica que el sujeto es falso. Los valores falsos son undefined, null, false, NaN, 0 y '' (cadena vacía).
isTruthy()	Verifica que el sujeto es verdadero. Los valores falsos son undefined, null, false, NaN, 0 y '' (cadena vacía).
isNaN()	Verifica que el sujeto es el valor NAN.
isNotNaN()	Verifica que el sujeto es cualquier valor que no sea NAN.
isInfinity()	Verifica que el sujeto es un valor infinito positivo o infinito negativo.
isNotInfinity()	Verifica que el sujeto es cualquier valor que no sea infinito positivo o infinito negativo.
isEqualTo(expected)	Verifica que el sujeto es igual al valor proporcionado. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
isNotEqualTo(expected)	Verifica que el sujeto no es igual al valor proporcionado. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
isAnyOf(...expected)	Verifica que el sujeto es igual a uno de los valores proporcionados. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
isNoneOf(...expected)	Verifica que el sujeto no es igual a ninguno de los valores proporcionados. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
isStrictlyEqualTo(expected)	Verifica que el sujeto es exactamente igual (===) al valor proporcionado.
isNotStrictlyEqualTo(expected)	Verifica que el sujeto no es exactamente igual (!==) al valor proporcionado.
isGreaterThan(expected)	Verifica que el sujeto es mayor que (>) el valor proporcionado en una comparación ordenada.
isGreaterThanOrEqualTo(expected)	Verifica que el sujeto es mayor o igual que (>=) el valor proporcionado en una comparación ordenada.
isLessThan(expected)	Verifica que el sujeto es menor que (<) el valor proporcionado en una comparación ordenada.
isLessThanOrEqualTo(expected)	Verifica que el sujeto es menor o igual que (<=) el valor proporcionado en una comparación ordenada.
contains(...expected)	Verifica que el sujeto es un array o una cadena que contiene todos los valores proporcionados en cualquier orden. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
doesNotContain(...expected)	Verifica que el sujeto es un array o una cadena que no contiene ninguno de los valores proporcionados. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
containsExactly(...expected)	Verifica que el sujeto es un array que contiene todos los valores proporcionados en cualquier orden y ningún otro valor más. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
doesNotContainExactly(...expected)	Verifica que el sujeto es un array que contiene un conjunto de valores distinto de los valores proporcionados en cualquier orden. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente.
hasLength(expected)	Verifica que el sujeto es un array o una cadena con la longitud proporcionada. La verificación siempre falla si el valor no es un array o una cadena.
isEmpty()	Verifica que el sujeto es un array o una cadena que está vacía (longitud = 0). La verificación siempre falla si el valor no es un array o una cadena.
isNotEmpty()	Verifica que el sujeto es un array o una cadena que no está vacía (longitud > 0). La verificación siempre falla si el valor no es un array o una cadena.
isArray()	Verifica que el tipo del sujeto es un array.
isBoolean()	Verifica que el tipo del sujeto es un valor booleano.
isFunction()	Verifica que el tipo del sujeto es una función.
isNumber()	Verifica que el tipo del sujeto es un número.
isObject()	Verifica que el tipo del sujeto es un objeto.
isString()	Verifica que el tipo del sujeto es una cadena.

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

Provoca inmediatamente que la prueba actual no se pueda completar y muestra el mensaje que se haya indicado.

Sintaxis

fail(opt_message);

Parámetros

Parámetro	Tipo	Descripción
opt_message	string	Texto del mensaje de error opcional.

Ejemplo

fail('This test has failed.');

---

mock

La API mock permite anular el comportamiento de las APIs en entorno aislado. La API de ejemplo se puede utilizar de forma segura en el código de las plantillas, pero no funciona cuando no se está usando el modo de prueba. Los ejemplos se restablecen antes de ejecutar cada prueba.

Sintaxis

mock(apiName, returnValue);

Parámetros

Parámetro	Tipo	Descripción
apiName	string	Nombre de la API que se debe usar como ejemplo. Es la misma cadena que se ha enviado a require().
returnValue	any	Valor que se debe devolver de la API o la función a la que se llama en lugar de la API. Si returnValue es una función, se llama a esa función en lugar de la API en entorno aislado; si returnValue no es una función, se devuelve ese valor en lugar de la API en entorno aislado.

Ejemplos

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

---

runCode

Ejecuta el código de la plantilla, es decir, el contenido de la pestaña Código, en el entorno de prueba vigente con el objeto de datos de entrada indicado.

Sintaxis

runCode(data)

Parámetros

Parámetro	Tipo	Descripción
data	object	Es el objeto de datos que se va a usar en la prueba.

Valor devuelto

Devuelve el valor de una variable en el caso de las plantillas de variables. Cuando se trata de otros tipos de plantilla, devuelve undefined.

Ejemplo

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

---