APIs de plantillas personalizadas

APIs principales

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

const myAPI = require('myAPI');

addConsentListener

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

Se invocará el objeto de escucha proporcionado 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 un tipo de consentimiento no establecido se actualiza a otorgado. Las funciones de escucha se encargarán de garantizar que su código se ejecute la cantidad de veces adecuada.

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

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

Permisos asociados

Permiso de 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 hayan ejecutado todas las etiquetas del evento o si se alcanza un tiempo de espera del evento en la página. La devolución de llamada recibe dos valores: el ID del contenedor que invoca la función y un objeto que contiene información sobre el evento.

Sintaxis

addEventCallback(callback)

Parámetros

El objeto eventData contiene los siguientes datos:

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), lo 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. Devuelve true si se ejecuta correctamente; de lo contrario, devuelve false.

Sintaxis

aliasInWindow(toPath, fromPath)

Parámetros

Ejemplo

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

Permisos asociados

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

callInWindow

Te permite llamar a funciones desde una ruta de acceso 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 devuelve el valor. Si el tipo de devolución no se puede asignar directamente a un tipo admitido en JavaScript en zona de pruebas, se devolverá undefined. Los ocho tipos admitidos en JavaScript en 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 devolverá undefined.

Sintaxis

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

Parámetros

Permisos asociados

access_globals con el permiso execute habilitado

callLater

Programa una llamada a una función para que se produzca de forma asíncrona. Se llamará a la función después de que se muestre el código actual. Esto equivale a setTimeout(<function>, 0).

Sintaxis

callLater(function)

Parámetros

copyFromDataLayer

Devuelve el valor que se le asignó 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 literal de objeto, o undefined en otros casos.

Sintaxis

copyFromDataLayer(key[, dataLayerVersion])

Parámetros

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 admitido en JavaScript en zona de pruebas, se devolverá undefined. Los ocho tipos admitidos en JavaScript en zona de pruebas son null, undefined, boolean, number, string, Array, Object y function. Devuelve el valor recuperado (y forzado).

Sintaxis

copyFromWindow(key)

Parámetros

Permisos asociados

access_globals

createArgumentsQueue

Crea una fila que se completa con objetos de argumentos, en apoyo de las soluciones de etiquetas que lo requieren.

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

Cuando se llama a la función creada en fnKey, se inserta su objeto de argumentos en el array creado en arrayKey. El valor que devuelve la API es la función creada en fnKey.

Esta función requiere el parámetro de 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

Permisos asociados

access_globals

createQueue

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

Esta función requiere el parámetro de 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

Permisos asociados

access_globals

decodeUri

Decodifica los caracteres codificados en el URI proporcionado. Devuelve una cadena que representa el URI decodificado. Devuelve 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

Permisos asociados

Ninguno

decodeUriComponent

Decodifica los caracteres codificados en el componente de URI proporcionado. Devuelve una cadena que representa el componente de URI decodificado. Devuelve 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

Permisos asociados

Ninguno

encodeUri

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

Ejemplo:

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

Sintaxis

encodeUri(uri)

Parámetros

Permisos asociados

Ninguno

encodeUriComponent

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

Ejemplo:

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

Sintaxis

encodeUriComponent(str)

Parámetros

Permisos asociados

Ninguno

fromBase64

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

Sintaxis

fromBase64(base64EncodedString)

Parámetros

Ejemplo

const fromBase64 = require('fromBase64');

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

Permisos asociados

Ninguno

generateRandom

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

Sintaxis

generateRandom(min, max)

Parámetros

Permisos asociados

Ninguno

getContainerVersion

Devuelve un objeto que contiene datos sobre el contenedor actual. El objeto devuelto 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

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

Sintaxis

getCookieValues(name[, decode])

Parámetros

Permisos asociados

get_cookies

getQueryParameters

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

Sintaxis

getQueryParameters(queryKey[, retrieveAll])

Parámetros

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

• 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 funciona de la misma manera que getQueryParameters, excepto que actúa sobre la URL de referencia en lugar de la URL actual. Devuelve el primer parámetro o todos los parámetros del queryKey del sitio de referencia determinado. Devuelve el primer valor de queryKey o un array de valores de queryKey.

Sintaxis

getReferrerQueryParameters(queryKey[, retrieveAll])

Parámetros

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

• 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 búsqueda permitidas (o permitir cualquier clave de búsqueda).

getReferrerUrl

Dada una cadena de texto que representa un tipo de componente, la API lee el objeto del documento para el sitio de referencia y devuelve una cadena que representa una parte del sitio de referencia. Si no se especifica ningún componente, se devuelve la URL de referencia completa.

