APIs de plantillas personalizadas

APIs principales

Estas APIs, que funcionan con JavaScript en zona de pruebas, permiten crear plantillas personalizadas en Google Tag Manager. Cada API se añade con una instrucción require(); por ejemplo:

const myAPI = require('myAPI');

addEventCallback

La API addEventCallback permite registrar una función de retrollamada que se invocará al final de un evento. La retrollamada se invocará cuando se hayan ejecutado todas las etiquetas del evento o si se ha alcanzado el tiempo de espera del evento en la página. La retrollamada 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 función 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 Array Es un array de objetos de datos de etiqueta. Cada etiqueta que se haya activado durante el evento tendrá una entrada en este array. El objeto de datos de etiqueta contiene el ID de la etiqueta (id), el estado de su ejecución (status) y la hora de su ejecución (executionTime). Los datos de la etiqueta también incluyen los metadatos de etiqueta adicionales que se han configurado en la etiqueta.

Ejemplo

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

Permisos asociados

read_event_metadata


aliasInWindow

La API aliasInWindow permite crear un alias (por ejemplo, window.foo = window.bar) para poder usar las etiquetas que lo requieran. Asigna el valor del objeto window de fromPath a la clave del objeto window de toPath. Devuelve true si el proceso se realiza correctamente; de lo contrario devuelve false.

Sintaxis

aliasInWindow(toPath, fromPath)

Parámetros

Parámetro Tipo Descripción
toPath cadena Es una ruta separada por puntos que lleva al objeto window en el que se debe pegar un valor. Todos los componentes de la ruta hasta el último componente ya deben existir en el objeto window.
fromPath cadena Es una ruta separada por puntos que lleva al objeto window cuyo valor se debe copiar. Si dicho valor no existe, la operación no se llevará a cabo.

Ejemplo

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

Permisos asociados

access_globals es obligatorio tanto en toPath como en fromPath. En toPath se requiere acceso de escritura, y en fromPath, de lectura.


callInWindow

Permite llamar a funciones desde una ruta en una ubicación distinta del objeto window aplicando las políticas pertinentes. Llama a la función con unos argumentos dados en la ruta indicada en window y devuelve el valor correspondiente. Si el tipo de resultado devuelto no se puede asociar directamente a un tipo compatible con JavaScript en zona de pruebas, se devolverá undefined. Los ocho tipos compatibles con JavaScript en zona de pruebas son null, undefined, boolean, number, string, Array, Object y function. Si la ruta indicada no existe o no hace referencia a ninguna función, se devolverá undefined.

Sintaxis

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

Parámetros

Parámetro Tipo Descripción
pathToFunction cadena Es una ruta separada por puntos que lleva a la función de window a la que se debe llamar.
args * Son los argumentos que se transferirán a la función.

Permisos asociados

access_globals con el permiso execute habilitado.


callLater

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

Sintaxis

callLater(function)

Parámetros

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

copyFromDataLayer

Devuelve el valor asignado a la clave especificada en la capa de datos si ese valor es de tipo primitivo, una función o un objeto literal; de lo contrario, devuelve undefined.

Sintaxis

copyFromDataLayer(key[, dataLayerVersion])

Parámetros

Parámetro Tipo Descripción
key cadena Es la clave, en formato "a.b.c".
dataLayerVersion número Es la versión de capa de datos opcional. El valor predeterminado es 2. No se recomienda utilizar el valor 1 en absoluto.

Permisos asociados

read_data_layer


copyFromWindow

Copia una variable del objeto window. Si el valor de window no se puede asociar directamente a un tipo compatible con JavaScript en zona de pruebas, se devolverá undefined. Los ocho tipos compatibles con JavaScript en zona de pruebas son null, undefined, boolean, number, string, Array, Object y function. Devuelve el valor obtenido (y convertido).

Sintaxis

copyFromWindow(key)

Parámetros

