APIs de modelo personalizado

APIs principais

Essas APIs funcionam com JavaScript no modo sandbox para criar modelos personalizados no Gerenciador de tags do Google. Cada API é adicionada com uma instrução require(), por exemplo:

const myAPI = require('myAPI');

`addConsentListener`

Registra uma função de listener a ser executada quando o estado do tipo de consentimento especificado muda.

O listener fornecido será invocado sempre que o estado desse tipo de consentimento mudar de "negado" para "concedido" ou vice-versa. Um tipo de consentimento sem estado é considerado concedido, portanto, o listener não será chamado se um tipo de consentimento não definido for atualizado para "concedido". As funções do listener serão responsáveis por garantir a execução do código quantas vezes for adequado.

Exemplo:

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

Sintaxe

addConsentListener(consentType, listener)

Parâmetros

Parâmetro	Tipo	Descrição
`consentType`	string	Tipo de consentimento para detectar as mudanças de estado.
`listener`	função	A função a ser executada quando o estado do tipo de consentimento especificado mudar.

Quando um listener é invocado, serão transmitidos o tipo de consentimento que está sendo alterado e o novo valor desse tipo:

Parâmetro	Tipo	Descrição
`consentType`	string	O tipo de consentimento que está sendo alterado.
`granted`	booleano	Um booleano é "true" quando o tipo de consentimento especificado está sendo alterado para "concedido".

Permissões associadas

access_consent com acesso de leitura ao tipo de consentimento.

`addEventCallback`

A API addEventCallback permite registrar uma função de callback que será invocada ao fim de um evento. O callback será chamado quando todas as tags do evento forem executadas ou se o tempo limite do evento na página for atingido. Ele recebe dois valores: o ID do contêiner que invoca a função e um objeto que contém informações sobre o evento.

Sintaxe

addEventCallback(callback)

Parâmetros

Parâmetro	Tipo	Descrição
`callback`	function	A função a ser invocada ao fim do evento.

O objeto eventData contém os seguintes dados:

Nome da chave	Tipo	Descrição
`tags`	Array	Uma matriz de objetos de dados da tag. Cada tag disparada durante o evento terá uma entrada nessa matriz. O objeto de dados da tag contém o ID da tag (`id`), bem como o status (`status`) e o tempo de execução (`executionTime`). Os dados também incluirão outros metadados que foram configurados na tag.

Exemplo

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

Permissões associadas

read_event_metadata

`aliasInWindow`

A API aliasInWindow permite gerar um alias (por exemplo, window.foo = window.bar), ajudando na compatibilidade com determinadas tags que exigem a criação de alias. Atribui o valor no objeto window encontrado em fromPath à chave no objeto window em toPath. Retorna true se for bem-sucedido. Caso contrário, retorna false.

Sintaxe

aliasInWindow(toPath, fromPath)

Parâmetros

Parâmetro	Tipo	Descrição
`toPath`	string	Um caminho separado por ponto no objeto `window` em que um valor será copiado. Todos os componentes no caminho já precisam existir no objeto `window`.
`fromPath`	string	Um caminho separado por ponto no objeto `window` do valor a ser copiado. Se o valor não existir, a operação falhará.

Exemplo

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

Permissões associadas

access_globals é necessário para toPath e fromPath. toPath exige acesso de gravação, e fromPath requer acesso de leitura.

`callInWindow`

Permite chamar funções de um caminho do objeto window de maneira controlada por políticas. Invoca a função no caminho especificado em window com os argumentos informados e retorna o valor. Se não for possível mapear o tipo de retorno diretamente para um formato compatível com o JavaScript no modo sandbox, undefined será retornado. Os oito tipos compatíveis no JavaScript no modo sandbox são null, undefined, boolean, number, string, Array, Object e function. Se o caminho indicado não existir ou não fizer referência a uma função, undefined será retornado.

Sintaxe

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

Parâmetros

Parâmetro	Tipo	Descrição
`pathToFunction`	string	Um caminho separado por ponto para a função no objeto `window` a ser chamada.
`args`	*	Argumentos a serem passados para a função.

Permissões associadas

access_globals com a permissão execute ativada.

`callLater`

Programa uma chamada de função para ocorrer de maneira assíncrona. A função será chamada após o retorno do código atual. É equivalente a setTimeout(<function>, 0).

Sintaxe

callLater(function)

Parâmetros

Parâmetro	Tipo	Descrição
`function`	function	Função a ser chamada.

`copyFromDataLayer`

Retorna o valor atribuído à chave informada na camada de dados: o valor encontrado nessa chave, se for tipo primitivo, função ou literal de objeto. Caso contrário, o resultado será undefined.

Sintaxe

copyFromDataLayer(key[, dataLayerVersion])

Parâmetros

Parâmetro	Tipo	Descrição
`key`	string	Chave no formato de "a.b.c".
`dataLayerVersion`	número	Versão opcional da camada de dados. O valor padrão é 2. Recomendamos não usar o valor 1.

Permissões associadas

read_data_layer

`copyFromWindow`

