APIs de plantillas personalizadas

APIs principales

Estas APIs funcionan con JavaScript de zona de pruebas para compilar plantillas personalizadas en Google Tag Manager. Cada API se agrega con una instrucción require(), p.ej.:

const myAPI = require('myAPI');

addConsentListener

Registra una función de objeto de escucha para que se ejecute cuando cambia el estado del tipo de consentimiento especificado.

Se invocará al objeto de escucha determinado cada vez que el estado del tipo de consentimiento especificado cambie de denegado a concedido o de concedido a denegado. Un tipo de consentimiento sin estado se considera otorgado, por lo que no se llamará al objeto de escucha si se actualiza un tipo de consentimiento sin establecer a concedido. Las funciones de los objetos de escucha se encargarán de garantizar que el código se ejecute la cantidad adecuada de veces.

Ejemplo:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

Sintaxis

addConsentListener(consentType, listener)

Parámetros

Parámetro Tipo Descripción
consentType string El tipo de consentimiento para detectar cambios de estado.
listener function Es la función que se ejecuta cuando cambia el estado del tipo de consentimiento especificado.

Cuando se invoca un objeto de escucha, se le pasa el tipo de consentimiento que se está modificando y el valor nuevo de ese tipo de consentimiento:

Parámetro Tipo Descripción
consentType string El tipo de consentimiento que se modificará.
granted boolean Es un valor booleano que es verdadero si se cambia el tipo de consentimiento especificado a "Concedido".

Permisos asociados

access_consent con acceso de lectura para el tipo de consentimiento.


addEventCallback

La API de addEventCallback te permite registrar una función de devolución de llamada que se invocará al final de un evento. Se invocará la devolución de llamada cuando se ejecuten todas las etiquetas del evento o si se alcanza un tiempo de espera de un evento en la página. 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.

Sintaxis

addEventCallback(callback)

Parámetros

Parámetro Tipo Descripción
callback function La función que se invocará al final del evento.

El objeto eventData contiene los siguientes datos:

Nombre de la clave Tipo Descripción
tags Matriz Un array de objetos de datos de etiquetas. Cada etiqueta que se activó durante el evento tendrá una entrada en este array. El objeto de datos de la etiqueta contiene el ID de la etiqueta (id), su estado de ejecución (status) y su tiempo de ejecución (executionTime). Los datos de la etiqueta también incluirán metadatos de etiqueta adicionales que se configuraron en la etiqueta.

Ejemplo

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

Permisos asociados

read_event_metadata


aliasInWindow

La API de aliasInWindow te permite crear un alias (p.ej., window.foo = window.bar), que ayuda a admitir ciertas etiquetas que requieren alias. Asigna el valor en el objeto window que se encuentra en fromPath a la clave en el objeto window en toPath. Muestra true si se ejecuta correctamente; de lo contrario, muestra false.

Sintaxis

aliasInWindow(toPath, fromPath)

Parámetros

Parámetro Tipo Descripción
toPath string Una ruta de acceso separada por puntos al objeto window en el que se debe copiar un valor. Todos los componentes de la ruta hasta el último componente ya deben existir en el objeto window.
fromPath string Una ruta de acceso separada por puntos en window al valor que se copiará. Si el valor no existe, la operación fallará.

Ejemplo

aliasInWindow('foo.bar', 'baz.qux')

Permisos asociados

access_globals es obligatorio para toPath y fromPath; toPath requiere acceso de escritura y fromPath requiere acceso de lectura.


callInWindow

Te permite llamar a funciones desde una ruta fuera del objeto window, de una manera controlada por políticas. Llama a la función en la ruta de acceso determinada en window con los argumentos dados y muestra el valor. Si el tipo de datos que se muestra no se puede asignar directamente a un tipo compatible con el código JavaScript de zona de pruebas, se mostrará undefined. Los ocho tipos admitidos en la zona de pruebas de JavaScript son null, undefined, boolean, number, string, Array, Object y function. Si la ruta de acceso especificada no existe o no hace referencia a una función, se mostrará undefined.

Sintaxis

callInWindow(pathToFunction, argument [, argument2,... argumentN])

Parámetros

Parámetro Tipo Descripción
pathToFunction string Una ruta de acceso separada por puntos a la función en window a la que se llamará.
args * Argumentos que se pasarán a la función.

Permisos asociados

access_globals con el permiso execute habilitado


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

Sintaxis

callLater(function)

Parámetros

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

copyFromDataLayer

Muestra el valor asignado actualmente a la clave determinada en la capa de datos: Es el valor que se encuentra en la clave determinada si es un tipo primitivo, una función o un literal de objeto, o bien undefined.