Parámetro Tipo Descripción
key cadena Es la clave de window de la que se copiará el valor.

Permisos asociados

access_globals


createArgumentsQueue

Crea una cola que se rellena con objetos de argumentos destinada a las soluciones de etiquetado que la requieran.

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

Cuando se llama a la función que se ha creado con fnKey, envía su objeto de argumentos al array creado con arrayKey. El valor que devuelve la API es la función que se ha creado con fnKey.

Esta función requiere que fnKey y arrayKey tengan permiso de lectura y escritura en access_globals.

Ejemplo:

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

Sintaxis

createArgumentsQueue(fnKey, arrayKey)

Parámetros

Parámetro Tipo Descripción
fnKey cadena Es la ruta de window en la que se define la función, si aún no existe. En este argumento se puede usar la notación de puntos estándar. Si la ruta de la clave no existe, se obtiene una excepción. Es decir, si fnKey es 'one.two', se obtendrá una excepción.
arrayKey cadena Es la ruta de window en la que se define el array, si aún no existe. En este argumento se puede usar la notación de puntos estándar. Si la ruta de la clave no existe, se obtiene una excepción. Es decir, si arrayKey es 'one.two' y no hay un objeto global llamado 'one', se obtendrá una excepción.

Permisos asociados

access_globals


createQueue

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

Esta función requiere que arrayKey tenga permiso de lectura y escritura en access_globals.

Ejemplo:

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

Sintaxis

createQueue(arrayKey)

Parámetros

Parámetro Tipo Descripción
arrayKey cadena Es la clave de window en la que se define el array, si aún no existe. En este argumento se puede usar la notación de puntos estándar. Si la ruta de la clave no existe, se obtiene una excepción. Por ejemplo, si arrayKey es 'one.two' y no hay un objeto global llamado 'one', se obtendrá una excepción.

Permisos asociados

access_globals


decodeUri

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

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 cadena Es un URI codificado por encodeUri() o por otros medios.

Permisos asociados

Ninguno


decodeUriComponent

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

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 cadena Es un componente URI codificado por encodeUriComponent() o por otros medios.

Permisos asociados

Ninguno


encodeUri

Devuelve un URI codificado escapando los caracteres especiales. Devuelve una cadena que representa la cadena que se ha facilitado, codificada como un URI.

Ejemplo:

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

Sintaxis

encodeUri(uri)

Parámetros

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

Permisos asociados

Ninguno


encodeUriComponent

Devuelve un URI codificado escapando los caracteres especiales. Devuelve una cadena que representa la cadena que se ha facilitado, codificada como un URI.

Ejemplo:

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

Sintaxis

encodeUriComponent(str)

Parámetros

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

Permisos asociados

Ninguno


fromBase64

La API fromBase64 permite decodificar cadenas de su representación en base64. Devuelve undefined cuando se proporciona un valor no válido.

Sintaxis

fromBase64(base64EncodedString)

Parámetros

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

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno.


generateRandom

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

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 ha devuelto.
max número Es el valor potencial máximo del número entero que se ha devuelto.

Permisos asociados

Ninguno


getContainerVersion

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

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

Ejemplo

const getContainerVersion = require('getContainerVersion');
const 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

Devuelve los valores de todas las cookies con el nombre indicado.

Sintaxis

getCookieValues(name[, decode])

Parámetros

Parámetro Tipo Descripción
name cadena Es el nombre de la cookie.
decode booleano Controla si los valores de la cookie deben decodificarse con decodeURIComponent() de JavaScript. El valor predeterminado es true.

Permisos asociados

get_cookies


getQueryParameters

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

Sintaxis

getQueryParameters(queryKey[, retrieveAll])

Parámetros

Parámetro Tipo Descripción
queryKey cadena Es la clave de los parámetros de consulta que se va a leer.
retrieveAll booleano Indica si se obtienen todos los valores.