Copia uma variável do objeto window. Se o valor em window não puder ser mapeado diretamente para um tipo compatível no JavaScript no modo sandbox, undefined será retornado. Os oito tipos compatíveis no JavaScript no modo sandbox são null, undefined, boolean, number, string, Array, Object e function. Retorna o valor buscado e convertido.

Sintaxe

copyFromWindow(key)

Parâmetros

Parâmetro	Tipo	Descrição
`key`	string	A chave no objeto `window` de onde o valor será copiado.

Permissões associadas

access_globals

`createArgumentsQueue`

Cria uma fila que é preenchida com objetos de argumento para oferecer suporte a soluções de tag que exigem isso.

Cria uma função no escopo global (por exemplo, window), usando o argumento fnKey (mesma semântica de createQueue). Depois que a função é criada, essa API gera uma matriz em window (se já não existir) usando o argumento arrayKey.

Quando a função criada em fnKey é chamada, ela envia o objeto de argumentos para a matriz gerada em arrayKey. O valor de retorno da API é a função incluída em fnKey.

Essa função requer a configuração de leitura e gravação para fnKey e arrayKey na permissão access_globals.

Exemplo:

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

Sintaxe

createArgumentsQueue(fnKey, arrayKey)

Parâmetros

Parâmetro	Tipo	Descrição
`fnKey`	string	Caminho no objeto `window` em que a função é definida, se ela ainda não existir. Esse argumento é compatível com a notação de ponto padrão. Se o caminho da chave não existir, será lançada uma exceção. Ou seja, se `fnKey` for `'one.two'`, uma exceção será gerada.
`arrayKey`	string	Caminho no objeto `window` em que a matriz é definida, se ela ainda não existir. Esse argumento é compatível com a notação de ponto padrão. Se o caminho da chave não existir, será lançada uma exceção. Ou seja, se `arrayKey` for `'one.two'` e não houver um objeto global chamado `'one'`, uma exceção será gerada.

Permissões associadas

access_globals

`createQueue`

Cria uma matriz no objeto window (se ela ainda não existir) e retorna uma função que enviará valores a ela.

Essa função requer a configuração de leitura e gravação para arrayKey na permissão access_globals.

Exemplo:

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

Sintaxe

createQueue(arrayKey)

Parâmetros

Parâmetro	Tipo	Descrição
`arrayKey`	string	Chave no objeto `window` em que a matriz é definida, se ela ainda não existir. Esse argumento é compatível com a notação de ponto padrão. Se o caminho da chave não existir, será lançada uma exceção. Por exemplo, se `arrayKey` for `'one.two'` e não houver um objeto global chamado `'one'`, uma exceção será gerada.

Permissões associadas

access_globals

`decodeUri`

Decodifica os caracteres codificados no URI informado. Retorna uma string que representa o URI decodificado. Retorna undefined quando recebe uma entrada inválida.

Exemplo:

const decode = require('decodeUri');

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

Sintaxe

decodeUri(encoded_uri)

Parâmetros

Parâmetro	Tipo	Descrição
`encoded_uri`	string	Um URI que foi codificado por `encodeUri()` ou outros meios.

Permissões associadas

Nenhuma.

`decodeUriComponent`

Decodifica caracteres codificados no componente de URI fornecido. Retorna uma string que representa o componente de URI decodificado. Retorna undefined quando recebe uma entrada inválida.

Exemplo:

const decode = require('decodeUriComponent');

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

Sintaxe

decodeUriComponent(encoded_uri_component)

Parâmetros

Parâmetro	Tipo	Descrição
`encoded_uri_component`	string	Um componente de URI que foi codificado por `encodeUriComponent()` ou outros meios.

Permissões associadas

Nenhuma.

`encodeUri`

Retorna um Uniform Resource Identifier (URI) codificado ao adicionar escape aos caracteres especiais. Retorna uma string que representa a string fornecida codificada como URI. Retorna undefined quando recebe uma entrada inválida (uma condição única).

Exemplo:

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

Sintaxe

encodeUri(uri)

Parâmetros

Parâmetro	Tipo	Descrição
`uri`	string	URI completo.

Permissões associadas

Nenhuma.

`encodeUriComponent`

Exemplo:

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

Sintaxe

encodeUriComponent(str)

Parâmetros

Parâmetro	Tipo	Descrição
`str`	string	Componente de um URI.

Permissões associadas

Nenhuma.

`fromBase64`

A API fromBase64 permite decodificar strings a partir da representação base64 delas. Retorna undefined quando recebe uma entrada inválida.

Sintaxe

fromBase64(base64EncodedString)

Parâmetros

Parâmetro	Tipo	Descrição
`base64EncodedString`	string	String codificada em Base64.

Exemplo

const fromBase64 = require('fromBase64');

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

Permissões associadas

Nenhuma.

`generateRandom`

Retorna um número aleatório (inteiro) dentro do intervalo informado.

Sintaxe

generateRandom(min, max)

Parâmetros

Parâmetro	Tipo	Descrição
`min`	número	Valor potencial mínimo do inteiro retornado.
`max`	número	Valor potencial máximo do inteiro retornado.

