APIs de plantillas personalizadas

APIs principales

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

const myAPI = require('myAPI');

addConsentListener

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

Se invocará el objeto de escucha determinado cada vez que el estado del tipo de consentimiento especificado cambie de rechazado a otorgado o de otorgado a rechazado. 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 no establecido a otorgado. Las funciones de objeto de escucha se encargarán de garantizar que su código se ejecute la cantidad correcta 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 Es el tipo de consentimiento en el que se deben detectar los cambios de estado.
listener function Es la función que se ejecutará cuando cambie el estado del tipo de consentimiento especificado.

Cuando se invoque un objeto de escucha, se le pasará el tipo de consentimiento que se está cambiando y el valor nuevo de ese tipo de consentimiento:

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

Permisos asociados

Permiso 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 del evento en la página. Se pasan dos valores a la devolución de llamada: 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 Es la función que se invoca 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 etiqueta. Cada etiqueta que se active durante el evento tendrá una entrada en este array. El objeto de datos de etiqueta contiene el ID de la etiqueta (id), su estado de ejecución (status) y su hora 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 del objeto window que se encuentra en fromPath a la clave del objeto window en toPath. Muestra true si se realiza correctamente, y false en caso contrario.

Sintaxis

aliasInWindow(toPath, fromPath)

Parámetros

Parámetro Tipo Descripción
toPath string Es una ruta de acceso separada por puntos en el objeto window al que se debe copiar un valor. Todos los componentes de la ruta de acceso hasta el último componente ya deben existir en el objeto window.
fromPath string Es 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

Se requiere access_globals 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 la política. Llama a la función en la ruta de acceso determinada en window con los argumentos determinados y muestra el valor. Si el tipo que se muestra no se puede asignar directamente a un tipo compatible con JavaScript en zona de pruebas, se mostrará undefined. Los ocho tipos admitidos en JavaScript con zona de pruebas son null, undefined, boolean, number, string, Array, Object y function. Si la ruta de acceso proporcionada 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 Es una ruta de acceso separada por puntos a la función en window a la que se llama.
args * Son los 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 realice 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: el valor que se encuentra en la clave determinada si es un tipo primitivo, una función o un objeto literal, o undefined de lo contrario.

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 JavaScript en zona de pruebas, se mostrará undefined. Los ocho tipos admitidos en JavaScript con zona de pruebas 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 Es la clave en window de la que se debe copiar el valor.

Permisos asociados

access_globals

createArgumentsQueue

Crea una fila que se propaga con objetos de argumentos, en función de las soluciones de etiquetas que lo requieran.