Por ejemplo, si la URL que se está utilizando en ese momento es https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo:

  • 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 objeto queryKey en las claves de consulta permitidas (o permitir cualquier clave de consulta).


getReferrerQueryParameters

La API getReferrerQueryParameters funciona igual que getQueryParameters, aunque actúa en la URL referente y no en la URL que se está utilizando en ese momento. Devuelve el primero o todos los parámetros de queryKey de la URL referente especificada. Devuelve el primer valor de queryKey o un array de valores de queryKey.

Sintaxis

getReferrerQueryParameters(queryKey[, retrieveAll])

Parámetros

Parámetro Tipo Descripción
queryKey cadena Es la clave de los parámetros de consulta que se va a leer.
retrieveAll booleano Indica si se obtienen todos los valores.

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

  • 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 objeto queryKey en las claves de consulta permitidas (o permitir cualquier clave de consulta).


getReferrerUrl

Si se especifica un tipo de componente, la API lee el objeto de documento de la URL referente y devuelve una cadena que representa una parte de dicha URL. Si no se especifica ningún componente, se devuelve la URL referente completa.

Sintaxis

getReferrerUrl([component])

Parámetros

Parámetro Tipo Descripción
component cadena Es el componente de la URL que se devolverá. Puede ser uno de estos: protocol, host, port, path, query o extension. Si component es undefined o null, o no coincide con ninguno de estos componentes, se devolverá la URL completa.

Permisos asociados

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


getTimestamp

Obsoleta. Es preferible utilizar getTimestampMillis.

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

Sintaxis

getTimestamp();

Permisos asociados

Ninguno


getTimestampMillis

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

Sintaxis

getTimestampMillis();

Permisos asociados

Ninguno


getType

Devuelve una cadena que describe el tipo de valor proporcionado. A diferencia de typeof, getType distingue entre array y object.

Sintaxis

getType(data.someField)

Notas

En esta tabla se incluyen las cadenas devueltas con cada valor:

Valor de entrada Resultado
undefined 'sin definir'
null 'nulo'
true 'booleano'
12 'número'
'string' 'cadena'
{ a: 3 } 'objeto'
[ 1, 3 ] 'array'
(x) => x + 1 'función'

Permisos asociados

Ninguno


getUrl

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

Sintaxis

getUrl(component)

Parámetros

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

Permisos asociados

get_url


injectHiddenIframe

Añade un iframe invisible a la página.

Las retrollamadas se proporcionan como instancias de función y se integran en funciones JavaScript que permiten hacer llamadas a esas instancias.

Sintaxis

injectHiddenIframe(url, onSuccess)

Parámetros

Parámetro Tipo Descripción
url cadena Es la URL que se usará como valor del atributo src del iframe.
onSuccess función Es la función a la que se llama cuando el marco se carga correctamente.

Permisos asociados

inject_hidden_iframe


injectScript

Añade una etiqueta de secuencia de comandos a la página para cargar la URL proporcionada de forma asíncrona. Las retrollamadas se proporcionan como instancias de función y se integran en funciones JavaScript que permiten hacer llamadas a esas instancias.

Sintaxis

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

Parámetros

Parámetro Tipo Descripción
url cadena Es la dirección de la secuencia de comandos que se insertará.
onSuccess función Es la función a la que se llama cuando la secuencia de comandos se carga correctamente.
onFailure función Es la función a la que se llama cuando la secuencia de comandos no se carga.
cacheToken cadena Es la cadena opcional que se utiliza para indicar que la URL proporcionada debe almacenarse en caché. Si se especifica este valor, solo se creará un elemento de secuencia de comandos para solicitar el código JavaScript. Cada vez que se intente volver a cargar la secuencia de comandos, los métodos onSuccess y onFailure proporcionados se pondrán en cola hasta que se termine de cargar.

Permisos asociados

inject_script


JSON

Devuelve un objeto que proporciona funciones JSON.

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

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

Sintaxis

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

Parámetros

JSON.parse

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

JSON.stringify