Permissões associadas

Nenhuma.

`getContainerVersion`

Retorna um objeto que contém dados sobre o contêiner atual. O objeto retornado tem os seguintes campos:

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

Exemplo

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

Sintaxe

getContainerVersion();

Permissões associadas

read_container_data

`getCookieValues`

Retorna os valores de todos os cookies com o nome informado.

Sintaxe

getCookieValues(name[, decode])

Parâmetros

Parâmetro	Tipo	Descrição
`name`	string	Nome do cookie.
`decode`	booleano	Controla se os valores do cookie serão decodificados com `decodeURIComponent()` do JavaScript. O valor padrão é `true`.

Permissões associadas

get_cookies

`getQueryParameters`

Retorna o primeiro ou todos os parâmetros de queryKey do URL atual. Retorna o primeiro valor de queryKey ou uma matriz de valores de queryKey.

Sintaxe

getQueryParameters(queryKey[, retrieveAll])

Parâmetros

Parâmetro	Tipo	Descrição
`queryKey`	string	A chave para ler os parâmetros de consulta.
`retrieveAll`	booleano	Define se todos os valores serão recuperados.

Por exemplo, se o URL atual for https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, este será o resultado:

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

Permissões associadas

get_url precisa permitir o componente query e especificar queryKey nas chaves de consulta permitidas (ou autorizar qualquer chave desse tipo).

`getReferrerQueryParameters`

A API getReferrerQueryParameters age da mesma forma que getQueryParameters, mas atua no referenciador, e não no URL atual. Retorna o primeiro ou todos os parâmetros para queryKey do referenciador fornecido. Retorna o primeiro valor de queryKey ou uma matriz de valores de queryKey.

Sintaxe

getReferrerQueryParameters(queryKey[, retrieveAll])

Parâmetros

Parâmetro	Tipo	Descrição
`queryKey`	string	A chave para ler os parâmetros de consulta.
`retrieveAll`	booleano	Define se todos os valores serão recuperados.

Por exemplo, se o URL do referenciador for https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, este será o resultado:

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

Permissões associadas

get_referrer precisa permitir o componente query e especificar queryKey nas chaves de consulta permitidas (ou autorizar qualquer chave desse tipo).

`getReferrerUrl`

Após receber um tipo de componente, a API lê o objeto do documento para o referenciador e retorna uma string que representa uma parte do referenciador. Se nenhum componente for especificado, o URL do referenciador completo será retornado.

Sintaxe

getReferrerUrl([component])

Parâmetros

Parâmetro	Tipo	Descrição
`component`	string	O componente a ser retornado do URL. Será um dos seguintes valores: `protocol`, `host`, `port`, `path`, `query`, `extension`. Se `component` for `undefined`, `null` ou não corresponder a um desses componentes, todo o URL será retornado.

Permissões associadas

get_referrer precisa permitir o componente query e especificar queryKey nas chaves de consulta permitidas (ou autorizar qualquer chave desse tipo).

`getTimestamp`

Obsoleto. Use getTimestampMillis.

Retorna um número que representa o tempo atual em milissegundos desde a época Unix, conforme retornado por Date.now().

Sintaxe

getTimestamp();

Permissões associadas

Nenhuma.

`getTimestampMillis`

Retorna um número que representa o tempo atual em milissegundos desde a época Unix, conforme retornado por Date.now().

Sintaxe

getTimestampMillis();

Permissões associadas

Nenhuma.

`getType`

Retorna uma string que descreve o tipo de valor especificado. Ao contrário de typeof, getType diferencia entre array e object.

Sintaxe

getType(data.someField)

Observações

A tabela a seguir indica as strings retornadas para cada valor de entrada.

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

Permissões associadas

Nenhuma.

`getUrl`

Retorna uma string que representa o URL atual inteiro ou parte dele, segundo um tipo de componente e alguns parâmetros de configuração.

Sintaxe

getUrl(component)

Parâmetros

Parâmetro	Tipo	Descrição
`component`	string	O componente a ser retornado do URL. Precisa ser uma destas opções: `protocol`, `host`, `port`, `path`, `query`, `extension`, `fragment`. Se o componente for `undefined`, `null` ou não corresponder a um desses componentes, todo o valor `href` será retornado.

Permissões associadas

get_url

`gtagSet`

Envia um comando "set" da gtag para a camada de dados, para ser processado assim que possível, depois que o processamento do evento atual e de todas as tags que ele tiver ativado for concluído (ou atingir o tempo limite). A atualização será processada nesse contêiner antes de qualquer item na fila da camada de dados.

Por exemplo, se for chamada por uma tag disparada na inicialização de consentimento, a atualização vai ser implementada antes que o evento de inicialização seja processado. Exemplos: ads_data_redaction definido como true ou false, ou url_passthrough definido como true ou false.

Exemplos:

const gtagSet = require('gtagSet');

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

Sintaxe

gtagSet(object)

Parâmetros

Parâmetro	Tipo	Descrição
`Object`	objeto	Um objeto que atualiza o estado global das propriedades contidas nele.