Sintaxis

getReferrerUrl([component])

Parámetros

Permisos asociados

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

getTimestamp

Obsoleto. Es preferible usar getTimestampMillis.

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

Sintaxis

getTimestamp();

Permisos asociados

Ninguno

getTimestampMillis

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

Sintaxis

getTimestampMillis();

Permisos asociados

Ninguno

getType

Devuelve 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 enumeran las cadenas que se devuelven para cada valor de entrada.

Permisos asociados

Ninguno

getUrl

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

Sintaxis

getUrl(component)

Parámetros

Permisos asociados

get_url

gtagSet

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

Por ejemplo, si una etiqueta activada en Inicialización de consentimiento llama a este método, la actualización se aplicará antes de que se procese el evento de inicialización. Por ejemplo, ads_data_redaction se puede establecer en true o false, o bien url_passthrough se puede establecer en true o false.

Ejemplos:

const gtagSet = require('gtagSet');

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

Sintaxis

gtagSet(object)

Parámetros

Permisos asociados

write_data_layer verifica el permiso de escritura en dataLayer para todas las claves especificadas. Si la entrada para 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 para gtagSet es una clave y algún valor de objeto no simple, la API verificará el permiso de escritura para esa clave, p.ej., para gtagSet('abc', true) , la API verificará el 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 funciones y se encapsulan en funciones de JavaScript que las llaman.

Sintaxis

injectHiddenIframe(url, onSuccess)

Parámetros

Permisos asociados

inject_hidden_iframe

injectScript

Agrega una etiqueta de secuencia de comandos a la página para cargar la URL determinada de forma asíncrona. Las devoluciones de llamada se proporcionan como instancias de funciones y se encapsulan en funciones de JavaScript que las llaman.

Sintaxis

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

Parámetros

Permisos asociados

inject_script

isConsentGranted

Devuelve verdadero si se otorgó 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ó en absoluto. 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 siempre se activen. Si una etiqueta con la opción de activación siempre habilitada usa esta API, se considera que se otorgó el 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

Permisos asociados

Permiso de access_consent con acceso de lectura para el tipo de consentimiento.

JSON

Devuelve 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 el valor no se puede analizar (p.ej., JSON con formato incorrecto), la función devolverá undefined. Si el valor de entrada no es una cadena, se forzará a que sea 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 devolverá undefined.

Sintaxis

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

Parámetros

JSON.parse

JSON.stringify

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

Permisos asociados

logging

makeInteger

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

Sintaxis

makeInteger(value)

Parámetros

Permisos asociados

Ninguno

makeNumber

Convierte el valor proporcionado en un número.

Sintaxis

makeNumber(value)

Parámetros

Permisos asociados

Ninguno

makeString

Devuelve el valor proporcionado como una cadena.

Sintaxis

makeString(value)

Parámetros

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

Devuelve un Object: El Map convertido si se le agregaron pares clave-valor o null en caso contrario.

Sintaxis

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parámetros

Permisos asociados

Ninguno

Math

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

Devuelve un objeto que proporciona métodos Object.

El método keys() proporciona el comportamiento de Object.keys() de la biblioteca estándar. Devuelve un array de los nombres de las propiedades enumerables propias de un objeto determinado en el mismo orden en que lo haría un bucle for...in.... Si el valor de entrada no es un objeto, se forzará a que lo sea.

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

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

El método freeze() proporciona el comportamiento de Object.freeze() de la biblioteca estándar. Un objeto congelado ya no se puede cambiar. Congelar un objeto impide que se le agreguen propiedades nuevas, que se quiten propiedades existentes y que se cambien los valores de las propiedades existentes. freeze() devuelve el mismo objeto que se pasó. Un argumento primitivo o nulo se tratará como si fuera un objeto inmutable y se devolverá.

El método delete() proporciona el comportamiento del operador de eliminación de la biblioteca estándar. Quita la clave proporcionada del objeto, a menos que el objeto esté inmovilizado. Al igual que el operador de eliminación de la biblioteca estándar, devuelve true si el primer valor de entrada (objectInput) es un objeto que no está inmovilizado, incluso si el segundo valor de entrada (keyToDelete) especifica una clave que no existe. En todos los demás casos, devuelve false. Sin embargo, se diferencia del operador de eliminación de la biblioteca estándar de las siguientes maneras:

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

Sintaxis

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

Parámetros

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

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

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

Esta API devolverá 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 el valor de una cadena vacía o, en el caso de searchParams, un objeto vacío.

El objeto devuelto tendrá los siguientes campos:

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

Ejemplo

