APIs de inclusão de tags no servidor

Neste documento, descrevemos as APIs relacionadas à inclusão de tags no servidor.

---

addEventCallback

Registra uma função de callback que é invocada no fim de um evento. O callback é invocado quando todas as tags do evento são executadas. 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.

Quando essa API é usada em uma tag, ela é associada ao evento atual. Quando é utilizada em um cliente, ela precisa ser vinculada a um evento específico usando a função bindToEvent da API runContainer. Confira mais detalhes no exemplo.

Sintaxe

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

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 vão incluir outros metadados que foram configurados na tag.

Exemplo

Em um cliente:

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

Em uma tag:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

Permissões associadas

read_event_metadata

---

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

Exemplo

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

Sintaxe

callLater(function)

Parâmetros

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

Permissões associadas

Nenhuma.

---

claimRequest

Use essa API em um cliente para reivindicar a solicitação. Depois que uma solicitação é reivindicada, o contêiner não executa outros clientes.

Essa API gera uma exceção se for chamada em uma tag ou variável. Ela gera uma exceção quando chamada depois que o cliente retorna (por exemplo, em um callback assíncrono como em callLater ou na função runContainer onComplete).

Um cliente deve reivindicar a solicitação usando essa API antes de chamar a API runContainer.

Exemplo

const claimRequest = require('claimRequest');

claimRequest();

Sintaxe

claimRequest();

Permissões associadas

Nenhuma.

---

computeEffectiveTldPlusOne

Retorna o domínio efetivo de nível superior + 1 (eTLD+1) do domínio ou URL fornecido. O eTLD+1 é calculado analisando o domínio em relação às regras da lista de sufixos públicos. Ele costuma ser o domínio de nível mais alto em que você pode definir um cookie.

Se o argumento é nulo ou indefinido, o valor dele é retornado sem mudanças. Caso contrário, ele é convertido em uma string. Se o argumento não é um domínio ou URL válido, uma string em branco é retornada. Se o servidor não consegue buscar a lista de sufixos públicos, o valor do argumento retorna sem mudanças.

Exemplo

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

Sintaxe

computeEffectiveTldPlusOne(domainOrUrl);

Parâmetros

Parâmetro	Tipo	Descrição
domainOrUrl	string	Domínio ou URL em que o eTLD+1 é calculado.

Permissões associadas

Nenhuma.

---

createRegex

Cria uma nova instância de regex e a retorna agrupada em um objeto. Não é possível acessar o regex diretamente. No entanto, ele pode ser transmitido à API testRegex, String.replace(), String.match() e String.search().

Vai retornar null se o regex for inválido ou Re2 não estiver disponível no servidor.

Esta API usa uma implementação Re2. A imagem Docker do servidor precisa ser 2.0.0 ou posterior.

Exemplo

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

Sintaxe

createRegex(pattern, flags);

Parâmetros

Parâmetro	Tipo	Descrição
pattern	string	Texto da expressão regular.
flags	string	Uma string opcional contendo as sinalizações para o regex que está sendo criado. "g" (global) e "i" (ignorar caso) têm suporte. Todos os outros caracteres são ignorados silenciosamente.

Permissões associadas

Nenhuma.

---

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