Permissões associadas

write_data_layer verifica a permissão de gravação em dataLayer de todas as chaves especificadas. Se a entrada de gtagSet for um objeto simples, a API vai conferir a permissão de gravação de todas as chaves simplificadas dentro desse objeto, por exemplo: para gtagSet({foo: {bar: 'baz'}}), ela vai verificar a permissão de gravação em foo.bar.

Se a entrada em gtagSet for uma chave e algum valor de objeto não simples, a API vai conferir a permissão de gravação dessa chave, por exemplo: para gtagSet('abc', true) , ela vai verificar a permissão de gravação em 'abc'.

Se houver um ciclo no objeto de entrada, apenas as chaves anteriores ao mesmo objeto vão ser verificadas.

`injectHiddenIframe`

Adiciona um iframe invisível à página.

Os callbacks são realizados como instâncias de função e são agrupados nas funções JavaScript que os chamam.

Sintaxe

injectHiddenIframe(url, onSuccess)

Parâmetros

Parâmetro	Tipo	Descrição
`url`	string	O URL a ser usado como o valor do atributo `src` do iframe.
`onSuccess`	função	Chamado quando o frame é carregado com sucesso.

Permissões associadas

inject_hidden_iframe

`injectScript`

Adiciona uma tag de script à página para carregar o URL de forma assíncrona. Os callbacks são realizados como instâncias de função e são agrupados nas funções JavaScript que os chamam.

Sintaxe

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

Parâmetros

Parâmetro	Tipo	Descrição
`url`	string	Endereço do script a ser injetado.
`onSuccess`	função	Chamado quando o script é carregado com sucesso.
`onFailure`	função	Chamado quando o script não é carregado.
`cacheToken`	string	String opcional usada para indicar que o URL fornecido precisa ser armazenado em cache. Se esse valor for especificado, apenas um elemento de script será criado para solicitar o JavaScript. Qualquer outra tentativa de carregamento fará com que os métodos `onSuccess` e `onFailure` permaneçam na fila até que o script seja carregado.

Permissões associadas

inject_script

`isConsentGranted`

Retorna "true" se o tipo de consentimento especificado é "concedido".

Um tipo de consentimento é considerado "concedido" se está definido desse modo ou não tem definição nenhuma. Se o tipo de consentimento estiver definido com outro valor, ele não será considerado "concedido".

A interface do usuário do Gerenciador de tags oferece a opção de sempre dispará-las. Quando uma tag está ativada para sempre disparar com essa API, o consentimento é considerado "concedido", e true é retornado, seja qual for o estado real do consentimento.

Exemplo:

const isConsentGranted = require('isConsentGranted');

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

Sintaxe

isConsentGranted(consentType)

Parâmetros

Parâmetro	Tipo	Descrição
`consentType`	string	O tipo de consentimento que terá o estado verificado.

Permissões associadas

access_consent com acesso de leitura ao tipo de consentimento.

`JSON`

Retorna um objeto que oferece funções JSON.

A função parse() analisa uma string JSON para criar o valor ou objeto descrito pela string. Se o valor não puder ser analisado (por exemplo, JSON incorreto), a função retornará undefined. Se o valor de entrada não for uma string, a entrada será convertida para uma string.

A função stringify() converte a entrada em uma string JSON. Se o valor não puder ser analisado (por exemplo, o objeto tiver um ciclo), o método retornará undefined.

Sintaxe

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

Parâmetros

JSON.parse

Parâmetro	Tipo	Descrição
stringInput	qualquer um	Valor a ser convertido. Se o valor não for uma string, a entrada será convertida em uma string.

JSON.stringify

Parâmetro	Tipo	Descrição
value	qualquer um	Valor a ser convertido.