Parámetro Tipo Descripción
value cualquiera 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

Devuelve un objeto que contiene 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 proporcionado en un número (entero).

Sintaxis

makeInteger(value)

Parámetros

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

Permisos asociados

Ninguno


makeNumber

Convierte el valor en un número.

Sintaxis

makeNumber(value)

Parámetros

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

Permisos asociados

Ninguno


makeString

Devuelve el valor proporcionado como una cadena.

Sintaxis

makeString(value)

Parámetros

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

Permisos asociados

Ninguno


makeTableMap

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

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

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

en este objeto de mapa:

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

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

Sintaxis

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parámetros

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

Permisos asociados

Ninguno


Math

Un objeto que proporciona funciones matemáticas Math.

Sintaxis

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

Parámetros

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

Permisos asociados

Ninguno


parseUrl

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

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

El objeto devuelto tendrá los campos siguientes:

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

Ejemplo

const parseUrl = require('parseUrl');

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

Sintaxis

parseUrl(url);

Parámetros

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

Permisos asociados

Ninguno


queryPermission

Consulta los permisos permitidos y los restringidos. Devuelve un valor booleano: true si se da permiso y, en caso contrario, false.

Sintaxis

queryPermission(permission, functionArgs*)

Parámetros

Parámetro Tipo Descripción
permission cadena Nombre del permiso.
functionArgs cualquiera Los argumentos de función varían según el permiso que se consulta. Lee el siguiente apartado: Argumentos de función.

Argumentos de función

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

writeGlobals, readGlobals: el segundo parámetro debe ser una clave que se va a escribir o a leer.

readUrl: no se necesitan argumentos adicionales para consultar si se puede leer la URL completa. Para consultar si se puede leer un determinado componente, envía su nombre como segundo argumento:

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

Para verificar si una determinada clave de consulta se puede leer, envíala como tercer parámetro:

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

Permisos asociados

Ninguno


readCharacterSet

Devuelve el valor de document.characterSet.

Sintaxis

readCharacterSet()

Parámetros

Ninguno

Permisos asociados

read_character_set


readTitle

Devuelve el valor de document.title.

Sintaxis

readTitle()

Parámetros

Ninguno

Permisos asociados

read_title


require

Importa por nombre una función integrada. Devuelve una función o un objeto a los que se puede llamar desde el programa. Si el navegador no es compatible con la función integrada, devuelve un valor sin definir.

Sintaxis

require(name)

Parámetros

Parámetro Tipo Descripción
name cadena Es el nombre de la función que va a importarse.

Ejemplo

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

Permisos asociados

Ninguno


sendPixel

Hace una solicitud "GET" a un punto de conexión de URL determinado.

Sintaxis

sendPixel(url, onSuccess, onFailure)

Parámetros

Parámetro Tipo Descripción
url cadena Es la URL a la que se enviará el píxel.
onSuccess función Es la función a la que se llama cuando el píxel se envía correctamente.
onFailure función Es la función a la que se llama cuando el píxel no se envía.

Permisos asociados

send_pixel


setCookie

Configura o elimina una cookie con el nombre, el valor y las opciones que se indiquen.

Sintaxis

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

Parámetros

Parámetro Tipo Descripción
name cadena Es el nombre de la cookie.
value cadena Es el valor de la cookie.
options objeto Especifica los atributos "Domain", "Path", "Expires", "Max-Age", "Secure" y "SameSite". Consulta la sección Opciones que aparece más abajo.
encode booleano Determina si el valor de la cookie se codificará con encodeURIComponent() de JavaScript. El valor predeterminado es true.

