Nota: Este sitio para desarrolladores se trasladará a developers.google.com/tag-platform y se redirigirá a los usuarios a esa URL hasta el 30 de septiembre del 2021.

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

`addConsentListener`

Registra la función de procesador que se ejecuta cuando cambia el estado del tipo de consentimiento especificado.

El procesador especificado se invocará cada vez que el estado del tipo de consentimiento especificado cambie de "granted" (concedido) a "denied" (denegado) o viceversa. Si el tipo de consentimiento no tiene ningún estado, se considera que es "granted". Así que, si cambia a ese estado, no se hará una llamada al procesador. Las funciones del procesador se encargan de garantizar que el código se ejecute el número de veces adecuado.

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	Tipo de consentimiento que se procesa para detectar si se producen cambios de estado.
`listener`	function	Función que se ejecuta cuando cambia el estado del tipo de consentimiento especificado.

Cuando se invoca un procesador, se le transfiere el tipo de consentimiento que ha cambiado y el nuevo valor:

Parámetro	Tipo	Descripción
`consentType`	string	Tipo de consentimiento que ha cambiado.
`granted`	boolean	Valor booleano que es "true" si el tipo de consentimiento especificado cambia a "granted".

Permisos asociados

Permiso access_consent con acceso de lectura al tipo de consentimiento.

`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`	function	Es la función que se invoca al final del evento.

El objeto eventData contiene los siguientes datos:

Nombre de clave	Tipo	Descripción
`tags`	Array	Es un array de objetos de datos de etiqueta. Cada etiqueta que se 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`	string	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`	string	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`	string	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`	function	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`	string	Es la clave, en formato "a.b.c".
`dataLayerVersion`	number	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`	string	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`	string	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`	string	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`	string	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`	string	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`	string	Es un componente URI codificado por `encodeUriComponent()` o por otros medios.

Permisos asociados

Ninguno

`encodeUri`

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

Ejemplo:

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

Sintaxis

encodeUri(uri)

Parámetros

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

Permisos asociados

Ninguno

`encodeUriComponent`

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

Ejemplo:

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 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`	string	Cadena codificada en base64.

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno

`generateRandom`

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

Sintaxis

generateRandom(min, max)

Parámetros

Parámetro	Tipo	Descripción
`min`	number	Es el valor potencial mínimo del número entero que se ha devuelto.
`max`	number	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`	string	Es el nombre de la cookie.
`decode`	boolean	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`	string	Es la clave de los parámetros de consulta que se va a leer.
`retrieveAll`	boolean	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`	string	Es la clave de los parámetros de consulta que se va a leer.
`retrieveAll`	boolean	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`	string	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`	string	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`	string	Es la URL que se usará como valor del atributo `src` del iframe.
`onSuccess`	function	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`	string	Es la dirección de la secuencia de comandos que se insertará.
`onSuccess`	function	Es la función a la que se llama cuando la secuencia de comandos se carga correctamente.
`onFailure`	function	Es la función a la que se llama cuando la secuencia de comandos no se carga.
`cacheToken`	string	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

`isConsentGranted`

Devuelve el valor "true" si el tipo de consentimiento especificado es "granted".

El tipo de consentimiento se considera concedido si se le ha asignado el valor "granted" o no se le ha asignado ninguno. Si se le asigna cualquier otro valor, se considerará que es "granted".

Desde la interfaz de Tag Manager, puedes configurar los ajustes de la etiqueta para que se active siempre. Si una etiqueta configurada para activarse siempre usa esta API, se considera que se ha dado consentimiento y se devolverá 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	Tipo de consentimiento del que se va a comprobar el estado.

Permisos asociados

Permiso access_consent con acceso de lectura al tipo de consentimiento.

`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	any	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	any	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]`	any	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`	any	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`	any	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`	any	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`	string	Es el nombre de la columna cuyos valores se convertirán en claves dentro del objeto `Map` convertido.
`valueColumnName`	string	Es el nombre de la columna cuyos valores se convertirán en valores dentro del objeto `Map` convertido.

Permisos asociados

Ninguno

`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 URLs con formato incorrecto. En el caso de las URLs con formato correcto, los campos que no estén presentes en la cadena de URL tendrán un valor de cadena vacía o, en el caso de searchParams, un objeto vacío.

El objeto devuelto tendrá los campos siguientes:

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