Crea una función en el alcance global (es decir, window) con el argumento fnKey (la 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 argumentos al array creado en arrayKey. El valor que muestra 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 donde se establece la función, si aún no existe. Este argumento admite la notación de punto estándar. Si la ruta de la clave no existe, se arroja una excepción. Es decir, si fnKey es 'one.two', arrojará una excepción.
arrayKey string Es la ruta de acceso en window donde se establece el array, si aún no existe. Este argumento admite la notación de punto estándar. Si la ruta de la clave no existe, se arroja 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 en window donde se establece el array, si aún no existe. Este argumento admite la notación de punto estándar. Si la ruta de la clave no existe, se arroja 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 los caracteres codificados en el URI proporcionado. Devuelve una cadena 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 que se codificó con encodeUri() o con otros medios.

Permisos asociados

Ninguno

decodeUriComponent

Decodifica los caracteres codificados en el componente de URI proporcionado. Muestra una cadena que representa el componente de URI decodificado. Muestra undefined cuando se proporciona 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 que se codificó con encodeUriComponent() o con otros medios.

Permisos asociados

Ninguno

encodeUri

Muestra un identificador uniforme de recursos (URI) codificado con escape de caracteres especiales. Muestra una cadena que representa la cadena proporcionada codificada como un URI. Muestra undefined cuando se proporciona una entrada no válida (un sustituto único).

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

Ninguno

encodeUriComponent

Muestra un identificador uniforme de recursos (URI) codificado con escape de caracteres especiales. Muestra una cadena que representa la cadena proporcionada codificada como un URI. Muestra undefined cuando se proporciona una entrada no válida (un sustituto único).

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

Ninguno

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 Es una cadena codificada en base64.

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno

generateRandom

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

Sintaxis

generateRandom(min, max)

Parámetros

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

Permisos asociados

Ninguno

getContainerVersion

Devuelve 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 determinado.

Sintaxis

getCookieValues(name[, decode])

Parámetros

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

Permisos asociados

get_cookies

getQueryParameters

Devuelve el primer parámetro o todos los parámetros de 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 Es la clave para leer de los parámetros de consulta.
retrieveAll booleano 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, haz 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 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 primer parámetro o todos los parámetros del queryKey del referente determinado. 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 Es la clave para leer de los parámetros de consulta.
retrieveAll booleano 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 queryKey en las claves de consulta permitidas (o permitir cualquier clave de consulta).

getReferrerUrl

Dado un tipo de componente, la API lee el objeto de documento del referente y muestra una cadena que representa una parte del referente. 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 Es el componente que se muestra desde la URL. Puede ser una de las siguientes opciones: protocol, host, port, path, query, extension. Si component es undefined, null o no coincide con uno de estos componentes, se mostrará la URL completa.

Permisos asociados

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

getTimestamp

Obsoleto. Se prefiere getTimestampMillis.

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

Sintaxis

getTimestamp();

Permisos asociados

Ninguno

getTimestampMillis

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

Sintaxis

getTimestampMillis();

Permisos asociados

Ninguno

getType

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

Sintaxis

getType(data.someField)

Notas

En la siguiente tabla, se muestran las cadenas que se devuelven para cada valor de entrada.

Valor de entrada Resultado
undefined 'undefined'
null 'null'
true 'boolean'
12 'number'
'string' 'string'
{ a: 3 } 'object'
[ 1, 3 ] 'array'
(x) => x + 1 'function'

Permisos asociados

Ninguno

getUrl

Devuelve una cadena que representa toda o una parte de la URL actual, dado un tipo de componente y algunos parámetros de configuración.

Sintaxis

getUrl(component)

Parámetros

Parámetro Tipo Descripción
component string Es el componente que se muestra 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 uno de estos componentes, se mostrará todo el valor de href.

Permisos asociados

get_url

gtagSet

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

Por ejemplo, si una etiqueta activada en Inicialización de consentimiento la llama, la actualización se aplicará antes de que se procese el evento de inicialización. Algunos ejemplos serían ads_data_redaction configurado como true o false, o url_passthrough configurado como 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 sus propiedades contenedoras.

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 simple, la API verificará el permiso de escritura para todas las claves aplanadas dentro de ese objeto, p.ej., para gtagSet({foo: {bar: 'baz'}}), la API verificará el permiso de escritura para foo.bar.

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

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

injectHiddenIframe

Agrega un iframe invisible a la página.

Las devoluciones de llamada se proporcionan como instancias de función y se unen en funciones de JavaScript que las llaman.

Sintaxis

injectHiddenIframe(url, onSuccess)

Parámetros

Parámetro Tipo Descripción
url string Es la URL que se usará como valor del atributo src del iframe.
onSuccess function Se llama cuando el marco 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 callbacks se proporcionan como instancias de función y se unen en funciones de JavaScript que las llaman.

Sintaxis

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

Parámetros

Parámetro Tipo Descripción
url string Es 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 secuencia de comandos para solicitar el código JavaScript. Cualquier intento adicional de carga hará que los métodos onSuccess y onFailure dados se pongan en cola hasta que se cargue la secuencia de comandos.

Permisos asociados

inject_script

isConsentGranted

Muestra verdadero si se otorga el tipo de consentimiento especificado.

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

La interfaz de usuario de Tag Manager para la configuración de etiquetas ofrecerá una opción para que se active siempre. Si una etiqueta con la opción de activación siempre activada usa esta API, se considera que se otorgó el consentimiento y se mostrará true, independientemente del estado real del 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 cuyo estado se debe verificar.

Permisos asociados

Permiso 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 describe la cadena. Si no se puede analizar el valor (p.ej., JSON con el 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 cadena JSON. Si el valor no se puede analizar (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 Es el valor que se convertirá. Si el valor no es una cadena, la entrada se forzará a una cadena.

JSON.stringify

Parámetro Tipo Descripción
valor cualquiera Es el valor que se 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 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 determinado en un número (número entero).

Sintaxis

makeInteger(value)

Parámetros

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

Permisos asociados

Ninguno

makeNumber

Convierte el valor determinado en un número.

Sintaxis

makeNumber(value)

Parámetros

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

Permisos asociados

Ninguno

makeString

Muestra el valor determinado como una cadena.

Sintaxis

makeString(value)

Parámetros

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

Permisos asociados

Ninguno

makeTableMap

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

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

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

en un mapa:

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

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

Sintaxis

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parámetros

Parámetro Tipo Descripción
tableObj Lista Es el objeto de tabla que se convertirá. Es una lista de mapas en la que cada Map representa una fila de 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 Es el 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

Ninguno

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

Ninguno

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 las propiedades enumerables de un objeto determinado en el mismo orden que lo haría un bucle for...in.... Si el valor de entrada no es un objeto, se convertirá en uno.

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

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

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 evita que se le agreguen propiedades nuevas, que se quiten las propiedades existentes ni que se cambien 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 delete de la biblioteca estándar. Quita la clave determinada del objeto, a menos que esté inmovilizado. Al igual que el operador delete 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, difiere del operador delete de la biblioteca estándar de las siguientes maneras:

  • keyToDelete no puede ser una cadena 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 ninguna propiedad 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 Es el objeto cuyas claves se enumerarán. Si la entrada no es un objeto, se le asignará uno.

Object.values

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

Object.entries

Parámetro Tipo Descripción
objectInput cualquiera El objeto cuyos pares clave-valor se enumerarán. Si la entrada no es un objeto, se convertirá en uno.

Object.freeze

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

Object.delete

Parámetro Tipo Descripción
objectInput cualquiera Es el objeto cuya clave se borrará.
keyToDelete string 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 cualquier URL con formato incorrecto. En el caso de las URLs con el formato correcto, los campos que no estén presentes en la cadena de URL tendrán un valor de cadena vacía o, en el caso de searchParams, un objeto vacío.

El objeto que se devuelve 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

Ninguno

queryPermission

Consulta los permisos permitidos y reducidos. Muestra un valor booleano: true si se otorga un permiso, false en caso contrario.

Sintaxis

queryPermission(permission, functionArgs*)

Parámetros

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

Argumentos de funciones

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 está escribiendo o leyendo.

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

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

Para verificar si una clave de consulta específica es legible, pásala como tercer parámetro:

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

Permisos asociados

Ninguno

readCharacterSet

Muestra el valor de document.characterSet.

Sintaxis

readCharacterSet()

Parámetros

Ninguno

Permisos asociados

read_character_set

readTitle

Muestra el valor de document.title.

Sintaxis

readTitle()

Parámetros

Ninguno

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 Es el nombre de la función que se importará.

Ejemplo

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

Permisos asociados

Ninguno

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 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 no se puede cargar el píxel. Nota: Incluso si la solicitud se envía correctamente, onFailure puede ejecutarse 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 Es el nombre de la cookie.
value string Es el valor de la cookie.
options objeto Especifica los atributos Domain, Path, Expires, Max-Age, Secure y SameSite. (Consulta Opciones a continuación).
encode booleano Controla si el valor de la cookie se debe codificar con encodeURIComponent() de JavaScript. La configuración predeterminada es true.

Opciones

  • 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, intentará subdominios más específicos de forma consecutiva. Si todos fallan, intentará escribir la cookie sin un dominio. Si no se establece ningún valor, se intentará escribir la cookie sin especificar un dominio. Nota: Cuando se escribe una cookie sin un dominio especificado en document.cookie, el usuario-agente establecerá de forma predeterminada el dominio de la cookie en el host de la ubicación del documento actual.
  • Ruta: Establecida por options['path'], si está presente. Cuando se escribe una cookie sin una ruta especificada en document.cookie, el usuario-agente establecerá de forma predeterminada la ruta de la cookie en la ruta de la ubicación del documento actual.
  • Max-Age: Establecido por options['max-age'], si está presente.
  • Expires: Establecido por options['expires'], si está presente. Si está presente, debe ser una cadena de fecha con formato UTC. Date.toUTCString() se puede usar para dar formato a un Date para este parámetro.
  • Secure: Establecido 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 se complete el procesamiento del evento actual y de las etiquetas que activó (o se alcance el tiempo de espera de procesamiento de etiquetas). Se garantiza que la actualización se procesará en este contenedor antes que 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 Es 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 una de '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 en "granted" o "denied". Cualquier valor que no sea "granted" se tratará como "denied". Establecer el valor en "undefined" no tendrá ningún efecto en su valor anterior.
region Matriz Es un array opcional de códigos de región 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 en milisegundos para controlar cuánto tiempo se debe esperar antes de enviar los datos. Se usa con herramientas de consentimiento que se cargan de forma asíncrona.

Permisos asociados

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

setInWindow

Establece el valor determinado en window en la clave determinada. De forma predeterminada, este método no establecerá el valor en window si ya hay un valor presente. Establece overrideExisting en true para establecer el valor en window, independientemente de la presencia de un valor existente. Muestra un valor booleano: true si el valor se estableció correctamente y false en caso contrario.

Sintaxis

setInWindow(key, value, overrideExisting)

Parámetros

Parámetro Tipo Descripción
key string Es la clave en window en la que se colocará el valor.
value * Es el valor que se establecerá en window.
overrideExisting booleano La marca que indica ese valor se debe establecer en window, sin importar si hay un valor allí o no.

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 calculará 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 tiene compatibilidad 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 Objeto de opciones opcional para especificar la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding con el valor base64 o hex.

Permisos asociados

Ninguno

templateStorage

Muestra un objeto con métodos para acceder al almacenamiento de plantillas. El almacenamiento de plantillas permite que los datos se compartan entre las ejecuciones de una sola plantilla. Los datos almacenados en el almacenamiento de plantillas persisten durante la vida útil 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 cadena 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 se complete el procesamiento del evento actual y de las etiquetas que activó (o se alcance el tiempo de espera de procesamiento de etiquetas). Se garantiza que la actualización se procesará en este contenedor antes que 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 una de '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 en "otorgado" o "rechazado". Cualquier valor que no sea "granted" se tratará como "denied". Establecer el valor en “undefined” no tendrá ningún efecto en su valor anterior.

Permisos asociados

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

APIs de prueba

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

assertApi

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

Sintaxis

assertApi(apiName)

Parámetros

Parámetro Tipo Descripción
apiName string Es el nombre de la API que se debe verificar, la misma cadena que se pasa a require().

Matcher

  • 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 el modelo de la biblioteca [Truth] de Google. Muestra un objeto que se puede usar para hacer afirmaciones con fluidez sobre el valor de un sujeto. Una falla de aserción detendrá la prueba de inmediato y la marcará como fallida. Sin embargo, una falla en una prueba no afectará a otros casos de prueba.

Sintaxis

assertThat(actual, opt_message)

Parámetros

Parámetro Tipo Descripción
actual cualquiera Es el valor que se usará en las verificaciones fluidas.
opt_message string Es un mensaje opcional para imprimir si falla la aserción.

Matcher

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

Hace que la prueba actual falle de inmediato y, si se proporciona, imprime el mensaje determinado.

Sintaxis

fail(opt_message);

Parámetros

Parámetro Tipo Descripción
opt_message string Es el 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 en zona de pruebas. La API simulada es segura para usar en el código de plantilla, pero solo funciona en modo de prueba. Las simulaciones se restablecen antes de que se ejecute cada prueba.

Sintaxis

mock(apiName, returnValue);

Parámetros

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

Ejemplos

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

mockObject

La API de mockObject te permite anular el comportamiento de las APIs en zona de pruebas que muestran un objeto. La API es segura para usar en el código de plantilla, pero solo funciona en modo de prueba. Las simulaciones se restablecen antes de que se ejecute cada prueba.

Sintaxis

mockObject(apiName, objectMock);

Parámetros

Parámetro Tipo Descripción
apiName string Es el nombre de la API que se simulará; es la misma cadena que se pasa a require().
objectMock objeto Es el valor que se mostrará para la API o una función a la que se llama en lugar de la API. Debe ser un objeto.

Ejemplos

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

Ejecuta el código de la plantilla, es decir, el contenido de la pestaña Code, en el entorno de prueba 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 plantillas de variables. Muestra undefined para todos los demás tipos de plantillas.

Ejemplo

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