Exemplo

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`

Retorna um objeto com métodos para acessar o armazenamento local.

Sintaxe

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

Permissões associadas

access_local_storage

Exemplo

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 no console do navegador.

Sintaxe

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

Parâmetros

Parâmetro	Tipo	Descrição
`obj1 [, obj2,... objN]`	qualquer um	Argumentos

Permissões associadas

logging

`makeInteger`

Converte o valor informado em um número (inteiro).

Sintaxe

makeInteger(value)

Parâmetros

Parâmetro	Tipo	Descrição
`value`	qualquer um	Valor a ser convertido.

Permissões associadas

Nenhuma.

`makeNumber`

Converte o valor informado em um número.

Sintaxe

makeNumber(value)

Parâmetros

Parâmetro	Tipo	Descrição
`value`	qualquer um	Valor a ser convertido.

Permissões associadas

Nenhuma.

`makeString`

Retorna o valor fornecido como uma string.

Sintaxe

makeString(value)

Parâmetros

Parâmetro	Tipo	Descrição
`value`	qualquer um	Valor a ser convertido.

Permissões associadas

Nenhuma.

`makeTableMap`

Converte um objeto de tabela simples com duas colunas em um Map. Isso é usado para alterar um campo de modelo SIMPLE_TABLE com duas colunas em um formato mais prático.

Por exemplo, a função a seguir poderia converter um objeto de tabela:

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

em um Map:

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

Retorna um objeto: o Map convertido, se os pares de chave-valor tiverem sido adicionados. Caso contrário, o resultado será null.

Sintaxe

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parâmetros

Parâmetro	Tipo	Descrição
`tableObj`	List	Objeto de tabela a ser convertido. É uma lista de mapas em que cada `Map` representa uma linha na tabela. Cada nome de propriedade em um objeto de linha é o nome da coluna, e o valor da propriedade é o valor da coluna na linha.
`keyColumnName`	string	Nome da coluna cujos valores se tornarão chaves no `Map` convertido.
`valueColumnName`	string	Nome da coluna cujos valores se tornarão valores no `Map` convertido.

Permissões associadas

Nenhuma.

`Math`

Objeto que disponibiliza funções Math.

Sintaxe

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

Os parâmetros das funções matemáticas são convertidos em números.

Permissões associadas

Nenhuma.

`Object`

Retorna um objeto que fornece métodos Object.

O método keys() fornece o comportamento da Biblioteca padrão Object.keys(). Ela retorna uma matriz dos nomes de propriedades enumeráveis de um determinado objeto na mesma ordem que um loop for...in... faria. Se o valor de entrada não for um objeto, ele será convertido em um objeto.

O método values() fornece o comportamento Object.values() da Biblioteca padrão. Ela retorna uma matriz dos objetos de propriedades enumeráveis de um determinado objeto na mesma ordem que um loop for...in... faria. Se o valor de entrada não for um objeto, ele será convertido em um objeto.

O método entries() fornece o comportamento da Biblioteca padrão Object.entries(). Ela retorna uma matriz dos próprios pares de propriedades enumeráveis [key, value] de um determinado objeto na mesma ordem que um loop for...in... faria. Se o valor de entrada não for um objeto, ele vai ser convertido em um objeto.

O método freeze() oferece o comportamento da Biblioteca padrão Object.freeze(). Um objeto congelado não pode mais ser alterado. Congelar um objeto impede que novas propriedades sejam adicionadas a ele, propriedades atuais sejam removidas e valores das propriedades atuais sejam mudados. freeze() retorna o mesmo objeto que foi transmitido. Um argumento primitivo ou nulo é tratado como se fosse um objeto congelado e é retornado.

O método delete() fornece o comportamento do operador de exclusão da Biblioteca padrão. Esse método remove a chave informada do objeto, a menos que o objeto esteja congelado. Como o operador de exclusão da Biblioteca padrão, ele vai retornar true se o primeiro valor de entrada (objectInput) for um objeto não congelado, mesmo que o segundo valor de entrada (keyToDelete) especifique uma chave que não existe. Ele retornará false em todos os outros casos. Ele é diferente operador de exclusão da Biblioteca padrão por conta do seguinte:

keyToDelete não pode ser uma string delimitada por ponto que especifica uma chave aninhada.
delete() não pode ser usado para remover elementos de uma matriz.
delete() não pode ser usado para remover propriedades do escopo global.

Sintaxe

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

Parâmetros

Object.keys

Parâmetro	Tipo	Descrição
objectInput	any	O objeto cujas chaves são enumeradas. Se a entrada não for um objeto, ele será convertido em um objeto.

Object.values

Parâmetro	Tipo	Descrição
objectInput	any	O objeto cujos valores são enumerados. Se a entrada não for um objeto, ela será convertida em um objeto.

Object.entries

Parâmetro	Tipo	Descrição
objectInput	any	O objeto que tem pares de chave-valor para enumerar. Se a entrada não for um objeto, ela será convertida em um objeto.

Object.freeze

Parâmetro	Tipo	Descrição
objectInput	any	O objeto a ser congelado. Se a entrada não for um objeto, ela vai ser tratada como um objeto congelado.

Object.delete

Parâmetro	Tipo	Descrição
objectInput	any	O objeto cuja chave será excluída.
keyToDelete	string	A chave de nível superior que será excluída.

Exemplo

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`

Retorna um objeto que contém todas as partes dos componentes de um URL específico, semelhante ao objeto URL.

Essa API retornará undefined para qualquer URL incorreto. Para URLs formatados adequadamente, os campos ausentes na string de URL terão o valor de uma string vazia ou, no caso de searchParams, um objeto vazio.

O objeto retornado terá os seguintes 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,
}

Exemplo

const parseUrl = require('parseUrl');

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

Sintaxe

parseUrl(url);

Parâmetros

Parâmetro	Tipo	Descrição
`url`	string	O URL completo que será analisado.

Permissões associadas

Nenhuma.

`queryPermission`

Consulta as permissões restritas e autorizadas. Retornará um booleano: true se a permissão tiver sido concedida. Caso contrário, retornará false.

Sintaxe

queryPermission(permission, functionArgs*)

Parâmetros

Parâmetro	Tipo	Descrição
`permission`	string	Nome da permissão.
`functionArgs`	qualquer um	Os argumentos de função variam de acordo com a permissão que está sendo consultada. Veja Argumentos de função abaixo.