Ejemplo

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc: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 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`	string	Nombre del permiso.
`functionArgs`	any	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`	string	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`	string	Es la URL a la que se enviará el píxel.
`onSuccess`	function	Es la función a la que se llama cuando el píxel se envía correctamente.
`onFailure`	function	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`	string	Es el nombre de la cookie.
`value`	string	Es el valor de la cookie.
`options`	object	Especifica los atributos "Domain", "Path", "Expires", "Max-Age", "Secure" y "SameSite". Consulta la sección Opciones que aparece más abajo.
`encode`	boolean	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

`setDefaultConsentState`

Asigna (o actualiza) el estado de consentimiento predeterminado en la página.

Ejemplo:

const setDefaultConsentState = require('setDefaultConsentState');

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

Sintaxis

setDefaultConsentState(consentSettings)

Parámetros

Parámetro	Tipo	Descripción
`consentSettings`	object	Objeto que define el estado predeterminado de los tipos de consentimiento especificados.

El objeto consentSettings es un mapeado de cadenas de tipo de consentimiento arbitrarias a uno de los siguientes valores: 'granted' o 'denied'. Admite los siguientes valores:

Nombre de clave	Tipo	Descripción
`consentType`	string	El valor de cada tipo de consentimiento puede ser `'granted'` o `'denied'`. Cualquier valor que no sea `'granted'` se considerará `'denied'`. Asignar el valor `undefined` a un tipo de consentimiento, no tendrá ningún efecto sobre su valor anterior.
`region`	Array	Array opcional de códigos de región que especifica la región a la que se aplica la configuración de consentimiento. Los códigos de región se expresan mediante el formato ISO 3166-2 de país o de subdivisiones.
`wait_for_update`	number	Especifica un valor en milisegundos que controla el tiempo de espera antes de que se envíen los datos. Se usa con herramientas de consentimiento que se cargan de forma asíncrona.

Permisos asociados

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

`setInWindow`

Asigna el valor indicado a la clave de window determinada. 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`	string	Es la clave de `window` en la que se insertará el valor.
`value`	*	Es el valor que se asignará a `window`.
`overrideExisting`	boolean	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`	string	Es la cadena que se usa para calcular el hash.
`onSuccess`	function	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`	function	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`	object	Opcional para que el objeto especifique la codificación de salida. Si se especifica, el objeto debe contener la clave `outputEncoding`, con el valor `base64` o `hex`.

Permisos asociados

Ninguno

`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`	string	Cadena que se codificará.

Ejemplo

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Permisos asociados

Ninguno

`updateConsentState`

Actualiza el estado de los tipos de consentimiento especificados.

Ejemplo:

const updateConsentState = require('updateConsentState');

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

Sintaxis

updateConsentState(consentSettings)

Parámetros

Parámetro	Tipo	Descripción
`consentSettings`	object	Objeto que actualiza el estado de los tipos de consentimiento especificados.

El objeto consentSettings es un mapeado de cadenas de tipo de consentimiento arbitrarias a uno de los siguientes valores: 'granted' o 'denied'. Admite los siguientes valores:

Nombre de clave	Tipo	Descripción
`consentType`	string	El valor de cada tipo de consentimiento puede ser `'granted'` o `'denied'`. Cualquier valor que no sea `'granted'` se considerará `'denied'`. Asignar el valor `undefined` a un tipo de consentimiento, no tendrá ningún efecto sobre su valor anterior.

Permisos asociados

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

APIs de prueba

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`	string	Nombre de la API que se va a comprobar. Es la misma cadena que se ha enviado a `require()`.

Objetos de comparación

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

Ejemplos

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

`assertThat`

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

Sintaxis

assertThat(actual, opt_message)

Parámetros

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

Objetos de comparación

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

Ejemplos

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

`fail`

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

Sintaxis

fail(opt_message);

Parámetros

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

Ejemplo

fail('This test has failed.');

`mock`

La API mock permite anular el comportamiento de las 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`	string	Nombre de la API que se debe usar como ejemplo. Es la misma cadena que se ha enviado a `require()`.
`returnValue`	any	Valor que se debe devolver de la API o la función a la que se llama en lugar de la API. Si `returnValue` es una función, se llama a esa función en lugar de la API en 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`	object	Es el objeto de datos que se va a usar en la prueba.

Valor devuelto

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

Ejemplo

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