const decodedUrl = decodeUri(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 decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

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.

Exemplo

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('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

Retorna um Uniform Resource Identifier (URI) codificado ao adicionar escape aos caracteres especiais. Retorna uma string que representa a string fornecida codificada como URI.

Exemplo

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('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.

---

extractEventsFromMpv1

Converte uma solicitação de Measurement Protocol V1 recebida em uma lista de eventos no formato Unified Schema. Retorna a lista de eventos extraídos. Um erro é exibido quando a solicitação não está no formato correto.

Exemplo

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Sintaxe

extractEventsFromMpv1();

Permissões associadas

Requer a permissão read_request. A permissão precisa ser configurada para garantir acesso a pelo menos:

• body
• query parameters

---

extractEventsFromMpv2

Converte uma solicitação de Measurement Protocol V2 recebida em uma lista de eventos no formato Unified Schema. Retorna a lista de eventos extraídos. Um erro é exibido quando a solicitação não está no formato correto.

Exemplo

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Sintaxe

extractEventsFromMpv2();

Permissões associadas

Requer a permissão read_request. A permissão precisa ser configurada para garantir acesso a pelo menos:

• body
• query parameters

---

fromBase64

Decodifica uma string codificada em base64. Retornará undefined se a entrada for 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.

Exemplo

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Sintaxe

generateRandom(min, max);

Parâmetros

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

Permissões associadas

Nenhuma.

---

getAllEventData

Retorna uma cópia dos dados do evento.

Sintaxe

getAllEventData();

Permissões associadas

read_event_data

---

getClientName

Retorna uma string que contém o nome do cliente atual.

Sintaxe

getClientName();

Permissões associadas

read_container_data

---

getContainerVersion

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

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

Exemplo

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Sintaxe

getContainerVersion();

Permissões associadas

read_container_data

---

getCookieValues

Retorna uma matriz que contém os valores de todos os cookies com o nome informado.

Exemplo

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

Sintaxe

getCookieValues(name[, noDecode]);

Parâmetros

Parâmetro	Tipo	Descrição
name	string	Nome do cookie.
noDecode	boolean	Se é true, os valores dos cookies não são decodificados antes de serem retornados. O padrão é false.

Permissões associadas

get_cookies

---

getEventData

Retorna uma cópia do valor no caminho informado nos dados do evento. Retorna undefined se não há dados de eventos ou se não tem um valor no caminho fornecido.

Exemplo

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

Parâmetros

Parâmetro	Tipo	Descrição
keyPath	any	O caminho da chave, em que os componentes do caminho são separados por pontos. Os componentes do caminho podem ser chaves em um objeto ou índices em uma matriz. Se keyPath não é uma string, ele é convertido em uma.

Sintaxe

getEventData(keyPath);

Permissões associadas

read_event_data

---

getGoogleScript

Recupera um recurso de um conjunto predeterminado de scripts do Google e retorna uma promessa com o script e os metadados de armazenamento em cache associados.

A promessa vai ser resolvida em um objeto que contém duas chaves: script e metadata. Se a solicitação falhar, a promessa vai ser rejeitada com uma chave reason.

O objeto metadata contém os metadados de armazenamento em cache a seguir, com base nos cabeçalhos de resposta do recurso. Os campos só existem quando o cabeçalho correspondente está presente na resposta.

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

Exemplo

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

Sintaxe

getGoogleScript(script[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
script	string	Nome do script. Os scripts aceitos são 'ANALYTICS', 'GTAG' e 'GTM'. A opção 'ANALYTICS' busca o script do Google Analytics em https://www.google-analytics.com/analytics.js. A opção 'GTAG' busca o script da tag global do site (gtag.js) de https://www.googletagmanager.com/gtag/js. A opção 'GTM' busca o script do Gerenciador de tags do Google em https://www.googletagmanager.com/gtm.js.
options	object	Opções de solicitação alternativas. Veja abaixo as opções aceitas.

Opções

Opção	Tipo	Descrição
id	string	Aplicável a 'GTAG' com o ID de métricas da gtag e 'GTM' com o ID do contêiner da Web (por exemplo, GTM-XXXX).
debug	any	Se o valor é verdadeiro, ele solicita e retorna a versão de depuração do script de medição.
timeout	number	O tempo limite da solicitação em milissegundos. Os valores não positivos são ignorados. Quando a solicitação expira, o callback é invocado com undefined para o valor do script e {} para o objeto de metadados.

As chaves de opção não reconhecidas são ignoradas.

Permissões associadas

Requer a permissão send_http. A permissão precisa ser configurada para garantir o acesso a pelo menos:

• Permitir domínios do Google

---

getRemoteAddress

Retorna uma representação de string do endereço IP de origem da solicitação, por exemplo, 12.345.67.890 para IPv4 ou 2001:0db8:85a3:0:0:8a2e:0370:7334 para IPv6, lendo cabeçalhos de solicitação como Forwarded e X-Forwarded-For. Observação: essa API tenta descobrir o IP de origem, mas não garante um resultado preciso.

Sintaxe

getRemoteAddress();

Permissões associadas

Requer a permissão read_request. A permissão precisa ser configurada para garantir acesso a pelo menos:

• Cabeçalhos Forwarded e X-Forwarded-For
• Endereço IP remoto

---

getRequestBody

Retorna o corpo da solicitação como uma string, se presente, ou undefined, caso ausente.

Sintaxe

getRequestBody();

Permissões associadas

read_request

---

getRequestHeader

Retorna o valor do cabeçalho da solicitação nomeado como uma string, se presente, ou undefined, caso ausente. Quando o cabeçalho é repetido, os valores retornados são unidos com ', '.

Exemplo

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Sintaxe

getRequestHeader(headerName);

Parâmetros

Parâmetro	Tipo	Descrição
headerName	string	Nome do cabeçalho. Esse valor é indiferente a maiúsculas.

Permissões associadas

read_request

---

getRequestMethod

Retorna o método da solicitação, por exemplo, 'GET' ou 'POST', como uma string.

Exemplo

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

Sintaxe

getRequestMethod();

Permissões associadas

Nenhuma.

---

getRequestPath

Retorna o caminho da solicitação sem a string de consulta. Por exemplo, se o URL é '/foo?id=123', '/foo' é retornado. Remove automaticamente o prefixo de URL do contêiner do servidor do caminho. Por exemplo, se o URL do contêiner do servidor for https://example.com/analytics, e o caminho da solicitação for '/analytics/foo', será retornado '/foo'.

Exemplo

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

Sintaxe

getRequestPath();

Permissões associadas

read_request

---

getRequestQueryParameter

Retorna o valor decodificado do parâmetro de string de consulta nomeado como uma string, se presente, ou undefined, caso o parâmetro esteja ausente. Se o parâmetro está repetido na string de consulta, o primeiro valor exibido nela é retornado.

Exemplo

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

Sintaxe

getRequestQueryParameter(name);

Parâmetros

Parâmetro	Tipo	Descrição
name	string	Nome do parâmetro de consulta.

Permissões associadas

read_request

---

getRequestQueryParameters

Retorna os parâmetros de consulta da solicitação HTTP de entrada como um objeto que mapeia os nomes desses parâmetros para os valores correspondentes. Os nomes e valores são decodificados.

Exemplo

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

Sintaxe

getRequestQueryParameters();

Permissões associadas

read_request

---

getRequestQueryString

Retorna a consulta de solicitação como uma string sem o ponto de interrogação inicial ou uma string vazia se o URL da solicitação não inclui uma string de consulta.

Exemplo

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

Sintaxe

getRequestQueryString();

Permissões associadas

read_request

---

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.

Tipo de entrada	Valor retornado
string	'string'
number	'number'
boolean	'boolean'
null	'null'
undefined	'undefined'
Array	'array'
Object	'object'
Function	'function'

Exemplo

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

Sintaxe

getType(value);

Parâmetros

Parâmetro	Tipo	Descrição
value	any	Valor de entrada.

Permissões associadas

Nenhuma.

---

isRequestMpv1

Retorna true se a solicitação recebida é de Measurement Protocol V1 ou false quando é de outro tipo.

Exemplo

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

Sintaxe

isRequestMpv1();

Permissões associadas

Nenhuma.

---

isRequestMpv2

Retorna true se a solicitação recebida é de Measurement Protocol V2 ou false quando é de outro tipo.

Exemplo

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

Sintaxe

isRequestMpv2();

Permissões associadas

Nenhuma.

---

logToConsole

Registra os argumentos no console.

Esses registros ficam visíveis na Análise de registros no console do Google Cloud. Nesse local, execute a consulta logName =~ "stdout" para ver as entradas de registro criadas por essa API.

Exemplo

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

Sintaxe

logToConsole(argument1[, argument2, ...]);

Parâmetros

A API usa um ou mais argumentos, cada um convertido em uma string (se necessário) e registrado no console.

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	any type	O valor que 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	any type	O valor que 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	any type	O valor que 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 a ele. Caso contrário, o resultado vai 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.

---

parseUrl

Retorna um objeto que contém todas as partes de 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:[e-mail]: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.

---

returnResponse

Retorna a resposta que foi definida anteriormente por outros modelos usando as APIs que modificam a resposta, incluindo setCookie, setPixelResponse, setResponseBody, setResponseHeader e setResponseStatus. O padrão é um código de status HTTP 200, com corpo vazio e sem cabeçalhos.

É recomendável usar essa API com um modelo de cliente.

Sintaxe

returnResponse();

Exemplo

Veja o exemplo do runContainer.

Permissões associadas

return_response

---

runContainer

Executa a lógica do contêiner (variáveis, acionadores, tags) no escopo de um evento. Se essa API for chamada durante a execução do contêiner, o contêiner será executado novamente.

Os callbacks onComplete e onStart recebem uma função chamada bindToEvent. Use bindToEvent para executar uma API no contexto do evento. Veja o exemplo de addEventCallback para mais detalhes.

É recomendável usar essa API com um modelo de cliente.

Exemplo

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

Sintaxe

runContainer(event, onComplete, onStart);

Parâmetros

Parâmetro	Tipo	Descrição
event	object	Parâmetros do evento.
onComplete	function	Um callback invocado após o disparo de todas as tags.
onStart	function	Um callback que será invocado imediatamente, antes que as tags comecem a ser disparadas.

Permissões associadas

run_container

---

sendEventToGoogleAnalytics

Envia um único evento usando dados de eventos comuns para o Google Analytics e retorna uma promessa que é resolvida em um objeto com uma chave location ou é rejeitada para um objeto com uma chave reason. O destino, o Universal Analytics ou o Google Analytics 4 é baseado no ID de métricas nos dados de eventos.

O campo location é definido como o cabeçalho location, se estiver presente.

Exemplo

const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}, (err) => {
  setResponseStatus(500);
  data.gtmOnFailure();
});

Sintaxe

sendEventToGoogleAnalytics(event);

Parâmetros

Parâmetro	Tipo	Descrição
event	object	Evento no formato Unified Schema.

Permissões associadas

Requer a permissão send_http. A permissão precisa ser configurada para garantir o acesso a pelo menos:

• Permitir domínios do Google

---

sendHttpGet

Faz uma solicitação HTTP GET para o URL especificado e retorna uma promessa que é resolvida com o resultado quando a solicitação é concluída ou expira.

O resultado resolvido é um objeto que contém três chaves: statusCode, headers e body. Se houver uma falha na solicitação (por exemplo, URL inválido, sem rota para o host, erro na negociação do SSL etc.), a promessa vai ser rejeitada com: {reason: 'failed'}. Se a opção timeout tiver sido definida e a solicitação expirar, a promessa vai ser rejeitada com: {reason: 'timed_out'}

Exemplo

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

Sintaxe

sendHttpGet(url[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
url	string	URL da solicitação.
options	object	Opções de solicitação alternativas. As opções aceitas são: cabeçalhos e tempo limite. As chaves de opção desconhecidas são ignoradas. Veja Opções abaixo.

Opções

• cabeçalhos: os cabeçalhos de solicitação adicionais representados como um objeto.
• tempo limite: tempo limite em milissegundos até o cancelamento da solicitação. O padrão é 15000.

Permissões associadas

send_http

---

sendHttpRequest

Faz uma solicitação HTTP para o URL especificado e retorna uma promessa que é resolvida com o resultado quando a solicitação é concluída ou expira.

O resultado resolvido é um objeto que contém três chaves: statusCode, headers e body. Se houver uma falha na solicitação (por exemplo, URL inválido, sem rota para o host, erro na negociação do SSL etc.), a promessa vai ser rejeitada com: {reason: 'failed'}. Se a opção timeout tiver sido definida e a solicitação expirar, a promessa vai ser rejeitada com: {reason: 'timed_out'}

Exemplo

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

Sintaxe

sendHttpRequest(url[, options[, body]]);

Parâmetros

Parâmetro	Tipo	Descrição
url	string	URL da solicitação.
options	object	Opções de solicitação alternativas. As opções aceitas são: cabeçalhos, método e tempo limite. As chaves de opção desconhecidas são ignoradas. Confira abaixo em Opções.
body	string	Corpo da solicitação opcional.

Opções

• cabeçalhos: outros cabeçalhos da solicitação.
• método: o método de solicitação cujo padrão é "GET".
• tempo limite: tempo limite em milissegundos até o cancelamento da solicitação. O padrão é 15000.

Permissões associadas

send_http

---

sendPixelFromBrowser

Envia um comando ao navegador para carregar o URL fornecido como uma tag <img>. Esse protocolo de comando é compatível com as tags da Web Google Analytics: configuração do GA4 e Google Analytics: evento do GA. Ative a opção Enviar para o contêiner do servidor na tag de configuração. Confira mais detalhes nas instruções.

Essa API vai retornar false se a solicitação recebida não for compatível com o protocolo de comando ou se a resposta já tiver sido transferida. Caso contrário, a API retornará true.

Exemplo:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

Sintaxe

sendPixelFromBrowser(url)

Parâmetros

Parâmetro	Tipo	Descrição
url	string	O URL a ser enviado para o navegador.

Permissões associadas

send_pixel_from_browser

---

setCookie

Define ou exclui um cookie com as opções especificadas.

Para excluir um cookie, atribua a ele o mesmo caminho e domínio com que foi criado e defina um valor de expiração que esteja no passado, por exemplo, "Thu, 01 Jan 1970 00:00:00 GMT".

returnResponse precisa ser chamado para que a resposta seja enviada de volta ao cliente.

Exemplo

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

Sintaxe

setCookie(name, value[, options[, noEncode]]);

Parâmetros

Parâmetro	Tipo	Descrição
name	string	Nome do cookie. O nome é indiferente a maiúsculas.
value	string	Valor do cookie.
options	object	Atributos opcionais do cookie: domain, expires, fallbackDomain, httpOnly, max-age, path, secure e sameSite. Confira abaixo em Opções.
noEncode	boolean	Se o valor do cookie for verdadeiro, ele não será codificado. O valor padrão é false.

Opções

• domain: o host para onde o cookie será enviado. Se definido como o valor especial "auto", o host será calculado automaticamente usando a seguinte estratégia:

  • eTLD+1 do cabeçalho Forwarded, se presente.
  • eTLD+1 do cabeçalho X-Forwarded-Host, se presente.
  • eTLD+1 do cabeçalho Host.

• expires: o ciclo de vida máximo do cookie. Precisa ser uma string de data no formato UTC, por exemplo "Sábado, 26 de outubro de 1985 08:21:00 GMT". Se expires e max-age forem definidos, max-age terá precedência.

• httpOnly: evita que o JavaScript acesse o cookie se true.

• max-age: número de segundos até o cookie expirar. Um número zero ou negativo faz com que o cookie expire imediatamente. Se expires e max-age forem definidos, max-age terá precedência.

• path: um caminho que precisa existir no URL solicitado. Caso contrário, o navegador não enviará o cabeçalho "Cookie".

• secure: se for definido como true, o cookie só vai ser enviado ao servidor quando uma solicitação for feita em um endpoint https:.

• samesite: declara que um cookie não pode ser enviado com solicitações de origem cruzada. Precisa ser 'strict', 'lax' ou 'none'.

Permissões associadas

set_cookie

---

setPixelResponse

Define o corpo da resposta como um GIF 1x1, o cabeçalho "Content-Type" como "image/gif", os cabeçalhos de armazenamento em cache de modo que os user agents não armazenem a resposta em cache e estabelece o status de resposta como "200".

returnResponse precisa ser chamado para que a resposta seja enviada de volta ao cliente.

Sintaxe

setPixelResponse();

Permissões associadas

Requer a permissão access_response. A permissão precisa ser configurada para garantir acesso a pelo menos:

• headers: precisa permitir as seguintes chaves
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

---

setResponseBody

Define o corpo da resposta para o argumento.

returnResponse precisa ser chamado para que a resposta seja enviada de volta ao cliente.

Sintaxe

setResponseBody(body[, encoding]);

Parâmetros

Parâmetro	Tipo	Descrição
body	string	Valor a ser definido como o corpo da resposta.
encoding	string	A codificação de caracteres do corpo da resposta (o padrão é 'utf8'). Os valores aceitos incluem 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' e 'hex'.

Permissões associadas

Requer a permissão access_response. A permissão precisa ser configurada para garantir acesso a pelo menos:

• body

---

setResponseHeader

Define um cabeçalho na resposta que será retornada. Se esta API já tiver definido um cabeçalho com esse nome (que não diferencia maiúsculas de minúsculas), a última chamada vai substituir ou apagar o valor determinado pelo autor da chamada anterior.

returnResponse precisa ser chamado para que a resposta seja enviada de volta ao cliente.

Sintaxe

setResponseHeader(name, value);

Parâmetros

Parâmetro	Tipo	Descrição
name	string	Nome do cabeçalho. Os nomes dos cabeçalhos HTTP são indiferentes a maiúsculas. Assim, eles estarão em letras minúsculas.
value	string undefined	Valor do cabeçalho. Se o valor é nulo ou indefinido, o cabeçalho nomeado é apagado da resposta retornada.

Permissões associadas

Requer a permissão access_response. A permissão precisa ser configurada para garantir acesso a pelo menos:

• headers

---

setResponseStatus

Define o código de status HTTP da resposta que vai ser retornada.

returnResponse precisa ser chamado para que a resposta seja enviada de volta ao cliente.

Sintaxe

setResponseStatus(statusCode);

Parâmetros

Parâmetro	Tipo	Descrição
statusCode	number	Código de status HTTP a ser retornado.

Permissões associadas

Requer a permissão access_response. A permissão precisa ser configurada para garantir acesso a pelo menos:

• status

---

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.

Esse comportamento e assinatura da API correspondem à API sha256 para contêineres da Web. No entanto, os modelos personalizados em contêineres do servidor devem usar a API sha256Sync para simplificar o código.

Exemplo

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});

Sintaxe

sha256(input, onSuccess, options = undefined);

Parâmetros

Parâmetro	Tipo	Descrição
input	string	String em que o hash será gerado.
onSuccess	function	Chamado com o valor de hash resultante, codificado em base64, a menos que o objeto options especifique uma codificação de saída diferente.
options	object	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.

---

sha256Sync

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

Exemplo

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

Sintaxe

sha256Sync(input, options = undefined);

Parâmetros

Parâmetro	Tipo	Descrição
input	string	String em que o hash será gerado.
options	object	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.

---

templateDataStorage

Retorna um objeto com métodos para acessar o armazenamento de dados de modelo, que permite que os dados sejam compartilhados entre execuções de um único modelo. Os dados localizados no armazenamento de dados do modelo permanecem no servidor que executa o contêiner. Na maioria dos casos, há vários servidores executando o contêiner. Portanto, salvar informações no armazenamento de dados do modelo não garante que todas as solicitações seguinte terão acesso a elas.

"Data" no nome "templateDataStorage" indica que só os tipos de dados sem formatação e que não sejam uma função podem ser armazenados usando essa API. Todas as funções ou referências a funções transmitidas para a API vão ser salvas como null.

Observação: as solicitações do modo de depuração ou visualização ou do editor de modelos têm acesso ao armazenamento de dados do modelo, que é inicializado em uma string vazia e mantido até o fim da solicitação para não misturar os dados de depuração ou teste com os de produção.

Observação: diferente da API Web Storage, templateDataStorage não serializa/desserializa dados em strings.

Sintaxe

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

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

Exemplo

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

Permissões associadas

access_template_storage

---

testRegex

Testa uma string em um regex criado com a API createRegex. Vai retornar true se o regex corresponder. Caso contrário, retorna false.

Um regex criado com a sinalização global tem estado. Confira a documentação do RegExp para saber detalhes.

Exemplo

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

Sintaxe

testRegex(regex, string);

Parâmetros

Parâmetro	Tipo	Descrição
regex	Object	O regex para teste, retornado da API createRegex.
string	string	String para teste.

Permissões associadas

Nenhum.

---

toBase64

Codifica uma string como 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.

---

BigQuery

Retorna um objeto que fornece funções JSON.

Com a função BigQuery.insert, é possível gravar dados em uma tabela do BigQuery. Ela retorna uma promessa que é resolvida após uma inserção bem-sucedida ou é rejeitada depois de um erro.

Quando a inserção é bem-sucedida, a promessa é resolvida sem argumentos.

Quando a inserção falha, a promessa é rejeitada com uma lista de objetos contendo o motivo do erro e possivelmente um objeto de linha. É possível que uma parte da solicitação seja concluída com êxito e outras não. Nesse caso, a promessa é rejeitada com uma lista de erros para cada linha, contendo um objeto de linha para distinguir quais linhas foram inseridas. Consulte Exemplos de erros abaixo. Veja a documentação do BigQuery sobre mensagens de erro para mais informações.

Sintaxe

BigQuery.insert(connectionInfo, rows[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
connectionInfo	object	Define as informações necessárias para se conectar a uma tabela do BigQuery. Há um parâmetro opcional e dois obrigatórios: projectId (opcional) ID do projeto do Google Cloud Platform. Se omitido, o projectId é recuperado da variável de ambiente GOOGLE_CLOUD_PROJECT, desde que a configuração de permissão access_bigquery do ID do projeto esteja definida como * ou GOOGLE_CLOUD_PROJECT. Se o contêiner do servidor estiver em execução no Google Cloud, o GOOGLE_CLOUD_PROJECT já vai estar definido como o ID do projeto do Google Cloud. datasetId: ID do conjunto de dados do BigQuery. tableId – ID da tabela do BigQuery.
rows	Array	As linhas a serem inseridas na tabela.
options	object	Opções de solicitação alternativas. As opções aceitas são: ignoreUnknownValues e skipInvalidRows. A chaves de opção desconhecidas são ignoradas. Confira abaixo em Opções.

Opções

Parâmetro	Tipo	Descrição
ignoreUnknownValues	boolean	Se definido como true, as linhas que contêm valores não correspondentes ao esquema serão aceitas. Os valores desconhecidos serão ignorados. O valor padrão é false.
skipInvalidRows	boolean	Se definido como true, serão inseridas todas as linhas válidas de uma solicitação, mesmo que haja algumas inválidas. O padrão é false.

Exemplos de erro

Um erro de módulo não encontrado significa que o contêiner do servidor provavelmente está executando uma versão mais antiga da nossa imagem que ainda não incluiu o módulo do BigQuery. Implante seu contêiner do servidor com as mesmas configurações usando nosso script de implantação. O módulo será incluído automaticamente assim que a operação for concluída.

Um erro de não inserção normalmente tem um objeto com uma chave reason:

[{reason: 'invalid'}]

Um erro de inserção pode conter vários objetos com uma matriz errors e um objeto row. Veja a seguir um exemplo de resposta de erro exibida quando duas linhas são inseridas e apenas uma contém um erro:

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

Exemplo

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

Permissões associadas

access_bigquery

---

Firestore

Retorna um objeto que oferece funções do Firestore.

Essa API é compatível apenas com o Firestore no modo nativo, não com o Firestore no modo Datastore.

Firestore.read

A função Firestore.read lê dados de um documento do Firestore e retorna uma promessa que é resolvida em um objeto com duas chaves: id e data. Se o documento não existir, a promessa vai ser rejeitada com um objeto contendo uma chave reason igual a not_found.

Observação: por padrão, Firestore.read armazena a resposta em cache durante a execução do contêiner. Para desativar o armazenamento em cache, consulte a seção Opções abaixo. O armazenamento em cache é desativado automaticamente durante qualquer transação.

Sintaxe

Firestore.read(path[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
path	string	O caminho para o documento ou coleção. Não pode começar nem terminar com um "/".
options	object	Opções de solicitação alternativas. As opções aceitas são: projectId, disableCache e transaction. As chaves de opção desconhecidas são ignoradas. Confira abaixo em Opções.

Opções

Parâmetro	Tipo	Descrição
projectId	string	Opcional. ID do projeto do Google Cloud Platform. Se omitido, o projectId é recuperado da variável de ambiente GOOGLE_CLOUD_PROJECT, desde que a configuração de permissão access_firestore do ID do projeto esteja definida como * ou GOOGLE_CLOUD_PROJECT. Se o contêiner do servidor estiver em execução no Google Cloud, o GOOGLE_CLOUD_PROJECT já vai estar definido como o ID do projeto do Google Cloud.
disableCache	boolean	Opcional. Determina se o cache deve ou não ser desativado. O armazenamento em cache é ativado por padrão, o que armazena os resultados em cache durante toda a solicitação.
transaction	string	Opcional. Valor recuperado de Firestore.runTransaction(). Marca a operação a ser usada dentro de uma transação.

Exemplo

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

A função Firestore.write grava dados em um documento ou coleção do Firestore. Se o caminho vai para uma coleção, um documento é criado com um ID gerado aleatoriamente. Se o caminho levar a um documento que ainda não existe, ele vai ser criado. Essa API retorna uma promessa que é resolvida com o ID do documento adicionado ou modificado. Quando a opção de transação é usada, a API retorna uma promessa, mas sem o ID, já que as gravações são agrupadas.

Sintaxe

Firestore.write(path, input[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
path	string	O caminho para o documento ou coleção. Não pode começar nem terminar com um "/".
input	object	O valor a ser gravado no documento. Quando a opção de mesclagem está definida, a API combina as chaves da entrada no documento.
options	object	Opções de solicitação alternativas. As opções aceitas são: projectId, merge e transaction. A chaves de opção desconhecidas são ignoradas. Confira abaixo em Opções.

Opções

Parâmetro	Tipo	Descrição
projectId	string	Opcional. ID do projeto do Google Cloud Platform. Se omitido, o projectId é recuperado da variável de ambiente GOOGLE_CLOUD_PROJECT, desde que a configuração de permissão access_firestore do ID do projeto esteja definida como * ou GOOGLE_CLOUD_PROJECT. Se o contêiner do servidor estiver em execução no Google Cloud, o GOOGLE_CLOUD_PROJECT já vai estar definido como o ID do projeto do Google Cloud.
merge	boolean	Opcional. Se for definido como true, combine as chaves da entrada no documento; caso contrário, o método vai modificar todo o documento. O valor padrão é false.
transaction	string	Opcional. Valor recuperado de Firestore.runTransaction(). Marca a operação a ser usada dentro de uma transação.

Exemplo

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

A função Firestore.query consulta a coleção especificada e retorna uma promessa que é resolvida em uma matriz de documentos do Firestore correspondentes às condições da consulta. O objeto do documento do Firestore é igual ao exibido acima em Firestore.read. Se não houver documentos que correspondam às condições da consulta, a promessa retornada será resolvida como uma matriz vazia.

Observação: por padrão, Firestore.query armazena a resposta em cache durante a execução do contêiner. Para desativar o armazenamento em cache, consulte a seção Opções abaixo. O armazenamento em cache é desativado automaticamente durante qualquer transação.

Observação: o Firestore cria automaticamente um índice para cada campo. Para consultar vários campos, pode ser necessário criar um índice composto para a coleção especificada. Para mais informações, consulte a documentação do Firestore sobre índices compostos.

Sintaxe

Firestore.query(collection, queryConditions[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
collection	string	O caminho para a coleção. Não pode começar nem terminar com um "/".
queryConditions	Array	Uma matriz de condições de consulta. Cada consulta tem a forma de uma matriz com três valores: key, operator e expectedValue. Por exemplo: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. As condições são unidas por AND para criar o resultado da consulta. Consulte Operadores de consulta do Firestore para ver uma lista de operadores compatíveis.
options	object	Opções de solicitação alternativas. As opções aceitas são: projectId, disableCache, limit e transaction. As chaves de opção desconhecidas são ignoradas. Veja abaixo em Opções.

Opções

Parâmetro	Tipo	Descrição
projectId	string	Opcional. ID do projeto do Google Cloud Platform. Se omitido, o projectId é recuperado da variável de ambiente GOOGLE_CLOUD_PROJECT, desde que a configuração de permissão access_firestore do ID do projeto esteja definida como * ou GOOGLE_CLOUD_PROJECT. Se o contêiner do servidor estiver em execução no Google Cloud, o GOOGLE_CLOUD_PROJECT já vai estar definido como o ID do projeto do Google Cloud.
disableCache	boolean	Opcional. Determina se o cache deve ou não ser desativado. O armazenamento em cache é ativado por padrão, o que armazena os resultados em cache durante toda a solicitação.
limit	number	Opcional. Altera o número máximo de resultados retornados pela consulta, que tem como padrão 5.
transaction	string	Opcional. Valor recuperado de Firestore.runTransaction(). Marca a operação a ser usada dentro de uma transação.

Exemplo

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

A função Firestore.runTransaction permite que o usuário leia e grave de maneira atômica no Firestore. Se uma gravação simultânea ou outro conflito de transação acontece, a transação é repetida até duas vezes. Quando falha depois de três tentativas, a API é rejeitada com um erro. Essa API retorna uma promessa que é resolvida com uma matriz de IDs de documentos para cada operação de gravação quando a transação é realizada, e é rejeitada com o erro em caso de falha.

Sintaxe

Firestore.runTransaction(callback[, options]);

Parâmetros

Parâmetro	Tipo	Descrição
callback	function	Um callback invocado com um ID da transação de string. O ID da transação pode ser transmitido para chamadas da API de leitura/gravação/consulta. Essa função de callback precisa retornar uma promessa. Ele pode ser executado até três vezes antes de falhar.
options	object	Opções de solicitação alternativas. A única opção compatível é projectId. A chaves de opção desconhecidas são ignoradas. Confira abaixo em Opções.

Opções

Parâmetro	Tipo	Descrição
projectId	string	Opcional. ID do projeto do Google Cloud Platform. Se omitido, o projectId é recuperado da variável de ambiente GOOGLE_CLOUD_PROJECT, desde que a configuração de permissão access_firestore do ID do projeto esteja definida como * ou GOOGLE_CLOUD_PROJECT. Se o contêiner do servidor estiver em execução no Google Cloud, o GOOGLE_CLOUD_PROJECT já vai estar definido como o ID do projeto do Google Cloud.

Exemplo

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Exemplo de erro

Os erros disponíveis em cada função do Firestore são rejeitados com um objeto contendo uma chave reason:

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

Os motivos dos erros podem conter, entre outros, códigos de erro da API REST do Firestore.

Permissões associadas

access_firestore

---

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.

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

Sintaxe

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

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.

---

Messages

As seguintes APIs funcionam juntas para permitir a transmissão de mensagens entre diferentes partes de um contêiner.

---

addMessageListener

Adiciona uma função que detecta uma mensagem de um tipo específico. Quando uma mensagem desse tipo é enviada usando a API sendMessage (normalmente por uma tag), o callback é executado de forma síncrona. O callback é executado com dois parâmetros:

1. messageType:string
2. message:Object

Se o callback for adicionado a um cliente, ele vai receber mensagens em todos os eventos criados por esse cliente. Se o callback precisar receber mensagens apenas de determinado evento, vincule essa API ao evento usando bindToEvent na função onStart da API runContainer. Veja o exemplo.

Sintaxe

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

Parâmetros

Parâmetro	Tipo	Descrição
messageType	string	O tipo de mensagem a ser detectada. Se o valor não for uma string, ele será convertido em uma.
callback	function	O callback a ser executado quando uma mensagem do tipo de mensagem aplicável é enviada. Se o callback não for uma função, a API não terá efeito.

Exemplo

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

Permissões associadas

Requer a permissão use_message. A permissão precisa ser configurada para garantir pelo menos:

• Um tipo de mensagem com Usage de listen ou listen_and_send

---

hasMessageListener

Retorna "true" se um listener de mensagens tiver sido adicionado para o tipo de mensagem informado. Retorna "false", caso contrário.

Sintaxe

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Permissões associadas

Nenhuma.

---

sendMessage

Envia uma mensagem do tipo especificado para um listener registrado. Isso pode ser usado para enviar mensagens de uma tag de volta ao cliente que executou o contêiner.

Sintaxe

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

Parâmetros

Parâmetro	Tipo	Descrição
messageType	string	O tipo de mensagem a ser enviada. Se o valor não for uma string, ele será convertido em uma.
message	object	A mensagem a ser enviada. Se a mensagem não for um objeto, a API não vai ter efeito.

Permissões associadas

Requer a permissão use_message. A permissão precisa ser configurada para garantir pelo menos:

• Um tipo de mensagem com Usage de listen_and_send ou send.

---

Object

Retorna um objeto que oferece 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.

---

Promise

Retorna um objeto que oferece métodos para interagir com promessas.

As promessas são funcionalmente equivalentes às promessas do JavaScript. Cada instância tem três métodos que retornam uma promessa, que permite mais ações quando uma promessa é resolvida:

• .then(): gerencia os casos resolvidos e rejeitados. Ela usa dois callbacks como parâmetros: um para o caso de sucesso e outro para o de falha.
• .catch(): gerencia apenas os casos rejeitados. Ela usa um callback como parâmetro.
• .finally(): oferece uma maneira de executar o código independentemente de a promessa ter sido resolvida ou rejeitada. Ela usa um callback como parâmetro que é invocado sem argumentos.

Uma variável que retorna uma promessa é igual ao valor resolvido da promessa ou false se a promessa for rejeitada.

Observação: uma promessa de JavaScript no modo sandbox expira (é rejeitada) após cinco segundos quando não é resolvida.

Exemplo

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

Retorna uma promessa que:

• é resolvida quando todas as entradas também foram resolvidas; ou
• é rejeitada quando qualquer uma das entradas é rejeitada.

Sintaxe

Promise.all(inputs);

Parâmetros

Parâmetro	Tipo	Descrição
inputs	Array	Uma matriz de valores ou promessas. Se uma entrada não for uma promessa, ela vai ser transmitida como se fosse o valor resolvido de uma promessa. Um erro vai aparecer se a entrada não for uma matriz.

Exemplo

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

Permissões associadas

Nenhuma.

Promise.create

Cria uma promessa que é funcionalmente equivalente a uma promessa do JavaScript.

Sintaxe

Promise.create(resolver);

Parâmetros

Parâmetro	Tipo	Descrição
resolver	function	Uma função que é invocada com duas funções: "resolve" (resolver) e "reject" (rejeitar). A promessa retornada vai ser resolvida ou rejeitada quando o parâmetro correspondente for invocado. Um erro vai aparecer se o resolvedor não for uma função.

Exemplo

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

Permissões associadas

Nenhuma.

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

---