const parseUrl = require('parseUrl');

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

Sintaxis

parseUrl(url);

Parámetros

Permisos asociados

Ninguno

queryPermission

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

Sintaxis

queryPermission(permission, functionArgs*)

Parámetros

Argumentos de la función

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

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

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, pasa la clave de consulta como el tercer parámetro:

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

Permisos asociados

Ninguno

readAnalyticsStorage

Recupera los datos almacenados para las estadísticas y devuelve un objeto con client_id y sessions.

• client_id: Es una cadena que representa el ID del cliente que se usa para las estadísticas.
• sessions: Es un array de objetos que contiene información sobre las sesiones actuales. Cada objeto incluye lo siguiente:
  • measurement_id: Es una cadena que representa el ID de medición del destino de Analytics.
  • session_id: Es una cadena que representa la marca de tiempo que identifica la sesión actual.
  • session_number: Es un número que representa el recuento de sesiones que un usuario inició hasta la sesión actual.

Sintaxis

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

Parámetros

Permisos asociados

read_analytics_storage

Ejemplo

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

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 una función integrada por su nombre. Devuelve una función o un objeto que se puede llamar desde tu programa. Devuelve undefined cuando el navegador no admite la función integrada.

Sintaxis

require(name)

Parámetros

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

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

Opciones

• Dominio: Se establece con 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 falla, intentará con subdominios cada vez más específicos. Si todos esos intentos 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 agente de usuario establecerá de forma predeterminada el dominio de la cookie en el host de la ubicación del documento actual.
• Ruta de acceso: La establece 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.
• Vencimiento: 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: Se establece con options['secure'], si está presente.
• SameSite: Establecido por options['samesite'], si está presente.

Permisos asociados

set_cookies

setDefaultConsentState

Envía una actualización del consentimiento predeterminada a la capa de datos para que se procese lo antes posible después de que finalice el evento actual y todas las etiquetas que activó (o se alcance el tiempo de espera del procesamiento de etiquetas). Se garantiza que la actualización se procesará en este contenedor antes que cualquier elemento en cola de 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

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

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. Devuelve un valor booleano: true si el valor se estableció correctamente y false en caso contrario.

Sintaxis

setInWindow(key, value, overrideExisting)

Parámetros

Permisos asociados

access_globals

sha256

Calcula el resumen SHA-256 de la entrada y llama a 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

Permisos asociados

Ninguno

templateStorage

Devuelve 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 de base64.

Sintaxis

toBase64(input)

Parámetros

Ejemplo

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Permisos asociados

Ninguno

updateConsentState

Envía una actualización del consentimiento a la capa de datos para que se procese lo antes posible después de que finalice el procesamiento del evento actual y de las etiquetas que activó (o cuando se alcance el tiempo de espera del procesamiento de la etiqueta). 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

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

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 crear pruebas de plantillas personalizadas en Google Tag Manager. Estas APIs de prueba no necesitan una declaración de require(). Obtén más información sobre las pruebas de plantillas personalizadas.

assertApi

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

Sintaxis

assertApi(apiName)

Parámetros

Matchers

• 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 modela según la biblioteca [Truth] de Google. Devuelve un objeto que se puede usar para realizar aserciones de forma fluida sobre el valor de un sujeto. Si falla una aserción, la prueba se detendrá de inmediato y se marcará como fallida. Sin embargo, si falla una prueba, no se verán afectados otros casos de prueba.

Sintaxis

assertThat(actual, opt_message)

Parámetros

Matchers

Ejemplos

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

fail

Falla inmediatamente la prueba actual y, si se proporciona, imprime el mensaje determinado.

Sintaxis

fail(opt_message);

Parámetros

Ejemplo

fail('This test has failed.');

mock

La API de mock te permite anular el comportamiento de las APIs de Sandboxed. La API de simulación se puede usar de forma segura en el código de la plantilla, pero solo funciona en el modo de prueba. Los simulacros se restablecen antes de que se ejecute cada prueba.

Sintaxis

mock(apiName, returnValue);

Parámetros

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 de Sandboxed que devuelven un objeto. La API se puede usar de forma segura en el código de la plantilla, pero solo funciona en el modo de prueba. Los simulacros se restablecen antes de que se ejecute cada prueba.

Sintaxis

mockObject(apiName, objectMock);

Parámetros

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 Código, en el entorno de prueba actual con un objeto de datos de entrada determinado.

Sintaxis

runCode(data)

Parámetros

Valor que se muestra

Devuelve el valor de una variable para las plantillas de variables y undefined para todos los demás tipos de plantillas.

Ejemplo

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