Argumentos de função

sendPixel, injectScript, injectHiddenIframe: o segundo parâmetro precisa ser uma string de URL.

writeGlobals, readGlobals: o segundo parâmetro precisa ser a chave que está sendo escrita ou lida.

readUrl: nenhum outro argumento é necessário para consultar se o URL inteiro pode ser lido. Para consultar se um determinado componente pode ser lido, transfira o nome do componente como o segundo argumento:

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

Para verificar se uma chave de consulta específica é válida, envie a chave de consulta como o terceiro parâmetro:

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

Permissões associadas

Nenhuma.

`readCharacterSet`

Retorna o valor de document.characterSet.

Sintaxe

readCharacterSet()

Parâmetros

Nenhum.

Permissões associadas

read_character_set

`readTitle`

Retorna o valor de document.title.

Sintaxe

readTitle()

Parâmetros

Nenhum.

Permissões associadas

read_title

`require`

Importa uma função integrada pelo nome. Retorna uma função ou um objeto que pode ser chamado no seu programa. Retorna undefined quando o navegador não é compatível com a função integrada.

Sintaxe

require(name)

Parâmetros

Parâmetro	Tipo	Descrição
`name`	string	Nome da função a ser importada.

Exemplo

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

Permissões associadas

Nenhuma.

`sendPixel`

Faz uma solicitação GET para um ponto de extremidade de URL especificado.

Sintaxe

sendPixel(url, onSuccess, onFailure)

Parâmetros

Parâmetro	Tipo	Descrição
`url`	string	Local de envio do pixel.
`onSuccess`	função	Chamado quando o pixel é carregado. Observação: mesmo que a solicitação seja enviada, os navegadores podem exigir uma resposta de imagem válida para executar o onSuccess.
`onFailure`	função	Chamado quando o script não é carregado. Observação: mesmo que a solicitação seja enviada, o onFailure pode ser executado se o servidor não retornar uma resposta de imagem válida.

Permissões associadas

send_pixel

`setCookie`

Define ou exclui o cookie com o nome, o valor e as opções especificadas.

Sintaxe

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

Parâmetros

Parâmetro	Tipo	Descrição
`name`	string	Nome do cookie.
`value`	string	Valor do cookie.
`options`	objeto	Especifica os atributos Domain, Path, Expires, Max-Age, Secure e SameSite. Veja Opções abaixo.
`encode`	booleano	Controla se o valor do cookie será codificado com o `encodeURIComponent()` do JavaScript. O valor padrão é `true`.

Opções

Domain: definido pela propriedade options['domain'], se estiver presente. Defina esse valor como 'auto' para tentar gravar o cookie usando o domínio mais amplo possível com base no local do documento. Se isso falhar, o sistema tentará subdomínios sucessivamente mais restritivos. Se isso também não funcionar, ele tentará gravar o cookie sem um domínio. Caso nenhum valor seja definido, o sistema tentará gravar o cookie sem um domínio especificado. Observação: quando um cookie sem um domínio especificado for gravado em document.cookie, o user agent vai padronizar o domínio do cookie como o host do local atual do documento.
Path: definido por options['path'], se presente. Quando um cookie sem um caminho especificado é gravado em document.cookie, o user agent padroniza o caminho do cookie para o caminho do local atual do documento.
Max-Age: definido por options['max-age'], se presente.
Expires: definido por options['expires'], se presente. Caso ele esteja presente, precisa ser uma string de data formatada em UTC. Date.toUTCString() pode ser usada para formatar Date para esse parâmetro.
Secure: definido por options['secure'], se presente.
SameSite: definido por options['samesite'], se houver.

Permissões associadas

set_cookies

`setDefaultConsentState`

Envia uma atualização de consentimento padrão para a camada de dados, para ser processada assim que possível, depois que o processamento do evento atual e de todas as tags que ele tiver ativado for concluído (ou atingir o tempo limite). A atualização será processada nesse contêiner antes de qualquer item na fila da camada de dados. Saiba mais sobre o consentimento.

Exemplo:

const setDefaultConsentState = require('setDefaultConsentState');

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

Sintaxe

setDefaultConsentState(consentSettings)

Parâmetros

Parâmetro	Tipo	Descrição
`consentSettings`	objeto	Um objeto que define o estado padrão para os tipos de consentimento especificados.

O objeto consentSettings é um mapeamento de strings de tipo de consentimento arbitrário para um dos valores 'granted' ou 'denied'. Ele aceita os seguintes valores:

Nome da chave	Tipo	Descrição
`consentType`	string	O valor de cada tipo de consentimento pode ser definido como "concedido" ou "negado". Qualquer valor diferente de "concedido" é tratado como "negado". Definir o valor como "indefinido" não altera o valor anterior.
`region`	Array	Uma matriz opcional de códigos regionais que especifica a área a que as configurações de consentimento se aplicam. Esses códigos são expressos usando países e/ou subdivisões no formato ISO 3166-2.
`wait_for_update`	número	Especifica um valor em milissegundos para controlar quanto tempo será necessário esperar antes de enviar os dados. Usado com ferramentas de consentimento que são carregadas de forma assíncrona.