Opciones

  • Domain: se define mediante la propiedad options['domain'] (si está presente). Introduce el valor 'auto' para intentar escribir la cookie utilizando el dominio más amplio posible, en función de la ubicación del documento. Si no es posible hacerlo, se probará con subdominios cada vez más específicos. Si sigue sin funcionar, se intentará escribir la cookie sin dominio. Si no se define ningún valor, se intentará escribir la cookie sin especificar su dominio. Nota: Cuando se escribe en document.cookie una cookie que no tiene un dominio específico, el user-agent de forma predeterminada utilizará como dominio de esa cookie el host donde se ubica el documento que esté en uso en ese momento.
  • Path: se define mediante options['path'] (si está presente). Cuando se escribe en document.cookie una cookie que no tiene un valor de ruta específico, el user-agent de forma predeterminada utilizará como ruta de la cookie la ruta donde se ubica el documento que esté en uso en ese momento.
  • Max-Age: se define mediante options['max-age'] (si está presente).
  • Expires: se define mediante options['expires'] (si está presente). Es una cadena de fecha en formato UTC. Para dar el formato adecuado a Date, se puede usar Date.toUTCString().
  • Secure: se define mediante options['secure'] (si está presente).
  • SameSite: se define mediante options['samesite'] (si está presente).

Permisos asociados

set_cookies


setInWindow

Asigna el valor indicado a la clave de window concreta. De forma predeterminada, este método no asignará el valor en window si ya hay otro valor. Asigna el valor true a overrideExisting para que se asigne el valor en window independientemente de si ya hay uno. Devuelve un valor booleano: true si el valor se asigna correctamente y, en caso contrario, false.

Sintaxis

setInWindow(key, value, overrideExisting)

Parámetros

Parámetro Tipo Descripción
key cadena Es la clave de window en la que se insertará el valor.
value * Es el valor que se asignará a window.
overrideExisting booleano Es el indicador que señala que el valor en cuestión se debe asignar en window, independientemente de si hay un valor.

Permisos asociados

access_globals


sha256

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

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 cadena Es la cadena que se usa para calcular el hash.
onSuccess función Es la función a la que se llama con la síntesis resultante, codificada en base64, a menos que el objeto options especifique una codificación de salida diferente.
onFailure función Es la función a la que se llama si se produce un error al calcular la síntesis o si el navegador no es compatible de forma nativa con sha256. La retrollamada se ejecuta con un objeto que contiene el nombre del error y el mensaje.
options objeto Opcional para que el objeto especifique la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding, con el valor base64 o hex.

Permisos asociados

Ninguno


templateStorage

Devuelve un objeto que contiene métodos para acceder al almacenamiento de la plantilla, que permite compartir datos entre diversas ejecuciones de una sola plantilla. Los datos almacenados en el almacenamiento de la plantilla se conservan 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 toBase64 permite codificar una cadena en una representación en base64.

Sintaxis

toBase64(input)

Parámetros

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

Ejemplo

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Permisos asociados

Ninguno.


APIs para pruebas

Estas APIs funcionan junto con pruebas de JavaScript en zona de pruebas para probar plantillas personalizadas en Google Tag Manager. Estas APIs para pruebas no necesitan una instrucción require(). Más información sobre las pruebas de plantillas personalizadas


assertApi

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

Sintaxis

assertApi(apiName)

Parámetros

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

Objetos de comparación

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

Ejemplos

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

assertThat

La API assertThat se basa en la biblioteca Truth de Google. Devuelve un objeto que se puede utilizar para comprobar de manera fluida que el valor de un sujeto es verdadero. Si no se puede hacer la verificación, la prueba se detendrá inmediatamente y se marcará como incompleta. No obstante, si no se puede hacer una prueba, los otros casos de prueba no se verán afectados.

Sintaxis

assertThat(actual, opt_message)

Parámetros

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

Objetos de comparación

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

Ejemplos

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

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

Sintaxis

fail(opt_message);

Parámetros

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

Ejemplo

fail('This test has failed.');

mock

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

Sintaxis

mock(apiName, returnValue);

Parámetros

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

Ejemplos

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

runCode

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

Sintaxis

runCode(data)

Parámetros

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

Valor devuelto

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

Ejemplo

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