Sintaxis

copyFromDataLayer(key[, dataLayerVersion])

Parámetros

Parámetro Tipo Descripción
key string La clave en el formato “a.b.c”.
dataLayerVersion número La versión de la capa de datos opcional. El valor predeterminado es 2. No se recomienda usar el valor 1.

Permisos asociados

read_data_layer


copyFromWindow

Copia una variable del objeto window. Si el valor de window no se puede asignar directamente a un tipo compatible con el código JavaScript de zona de pruebas, se mostrará undefined. Los ocho tipos admitidos en la zona de pruebas de JavaScript son null, undefined, boolean, number, string, Array, Object y function. Muestra el valor recuperado (y forzado).

Sintaxis

copyFromWindow(key)

Parámetros

Parámetro Tipo Descripción
key string La clave en el window de la que se copiará el valor.

Permisos asociados

access_globals


createArgumentsQueue

Crea una cola que se propaga con objetos de argumento, para admitir soluciones de etiquetas que lo requieren.

Crea una función en alcance global (es decir, window) con el argumento fnKey (misma semántica que createQueue). Después de crear la función, esta API crea un array en window (si aún no existe) con el argumento arrayKey.

Cuando se llama a la función creada en fnKey, envía su objeto de argumento al array creado en arrayKey. El valor que se muestra de la API es la función creada en fnKey.

Esta función requiere la configuración de lectura y escritura para fnKey y arrayKey en el permiso access_globals.

Ejemplo:

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

Sintaxis

createArgumentsQueue(fnKey, arrayKey)

Parámetros

Parámetro Tipo Descripción
fnKey string La ruta de acceso en window en la que se establece la función, si todavía no existe. Este argumento admite la notación de puntos estándar. Si la ruta de acceso de la clave no existe, se arrojará una excepción. Es decir, si fnKey es 'one.two', arrojará una excepción.
arrayKey string Es la ruta de acceso en window en la que está configurado el array, si aún no existe. Este argumento admite la notación de puntos estándar. Si la ruta de acceso de la clave no existe, se arrojará una excepción. Es decir, si arrayKey es 'one.two', y no hay un objeto global llamado 'one', se arrojará una excepción.

Permisos asociados

access_globals


createQueue

Crea un array en window (si aún no existe) y muestra una función que enviará valores a ese array.

Esta función requiere la configuración de lectura y escritura para arrayKey en el permiso access_globals.

Ejemplo:

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

Sintaxis

createQueue(arrayKey)

Parámetros

Parámetro Tipo Descripción
arrayKey string La clave de window en la que se establece el array, si aún no existe. Este argumento admite la notación de puntos estándar. Si la ruta de acceso de la clave no existe, se arrojará una excepción. Por ejemplo, si arrayKey es 'one.two' y no hay un objeto global llamado 'one', se arrojará una excepción.

Permisos asociados

access_globals


decodeUri

Decodifica cualquier carácter codificado en el URI proporcionado. Muestra una string que representa el URI decodificado. Muestra undefined cuando se proporciona una entrada no válida.

Ejemplo:

const decode = require('decodeUri');

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

Sintaxis

decodeUri(encoded_uri)

Parámetros

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

Permisos asociados

Ningún contenido de este tipo


decodeUriComponent

Decodifica cualquier carácter codificado en el componente de URI proporcionado. Muestra una string que representa el componente de URI decodificado. Muestra undefined cuando se proporciona con una entrada no válida.

Ejemplo:

const decode = require('decodeUriComponent');

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

Sintaxis

decodeUriComponent(encoded_uri_component)

Parámetros

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

Permisos asociados

Ningún contenido de este tipo


encodeUri

Muestra un identificador uniforme de recursos (URI) codificado mediante el escape de caracteres especiales. Muestra una string que representa la string proporcionada codificada como un URI. Muestra undefined cuando se proporciona una entrada no válida (un subrogado solitario).

Ejemplo:

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

Sintaxis

encodeUri(uri)

Parámetros

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

Permisos asociados

Ningún contenido de este tipo


encodeUriComponent

Muestra un identificador uniforme de recursos (URI) codificado mediante el escape de caracteres especiales. Muestra una string que representa la string proporcionada codificada como un URI. Muestra undefined cuando se proporciona una entrada no válida (un subrogado solitario).

Ejemplo:

sendPixel('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

Ningún contenido de este tipo


fromBase64

La API de fromBase64 te permite decodificar cadenas de su representación en Base64. Muestra undefined cuando se proporciona una entrada no válida.

Sintaxis

fromBase64(base64EncodedString)

Parámetros

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

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno


generateRandom

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

Sintaxis

generateRandom(min, max)

Parámetros

Parámetro Tipo Descripción
min número Valor potencial mínimo del número entero que se muestra.
max número Valor potencial máximo del número entero que se muestra.

Permisos asociados

Ningún contenido de este tipo


getContainerVersion

Muestra un objeto que contiene datos sobre el contenedor actual. El objeto que se muestra tiene los siguientes campos:

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

Ejemplo

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

Sintaxis

getContainerVersion();

Permisos asociados

read_container_data


getCookieValues

Muestra los valores de todas las cookies con el nombre dado.

Sintaxis

getCookieValues(name[, decode])

Parámetros

Parámetro Tipo Descripción
name string Nombre de la cookie.
decode boolean Controla si los valores de las cookies se deben decodificar con el decodeURIComponent() de JavaScript. La configuración predeterminada es true.

Permisos asociados

get_cookies


getQueryParameters

Muestra el primero o todos los parámetros del queryKey de la URL actual. Muestra el primer valor de queryKey o un array de valores de queryKey.

Sintaxis

getQueryParameters(queryKey[, retrieveAll])

Parámetros

Parámetro Tipo Descripción
queryKey string La clave que se debe leer desde los parámetros de consulta.
retrieveAll boolean Indica si se deben recuperar todos los valores.

Por ejemplo, si la URL actual es https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, sucede lo siguiente:

  • getQueryParameters('var') == 'foo'
  • getQueryParameters('var', false) == 'foo'
  • getQueryParameters('var', null) == 'foo'
  • getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Permisos asociados

get_url debe permitir el componente query y especificar el queryKey en las claves de consulta permitidas (o permitir cualquier clave de consulta).


getReferrerQueryParameters

La API de getReferrerQueryParameters actúa de la misma manera que getQueryParameters, excepto que actúa en la URL de referencia en lugar de la URL actual. Muestra el primero o todos los parámetros para el queryKey de la URL de referencia determinada. Muestra el primer valor de queryKey o un array de valores de queryKey.

Sintaxis

getReferrerQueryParameters(queryKey[, retrieveAll])

Parámetros

Parámetro Tipo Descripción
queryKey string La clave que se debe leer desde los parámetros de consulta.
retrieveAll boolean Indica si se deben recuperar todos los valores.

Por ejemplo, si la URL de referencia es https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, sucede lo siguiente:

  • getReferrerQueryParameters('var') == 'foo'
  • getReferrerQueryParameters('var', false) == 'foo'
  • getReferrerQueryParameters('var', null) == 'foo'
  • getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Permisos asociados

get_referrer debe permitir el componente query y especificar el queryKey en las claves de consulta permitidas (o permitir cualquier clave de consulta).


getReferrerUrl

Según un tipo de componente, la API lee el objeto del documento de la URL de referencia y muestra una cadena que representa una parte de ella. Si no se especifica ningún componente, se muestra la URL de referencia completa.

Sintaxis

getReferrerUrl([component])

Parámetros

Parámetro Tipo Descripción
component string El componente que se mostrará desde la URL. Puede ser uno de los siguientes: protocol, host, port, path, query o extension. Si component es undefined, null o no coincide con ninguno de estos componentes, se mostrará la URL completa.

Permisos asociados

get_referrer debe permitir el componente query y especificar el queryKey en las claves de consulta permitidas (o permitir cualquier clave de consulta).


getTimestamp

Obsoleto. Opta por getTimestampMillis.

Muestra un number que representa la hora actual en milisegundos desde la época Unix, como lo muestra Date.now().

Sintaxis

getTimestamp();

Permisos asociados

Ningún contenido de este tipo


getTimestampMillis

Muestra un number que representa la hora actual en milisegundos desde la época Unix, como lo muestra Date.now().

Sintaxis

getTimestampMillis();

Permisos asociados

Ningún contenido de este tipo


getType

Muestra una string que describe el tipo de valor determinado. A diferencia de typeof, getType diferencia entre array y object.

Sintaxis

getType(data.someField)

Notas

En la siguiente tabla, se enumeran las strings que se muestran para cada valor de entrada.

Valor de entrada Resultado
undefined 'indefinido'
null “nulo”
true 'boolean'
12 'número'
'string' 'cadena'
{ a: 3 } 'objeto'
[ 1, 3 ] 'matriz'
(x) => x + 1 'función'

Permisos asociados

Ningún contenido de este tipo


getUrl

Muestra una string que representa toda la URL actual o una parte de ella, según un tipo de componente y algunos parámetros de configuración.

Sintaxis

getUrl(component)

Parámetros

Parámetro Tipo Descripción
component string El componente que se mostrará desde la URL. Debe ser uno de los siguientes: protocol, host, port, path, query, extension o fragment. Si el componente es undefined, null o no coincide con ninguno de estos componentes, se mostrará el valor href completo.

Permisos asociados

get_url


gtagSet

Envía un comando de conjunto de gtag a la capa de datos para que se procese lo antes posible después de que termine el evento actual y las etiquetas que activó (o se agote el tiempo de espera de procesamiento de las etiquetas). Se garantiza que la actualización se procesará en este contenedor antes que cualquier elemento en cola de la cola de Data Layer.

Por ejemplo, si la llama una etiqueta activada en la Inicialización de consentimiento, la actualización se aplicará antes de que se procese el evento de inicialización. Por ejemplo, ads_data_redaction se establece en true o false, o url_passthrough se establece en true o false.

Ejemplos:

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

Sintaxis

gtagSet(object)

Parámetros

Parámetro Tipo Descripción
Object objeto Un objeto que actualiza el estado global de las propiedades que lo contienen.

Permisos asociados

write_data_layer verifica el permiso de escritura en dataLayer para todas las claves especificadas. Si la entrada a gtagSet es un objeto sin formato, la API verificará el permiso de escritura en todas las claves acopladas dentro de ese objeto, p.ej., para gtagSet({foo: {bar: 'baz'}}), la API verificará el permiso de escritura en foo.bar.

Si la entrada a gtagSet es una clave y algún valor de objeto no sin formato, la API verificará el permiso de escritura de esa clave; p.ej., para gtagSet('abc', true) , la API verificará el permiso de escritura en 'abc'.

Ten en cuenta que si hay un ciclo en el objeto de entrada, solo se marcarán las claves anteriores a llegar al mismo objeto.


injectHiddenIframe

Agrega un iframe invisible a la página.

Las devoluciones de llamada se proporcionan como instancias de funciones y se incluyen en las funciones de JavaScript que llaman a través de ellas.

Sintaxis

injectHiddenIframe(url, onSuccess)

Parámetros

Parámetro Tipo Descripción
url string La URL que se usará como valor del atributo src del iframe.
onSuccess function Se llama cuando el fotograma se carga correctamente.

Permisos asociados

inject_hidden_iframe


injectScript

Agrega una etiqueta de secuencia de comandos a la página para cargar la URL determinada de forma asíncrona. Las devoluciones de llamada se proporcionan como instancias de función y se unen en las funciones de JavaScript que llaman a través de ellas.

Sintaxis

injectScript(url, onSuccess, onFailure[, cacheToken])

Parámetros

Parámetro Tipo Descripción
url string La dirección de la secuencia de comandos que se insertará.
onSuccess function Se llama cuando la secuencia de comandos se carga correctamente.
onFailure function Se llama cuando no se puede cargar la secuencia de comandos.
cacheToken string Es una cadena opcional que se usa para indicar que la URL determinada se debe almacenar en caché. Si se especifica este valor, solo se creará un elemento de la secuencia de comandos para solicitar JavaScript. Cualquier intento adicional de carga hará que los métodos onSuccess y onFailure determinados se pongan en cola hasta que se cargue la secuencia de comandos.

Permisos asociados

inject_script


isConsentGranted

Muestra el valor true si se otorga el tipo de consentimiento especificado.

Se considera que el consentimiento para un tipo de consentimiento específico se otorgó si el tipo de consentimiento se configuró como "Concedido" o no se estableció en absoluto. Si el tipo de consentimiento se establece en cualquier otro valor, se considerará no otorgado.

La interfaz de usuario de Tag Manager para la configuración de etiquetas ofrecerá la opción de activar siempre. Si una etiqueta con la función Siempre activado usa esta API, el consentimiento se considera otorgado y se mostrará true, independientemente del estado real de consentimiento.

Ejemplo:

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

Sintaxis

isConsentGranted(consentType)

Parámetros

Parámetro Tipo Descripción
consentType string Es el tipo de consentimiento del que se debe verificar el estado.

Permisos asociados

access_consent con acceso de lectura para el tipo de consentimiento.


JSON

Muestra un objeto que proporciona funciones JSON.

La función parse() analiza una cadena JSON para construir el valor o el objeto que se describe en la cadena. Si el valor no se puede analizar (p.ej., un JSON con formato incorrecto), la función mostrará 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 string JSON. Si no se puede analizar el valor (p.ej., el objeto tiene un ciclo), el método mostrará undefined.

Sintaxis

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

Parámetros

JSON.parse

Parámetro Tipo Descripción
stringInput cualquiera Valor que se va a convertir. Si el valor no es una string, la entrada se convertirá en una string.

JSON.stringify

Parámetro Tipo Descripción
valor cualquiera Valor que se va a convertir.

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

localStorage

Muestra un objeto con métodos para acceder al almacenamiento local.

Sintaxis

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

Permisos asociados

access_local_storage

Ejemplo

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

Registra los argumentos en la consola del navegador.

Sintaxis

logToConsole(obj1 [, obj2,... objN])

Parámetros

Parámetro Tipo Descripción
obj1 [, obj2,... objN] cualquiera Argumentos

Permisos asociados

logging


makeInteger

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

Sintaxis

makeInteger(value)

Parámetros

Parámetro Tipo Descripción
value cualquiera Valor que se va a convertir.

Permisos asociados

Ningún contenido de este tipo


makeNumber

Convierte el valor dado en un número.

Sintaxis

makeNumber(value)

Parámetros

Parámetro Tipo Descripción
value cualquiera Valor que se va a convertir.

Permisos asociados

Ningún contenido de este tipo


makeString

Muestra el valor dado como una string.

Sintaxis

makeString(value)

Parámetros

Parámetro Tipo Descripción
value cualquiera Valor que se va a convertir.

Permisos asociados

Ningún contenido de este tipo


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

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

Muestra un objeto: el Map convertido si se le agregaron pares clave-valor, o bien null de lo contrario.

Sintaxis

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parámetros

Parámetro Tipo Descripción
tableObj Lista El objeto de la tabla que se convertirá. Es una lista de mapas en la que cada Map representa una fila en la tabla. Cada nombre de propiedad en un objeto de fila es el nombre de la columna, y el valor de la propiedad es el valor de la columna en la fila.
keyColumnName string Nombre de la columna cuyos valores se convertirán en claves en el Map convertido.
valueColumnName string Es el nombre de la columna cuyos valores se convertirán en valores en el Map convertido.

Permisos asociados

Ningún contenido de este tipo


Math

Un 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

Ningún contenido de este tipo


Object

Muestra un objeto que proporciona métodos Object.

El método keys() proporciona el comportamiento Object.keys() de la biblioteca estándar. Muestra un array de los 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. Muestra un array de los 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. Muestra un array de los pares de propiedades que se pueden enumerar [key, value] 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. Cuando se inmoviliza un objeto, se evita que se le agreguen propiedades nuevas, que se quiten las propiedades existentes y que se modifiquen los valores de las propiedades existentes. freeze() muestra el mismo objeto que se pasó. Un argumento primitivo o nulo se tratará como si fuera un objeto congelado y se mostrará.

El método delete() proporciona el comportamiento del operador de eliminación de la biblioteca estándar. Quita la clave dada del objeto, a menos que este esté inmovilizado. Al igual que el operador de eliminación de la biblioteca estándar, muestra 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. Muestra false en todos los demás casos. Sin embargo, se diferencia del operador de eliminación de la biblioteca estándar de las siguientes maneras:

  • keyToDelete no puede ser una string delimitada por puntos que especifique una clave anidada.
  • No se puede usar delete() para quitar elementos de un array.
  • No se puede usar delete() 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

Parámetro Tipo Descripción
objectInput cualquiera El objeto cuyas claves se deben enumerar. Si la entrada no es un objeto, se convertirá en un objeto.

Object.values

Parámetro Tipo Descripción
objectInput cualquiera 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 cualquiera El objeto cuyos pares clave-valor se deben enumerar. Si la entrada no es un objeto, se convertirá en un objeto.

Object.freeze

Parámetro Tipo Descripción
objectInput cualquiera El objeto que se debe inmovilizar. Si la entrada no es un objeto, se tratará como un objeto congelado.

Object.delete

Parámetro Tipo Descripción
objectInput cualquiera El objeto cuya clave se borrará.
keyToDelete string Es la clave de nivel superior que se borrará.

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.

parseUrl

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

Esta API mostrará undefined para todas las URLs con errores de formato. 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

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

Permisos asociados

Ningún contenido de este tipo


queryPermission

Consulta los permisos permitidos y restringidos. Muestra un valor boolean: true si se otorga un permiso; de lo contrario, muestra false.

Sintaxis

queryPermission(permission, functionArgs*)

Parámetros

Parámetro Tipo Descripción
permission string Es el nombre del permiso.
functionArgs cualquiera Los argumentos de función varían según el permiso que se consulta. Consulta la sección Argumentos de la función a continuación.

Argumentos de la función

sendPixel, injectScript, injectHiddenIframe: El segundo parámetro debe ser una cadena de URL.

writeGlobals, readGlobals: El segundo parámetro debe ser la clave que se escribe o se lee.

readUrl: No se necesitan argumentos adicionales para consultar si se puede leer toda la URL. Para consultar si un componente determinado se puede leer, pasa el nombre del componente como el segundo argumento:

if (queryPermission('readUrl','port')) {
  // read the port
}

Para verificar si una clave de consulta específica es legible, pasa la clave de consulta como el tercer parámetro:

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

Permisos asociados

Ningún contenido de este tipo


readCharacterSet

Muestra el valor de document.characterSet.

Sintaxis

readCharacterSet()

Parámetros

Ningún contenido de este tipo

Permisos asociados

read_character_set


readTitle

Muestra el valor de document.title.

Sintaxis

readTitle()

Parámetros

Ningún contenido de este tipo

Permisos asociados

read_title


require

Importa una función integrada por nombre. Muestra una función o un objeto al que se puede llamar desde tu programa. Muestra undefined cuando el navegador no admite la función integrada.

Sintaxis

require(name)

Parámetros

Parámetro Tipo Descripción
name string El nombre de la función que se importará.

Ejemplo

const getUrl = require('getUrl');
const url = getUrl();

Permisos asociados

Ningún contenido de este tipo


sendPixel

Realiza una solicitud GET a un extremo de URL especificado.

Sintaxis

sendPixel(url, onSuccess, onFailure)

Parámetros

Parámetro Tipo Descripción
url string A dónde enviar el píxel.
onSuccess function Se llama cuando el píxel se carga correctamente. Nota: Incluso si la solicitud se envía correctamente, es posible que los navegadores requieran una respuesta de imagen válida para ejecutar onSuccess.
onFailure function Se llama cuando el píxel no se carga. Nota: Incluso si la solicitud se envía correctamente, se puede ejecutar onFailure si el servidor no muestra una respuesta de imagen válida.

Permisos asociados

send_pixel


setCookie

Establece o borra la cookie con el nombre, el valor y las opciones especificados.

Sintaxis

setCookie(name, value[, options, encode])

Parámetros

Parámetro Tipo Descripción
name string Nombre de la cookie.
value string Valor de la cookie.
options objeto Especifica los atributos de dominio, ruta de acceso, vencimiento, antigüedad máxima, seguridad y SameSite. (Consulta Opciones a continuación).
encode boolean Controla si el valor de la cookie se debe codificar con el elemento encodeURIComponent() de JavaScript. La configuración predeterminada es true.

  • Dominio: establecido por la propiedad options['domain'], si está presente. Establece este valor en 'auto' para intentar escribir la cookie con el dominio más amplio posible, según la ubicación del documento. Si eso falla, probará de forma sucesiva subdominios más estrechos. Si todos fallan, intentará escribir la cookie sin un dominio. Si no se establece ningún valor, se intentará escribir la cookie sin un dominio especificado. Nota: Cuando una cookie sin un dominio especificado se escribe en document.cookie, el usuario-agente establecerá el dominio de la cookie de forma predeterminada en el host de la ubicación actual del documento.
  • Ruta de acceso: Es establecida por options['path'], si está presente. Cuando una cookie sin una ruta especificada se escribe en document.cookie, el usuario-agente configura, de forma predeterminada, la ruta de acceso de la cookie a la ruta de la ubicación actual del documento.
  • Max-Age: Es el valor establecido por options['max-age'], si está presente.
  • Vencimiento: establecido por options['expires'], si está presente Si está presente, debe ser una string de fecha con formato UTC. Date.toUTCString() se puede usar a fin de dar formato a un Date para este parámetro.
  • Secure: Es configurado por options['secure'], si está presente.
  • SameSite: Establecido por options['samesite'], si está presente

Permisos asociados

set_cookies


setDefaultConsentState

Envía una actualización de consentimiento predeterminada a la capa de datos para que se procese lo antes posible después de que finaliza el evento actual y las etiquetas que activó (o se agota el tiempo de espera de procesamiento de las etiquetas). Se garantiza que la actualización se procesará en este contenedor antes que en cualquier elemento en cola en la capa de datos. Obtén más información sobre el consentimiento.

Ejemplo:

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

Sintaxis

setDefaultConsentState(consentSettings)

Parámetros

Parámetro Tipo Descripción
consentSettings objeto Un objeto que define el estado predeterminado para los tipos de consentimiento especificados.

El objeto consentSettings es una asignación de cadenas de tipo de consentimiento arbitrarias a 'granted' o 'denied'. Admite los siguientes valores:

Nombre de la clave Tipo Descripción
consentType string El valor de cada tipo de consentimiento se puede establecer como "granted" o "denied". Cualquier valor distinto de "granted" se tratará como "denied". Configurar el valor como "undefined" no tendrá ningún efecto en su valor anterior.
region Matriz Un array opcional de códigos regionales que especifica a qué región se aplica la configuración de consentimiento. Los códigos de región se expresan con países o subdivisiones en formato ISO 3166-2.
wait_for_update número Especifica un valor de milisegundos para controlar cuánto tiempo se debe esperar antes de que se envíen los datos. Se usa con herramientas de consentimiento que se cargan de forma asíncrona.

Permisos asociados

access_consent con acceso de escritura para todos los tipos de consentimiento en el objeto consentimientoSettings.


setInWindow

Establece el valor dado en window con la clave dada. De forma predeterminada, este método no establecerá el valor en window si ya hay un valor presente. Establece overrideExisting como true para establecer el valor en window, sin importar la presencia de un valor existente. Muestra un valor boolean: true si el valor se configuró correctamente y false en caso contrario.

Sintaxis

setInWindow(key, value, overrideExisting)

Parámetros

Parámetro Tipo Descripción
key string La clave en window en la que se debe colocar el valor.
value * Es el valor que se establece en window.
overrideExisting boolean Es la marca que indica que el valor se debe establecer en window, independientemente de si existe o no un valor.

Permisos asociados

access_globals


sha256

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

Ejemplo:

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

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

Sintaxis

sha256(input, onSuccess, onFailure = undefined, options = undefined)

Parámetros

Parámetro Tipo Descripción
input string Es la cadena para la que se calcula el hash.
onSuccess function Se llama con el resumen resultante, codificado en base64, a menos que el objeto options especifique una codificación de salida diferente.
onFailure function Se llama si se produce un error mientras se calcula el resumen o si el navegador no es compatible de forma nativa con sha256. Se llama a la devolución de llamada con un objeto que contiene el nombre del error y el mensaje.
options objeto Opcional para especificar la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding con un valor de base64 o hex.

Permisos asociados

Ningún contenido de este tipo


templateStorage

Muestra un objeto con métodos para acceder al almacenamiento de plantillas. El almacenamiento de plantillas permite compartir los datos entre las ejecuciones de una sola plantilla. Los datos almacenados en el almacenamiento de plantillas persisten durante todo el ciclo de vida de la página.

Sintaxis

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

Permisos asociados

access_template_storage

Ejemplo

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

La API de toBase64 te permite codificar una string en una representación en base64.

Sintaxis

toBase64(input)

Parámetros

Parámetro Tipo Descripción
input string Cadena para codificar

Ejemplo

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Permisos asociados

Ninguno


updateConsentState

Envía una actualización de consentimiento a la capa de datos para que se procese lo antes posible después de que termine el evento actual y las etiquetas que activó (o cuando se alcance el tiempo de espera de procesamiento de las etiquetas). Se garantiza que la actualización se procesará en este contenedor antes que en cualquier elemento en cola en la capa de datos. Obtén más información sobre el consentimiento.

Ejemplo:

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

Sintaxis

updateConsentState(consentSettings)

Parámetros

Parámetro Tipo Descripción
consentSettings objeto Un objeto que actualiza el estado de los tipos de consentimiento especificados.

El objeto consentSettings es una asignación de cadenas de tipo de consentimiento arbitrarias a 'granted' o 'denied'. Admite los siguientes valores:

Nombre de la clave Tipo Descripción
consentType string El valor de cada tipo de consentimiento se puede establecer como "otorgado" o "denegado". Cualquier valor que no sea "otorgado" se tratará como "denegado". Configurar el valor como “indefinido” no tendrá ningún efecto en su valor anterior.

Permisos asociados

access_consent con acceso de escritura para todos los tipos de consentimiento en el objeto consentimientoSettings.


API de prueba

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


assertApi

Muestra un objeto comparador que se puede usar para realizar aserciones con fluidez sobre la API determinada.

Sintaxis

assertApi(apiName)

Parámetros

Parámetro Tipo Descripción
apiName string El nombre de la API que se verificará; la misma string que se pasó a require().

Comparadores

  • 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. Muestra un objeto que se puede usar para realizar aserciones con fluidez sobre el valor de un sujeto. Una falla de aserción detendrá de inmediato la prueba y la marcará como con errores. Sin embargo, si una prueba falla, no se verán afectados otros casos de prueba.

Sintaxis

assertThat(actual, opt_message)

Parámetros

Parámetro Tipo Descripción
actual cualquiera El valor que se usará en las verificaciones de fluidez.
opt_message string Mensaje opcional para imprimir si la aserción falla.

Comparadores

Matcher Descripción
isUndefined() Afirma que el sujeto es undefined.
isDefined() Afirma que el sujeto no es undefined.
isNull() Afirma que el sujeto es null.
isNotNull() Afirma que el sujeto no es null.
isFalse() Afirma que el sujeto es false.
isTrue() Afirma que el sujeto es true.
isFalsy() Afirma que el sujeto es falso. Los valores incorrectos son undefined, null, false, NaN, 0 y “' (string vacía).
isTruthy() Afirma que el sujeto es veraz. Los valores incorrectos son undefined, null, false, NaN, 0 y “' (string vacía).
isNaN() Afirma que el sujeto es el valor NaN.
isNotNaN() Afirma que el sujeto es cualquier valor además de NaN.
isInfinity() Afirma que el sujeto es Infinito positivo o negativo.
isNotInfinity() Afirma que el sujeto es cualquier valor además del infinito positivo o negativo.
isEqualTo(expected) Afirma que el sujeto es igual al valor indicado. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arrays se compara de manera recursiva.
isNotEqualTo(expected) Afirma que el sujeto no es igual al valor indicado. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arrays se compara de manera recursiva.
isAnyOf(...expected) Afirma que el sujeto es igual a uno de los valores especificados. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arrays se compara de manera recursiva.
isNoneOf(...expected) Afirma que el sujeto no es igual a ninguno de los valores especificados. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arrays se compara de manera recursiva.
isStrictlyEqualTo(expected) Afirma que el sujeto es estrictamente igual (===) al valor dado.
isNotStrictlyEqualTo(expected) Afirma que el sujeto no es estrictamente igual (!==) al valor determinado.
isGreaterThan(expected) Confirma que el sujeto es mayor que (>) el valor determinado en una comparación ordenada.
isGreaterThanOrEqualTo(expected) Confirma que el sujeto es mayor o igual que (>=) el valor determinado en una comparación ordenada.
isLessThan(expected) Confirma que el sujeto es menor que (<) el valor determinado en una comparación ordenada.
isLessThanOrEqualTo(expected) Confirma que el sujeto es menor o igual que (<=) el valor determinado en una comparación ordenada.
contains(...expected) Afirma que el sujeto es un array o una cadena que contiene todos los valores indicados en cualquier orden. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arreglos se compara de manera recursiva.
doesNotContain(...expected) Afirma que el sujeto es un array o una cadena que no contiene ninguno de los valores especificados. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arrays se compara de manera recursiva.
containsExactly(...expected) Afirma que el sujeto es un array que contiene todos los valores proporcionados en cualquier orden y ningún otro valor. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arreglos se compara de manera recursiva.
doesNotContainExactly(...expected) Afirma que el sujeto es un array que contiene un conjunto diferente de valores de los valores proporcionados en cualquier orden. Esta es una comparación de valores, no una comparación de referencia. El contenido de los objetos y los arrays se compara de manera recursiva.
hasLength(expected) Afirma que el sujeto es una matriz o una cadena con la longitud dada. La aserción siempre falla si el valor no es un array o una string.
isEmpty() Afirma que el sujeto es un array o una cadena vacía (longitud = 0). La aserción siempre falla si el valor no es un array ni una string.
isNotEmpty() Afirma que el sujeto es un array o una cadena que no está vacía (longitud > 0). La aserción siempre falla si el valor no es un array o una string.
isArray() Afirma que el tipo de sujeto es un array.
isBoolean() Afirma que el tipo de sujeto es booleano.
isFunction() Afirma que el tipo del sujeto es una función.
isNumber() Afirma que el tipo del sujeto es un número.
isObject() Afirma que el tipo de sujeto es un objeto.
isString() Afirma que el tipo de 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

Falla de inmediato la prueba actual y, si se proporciona, imprime el mensaje proporcionado.

Sintaxis

fail(opt_message);

Parámetros

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

Ejemplo

fail('This test has failed.');

mock

La API de mock te permite anular el comportamiento de las APIs de Sandboxed. Es seguro usar la API de prueba en el código de plantilla, pero no funciona cuando no está en modo de prueba. Los simulaciones se restablecen antes de cada prueba.

Sintaxis

mock(apiName, returnValue);

Parámetros

Parámetro Tipo Descripción
apiName string El nombre de la API que se va a simular; la misma cadena que se pasa a require()
returnValue cualquiera Es el valor que se muestra para la API o una 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 a la API de Sandboxed. Si returnValue no es una función, se muestra ese valor en lugar de la API de Sandboxed.

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 Code, en el entorno de pruebas actual con un objeto de datos de entrada determinado.

Sintaxis

runCode(data)

Parámetros

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

Valor que se muestra

Muestra el valor de una variable para las plantillas de variables; muestra undefined para todos los demás tipos de plantillas.

Ejemplo

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