Permissões associadas

access_consent com acesso de gravação a todos os tipos de consentimento no objeto consentSettings.

`setInWindow`

Define o valor informado no objeto window na chave especificada. Por padrão, esse método não definirá o valor no objeto window se já houver um valor presente. Defina overrideExisting como true para configurar o valor no objeto window, independentemente de haver ou não um valor. Retornará um booleano: true se o valor tiver sido definido. Caso contrário, retornará false.

Sintaxe

setInWindow(key, value, overrideExisting)

Parâmetros

Parâmetro	Tipo	Descrição
`key`	string	Chave no objeto `window` onde o valor será inserido.
`value`	*	Valor a ser definido em `window`.
`overrideExisting`	booleano	Sinalizador que indica se o valor precisa ser definido no objeto `window`, independentemente de haver ou não um valor.

Permissões associadas

access_globals

`sha256`

Calcula o valor de hash de SHA-256 da entrada e invoca um callback com o valor codificado em base64, a menos que o objeto options especifique uma codificação de saída diferente.

Exemplo:

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

Sintaxe

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

Parâmetros

Parâmetro	Tipo	Descrição
`input`	string	A string para o cálculo do hash.
`onSuccess`	função	Chamado com o valor de hash resultante, codificado em base64, a menos que o objeto `options` especifique uma codificação de saída diferente.
`onFailure`	função	Chamado se ocorrer um erro ao calcular o valor de hash ou se o navegador não tiver suporte nativo para sha256. O callback é invocado com um objeto que contém o nome do erro e a mensagem.
`options`	objeto	Objeto de escolhas opcionais para especificar a codificação de saída. Se definido, o objeto precisa conter a chave `outputEncoding` com valor `base64` ou `hex`.

Permissões associadas

Nenhuma.

`templateStorage`

Retorna um objeto com métodos para acessar o armazenamento de modelos, que permite que os dados sejam compartilhados entre execuções de um único modelo. Os dados armazenados no armazenamento de modelos duram por todo o ciclo de vida da página.

Sintaxe

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

Permissões associadas

access_template_storage

Exemplo

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`

A API toBase64 permite codificar uma string em uma representação base64.

Sintaxe

toBase64(input)

Parâmetros

Parâmetro	Tipo	Descrição
`input`	string	String a ser codificada.

Exemplo

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Permissões associadas

Nenhuma.

`updateConsentState`

Envia uma atualização de consentimento à camada de dados para ser processada assim que possível, depois que o processamento do evento atual e de todas as tags que ele tiver ativado for concluído (ou atingir o tempo limite). A atualização será processada nesse contêiner antes de qualquer item na fila da camada de dados. Saiba mais sobre o consentimento.

Exemplo:

const updateConsentState = require('updateConsentState');

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

Sintaxe

updateConsentState(consentSettings)

Parâmetros

Parâmetro	Tipo	Descrição
`consentSettings`	objeto	Um objeto que atualiza o estado dos tipos de consentimento especificados.

O objeto consentSettings é um mapeamento de strings de tipo de consentimento arbitrário para um dos valores 'granted' ou 'denied'. Ele aceita os seguintes valores:

Nome da chave	Tipo	Descrição
`consentType`	string	O valor de cada tipo de consentimento pode ser definido como "granted" ou "denied". Qualquer valor diferente de "granted" é tratado como "denied". Usar "undefined" não altera o valor anterior.

Permissões associadas

access_consent com acesso de gravação a todos os tipos de consentimento no objeto consentSettings.

APIs de teste

Essas APIs funcionam com testes do JavaScript no modo sandbox para criar testes de modelos personalizados no Gerenciador de tags do Google. Elas não precisam de uma instrução require(). Saiba mais sobre os testes de modelo personalizado.

`assertApi`

Retorna um objeto de correspondência que pode ser usado para fazer declarações de maneira fluente sobre a API informada.

Sintaxe

assertApi(apiName)

Parâmetros

Parâmetro	Tipo	Descrição
`apiName`	string	O nome da API a ser verificada. Mesma string que foi transmitida para `require()`.

Correspondências

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

Exemplos

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

`assertThat`

A API assertThat é modelada conforme a biblioteca [Truth] do Google. Ela retorna um objeto que pode ser usado para fazer declarações de forma fluente sobre o valor de um assunto. Um erro na declaração fará com que o teste seja interrompido imediatamente e falhe. No entanto, uma falha em um teste não afetará outros casos de teste.

Sintaxe

assertThat(actual, opt_message)

Parâmetros

Parâmetro	Tipo	Descrição
`actual`	any	O valor a ser usado nas verificações fluentes.
`opt_message`	string	Mensagem opcional a ser impressa se a declaração falhar.

Correspondências

Correspondente	Descrição
`isUndefined()`	Afirma que o assunto é `undefined`.
`isDefined()`	Afirma que o assunto não é `undefined`.
`isNull()`	Afirma que o assunto é `null`.
`isNotNull()`	Afirma que o assunto não é `null`.
`isFalse()`	Afirma que o assunto é `false`.
`isTrue()`	Afirma que o assunto é `true`.
`isFalsy()`	Afirma que o assunto é false. Os valores false são `undefined`, `null`, `false`, `NaN`, 0 e '' (string vazia).
`isTruthy()`	Afirma que o assunto é true. Os valores false são `undefined`, `null`, `false`, `NaN`, 0 e '' (string vazia).
`isNaN()`	Afirma que o assunto é o valor NaN.
`isNotNaN()`	Afirma que o assunto é qualquer valor além de NaN.
`isInfinity()`	Afirma que o assunto é um infinito positivo ou negativo.
`isNotInfinity()`	Afirma que o assunto é qualquer valor além de um infinito positivo ou negativo.
`isEqualTo(expected)`	Afirma que o assunto é igual ao valor informado. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`isNotEqualTo(expected)`	Afirma que o assunto não é igual ao valor informado. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`isAnyOf(...expected)`	Afirma que o assunto é igual a um dos valores fornecidos. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`isNoneOf(...expected)`	Afirma que o assunto não é igual a nenhum dos valores fornecidos. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`isStrictlyEqualTo(expected)`	Afirma que o assunto é estritamente igual (`===`) ao valor fornecido.
`isNotStrictlyEqualTo(expected)`	Afirma que o assunto não é estritamente igual (`!==`) ao valor fornecido.
`isGreaterThan(expected)`	Afirma que o assunto é maior (`>`) que o valor fornecido em uma comparação ordenada.
`isGreaterThanOrEqualTo(expected)`	Afirma que o assunto é maior ou igual (`>=`) ao valor fornecido em uma comparação ordenada.
`isLessThan(expected)`	Afirma que o assunto é menor (`<`) que o valor fornecido em uma comparação ordenada.
`isLessThanOrEqualTo(expected)`	Afirma que o assunto é menor ou igual (`<=`) ao valor fornecido em uma comparação ordenada.
`contains(...expected)`	Afirma que o assunto é uma matriz ou string que contém todos os valores fornecidos em qualquer ordem. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`doesNotContain(...expected)`	Afirma que o assunto é uma matriz ou string que não contém nenhum dos valores fornecidos. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`containsExactly(...expected)`	Afirma que o assunto é uma matriz que contém todos os valores fornecidos em qualquer ordem e nenhum outro valor. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`doesNotContainExactly(...expected)`	Afirma que o assunto é uma matriz que contém um conjunto de valores diferente dos valores fornecidos, em qualquer ordem. Essa é uma comparação de valores, não de referências. O conteúdo de objetos e matrizes é comparado de maneira recursiva.
`hasLength(expected)`	Afirma que o assunto é uma matriz ou string com o comprimento especificado. A declaração sempre vai falhar se o valor não for uma matriz ou string.
`isEmpty()`	Afirma que o assunto é uma matriz ou string vazia (comprimento = 0). A declaração sempre falhará se o valor não for uma matriz ou string.
`isNotEmpty()`	Afirma que o assunto é uma matriz ou string que não está vazia (comprimento > 0). A declaração sempre falhará se o valor não for uma matriz ou string.
`isArray()`	Afirma que o tipo de assunto é uma matriz.
`isBoolean()`	Afirma que o tipo de assunto é um booleano.
`isFunction()`	Afirma que o tipo de assunto é uma função.
`isNumber()`	Afirma que o tipo de assunto é um número.
`isObject()`	Afirma que o tipo de assunto é um objeto.
`isString()`	Afirma que o tipo de assunto é uma string.

Exemplos

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`

Falha no teste atual imediatamente e imprime a mensagem informada, se houver.

Sintaxe

fail(opt_message);

Parâmetros

Parâmetro	Tipo	Descrição
`opt_message`	string	Texto opcional da mensagem de erro.

Exemplo

fail('This test has failed.');

`mock`

Com a API mock, é possível substituir o comportamento das APIs no modo sandbox. A API de simulação pode ser usada com segurança no código de modelo, mas não funciona fora do modo de teste. As simulações são redefinidas antes da execução de cada teste.

Sintaxe

mock(apiName, returnValue);

Parâmetros

Parâmetro	Tipo	Descrição
`apiName`	string	O nome da API a ser simulada. É a mesma string transmitida para `require()`
`returnValue`	any	O valor a ser retornado para a API ou uma função chamada no lugar da API. Se `returnValue` for uma função, ela será chamada no lugar da API no modo sandbox. Caso `returnValue` não seja uma função, esse valor será retornado no lugar dessa API.

Exemplos

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

`runCode`

Executa o código do modelo, ou seja, o conteúdo da guia Código, no ambiente de teste atual com um determinado objeto de dados de entrada.

Sintaxe

runCode(data)

Parâmetros

Parâmetro	Tipo	Descrição
`data`	object	Objeto de dados a ser usado no teste.

Valor de retorno

Retorna o valor de uma variável para modelos de variáveis. Retorna undefined para todos os outros tipos de modelo.

Exemplo

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