En este documento se describen las APIs que se pueden usar para el etiquetado en el servidor.
addEventCallback
Registra la función de retrollamada que se invoca al final de un evento. La retrollamada se invoca cuando se han ejecutado todas las etiquetas del evento. A la retrollamada se le transfieren dos valores: el ID del contenedor que invoca la función y un objeto que contiene información sobre el evento.
Cuando esta API se usa en una etiqueta, se asocia al evento concreto. Cuando se usa en un cliente, hay que vincularla con un evento concreto a través de la función bindToEvent
de la API runContainer
. Consulta más detalles en el ejemplo.
Sintaxis
const addEventCallback = require('addEventCallback');
addEventCallback((containerId, eventData) => {
// Take some action based on the event data.
});
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
callback |
function | Es la función que se invoca al final del evento. |
El objeto eventData
contiene los siguientes datos:
Nombre de clave | Tipo | Descripción |
---|---|---|
tags |
Array |
Es un array de objetos de datos de etiqueta. Cada etiqueta que se activa durante el evento tiene una entrada en este array. El objeto de datos de etiqueta contiene el ID de la etiqueta (id ), el estado de su ejecución (status ) y la hora de su ejecución (executionTime ). Los datos de la etiqueta también incluyen los metadatos de etiqueta adicionales que se han configurado en la etiqueta.
|
En un 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();
}
});
});
En una etiqueta:
const addEventCallback = require('addEventCallback');
addEventCallback((containerId, eventData) => {
// This will be called at the end of the current event.
});
Permisos asociados
callLater
Programa una llamada asíncrona a una función. Esta llamada se ejecutará cuando se haya devuelto el código vigente. Equivale a setTimeout(<function>, 0)
.
Ejemplo
const callLater = require('callLater');
const logToConsole = require('logToConsole');
callLater(() => {
logToConsole('Logged asynchronously');
});
Sintaxis
callLater(function)
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
function |
function | Es la función a la que se debe llamar. |
Permisos asociados
Ninguno.
claimRequest
Usa esta API en un cliente para reclamar la solicitud. Cuando se reclama una solicitud, el contenedor no ejecuta más clientes.
Esta API produce una excepción si se invoca en una etiqueta o en una variable. Produce una excepción si se invoca después de que el cliente ha devuelto un resultado (por ejemplo, si se invoca en una retrollamada asíncrona, como en callLater
o la función runContainer
onComplete
).
Un cliente debe reclamar la solicitud usando esta API antes de llamar a la API runContainer
.
Ejemplo
const claimRequest = require('claimRequest');
claimRequest();
Sintaxis
claimRequest();
Permisos asociados
Ninguno.
computeEffectiveTldPlusOne
Devuelve el dominio de nivel superior efectivo +1 (eTLD+1) de la URL o del dominio especificados. El eTLD+1 se obtiene evaluando el dominio según las reglas de la lista de sufijos públicos. Suele ser el dominio de nivel más alto en el que puedes usar cookies.
Si el argumento es nulo o no se ha definido, se devuelve el valor del argumento sin modificar. De lo contrario, el argumento se convierte en una cadena. Si el argumento no es un dominio o una URL válidos, se devuelve una cadena en blanco. Si el servidor no puede obtener la lista de sufijos públicos, se devuelve el valor del argumento sin modificar.
Ejemplo
const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');
// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');
// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');
Sintaxis
computeEffectiveTldPlusOne(domainOrUrl);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
domainOrUrl |
string | Es el dominio o la URL de los que se obtiene el eTLD+1. |
Permisos asociados
Ninguno.
decodeUri
Decodifica los caracteres codificados del URI proporcionado. Devuelve una cadena que representa el URI decodificado. Devuelve undefined
cuando se le proporciona un valor no válido.
Ejemplo
const decodeUri = require('decodeUri');
const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
// ...
}
Sintaxis
decodeUri(encoded_uri);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
encoded_uri |
string | URI codificado por encodeUri() o por otros medios. |
Permisos asociados
Ninguno.
decodeUriComponent
Decodifica los caracteres codificados del componente de URI proporcionado. Devuelve una cadena que representa el componente de URI decodificado. Devuelve undefined
cuando se le proporciona un valor no válido.
Ejemplo
const decodeUriComponent = require('decodeUriComponent');
const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
// ...
}
Sintaxis
decodeUriComponent(encoded_uri_component);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
encoded_uri_component |
string |
Es un componente URI codificado por encodeUriComponent() o por otros medios.
|
Permisos asociados
Ninguno.
encodeUri
Devuelve un URI codificado escapando los caracteres especiales. Devuelve una cadena que representa la cadena que se ha facilitado, codificada como un URI.
Ejemplo
const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');
sendHttpGet('https://www.example.com/' + encodeUri(pathInput));
Sintaxis
encodeUri(uri);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
uri |
string | Es el URI completo. |
Permisos asociados
Ninguno.
encodeUriComponent
Devuelve un URI codificado escapando los caracteres especiales. Devuelve una cadena que representa la cadena que se ha facilitado, codificada como un URI.
Ejemplo
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));
Sintaxis
encodeUriComponent(str);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
str |
string | Es un componente de un URI. |
Permisos asociados
Ninguno.
extractEventsFromMpv1
Traduce una solicitud entrante de Measurement Protocol V1 a una lista con eventos en formato de esquema unificado. Devuelve la lista de eventos extraídos. Si la solicitud no tiene el formato correcto, se produce un error.
Ejemplo
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.
}
}
Sintaxis
extractEventsFromMpv1();
Permisos asociados
Requiere el permiso read_request
. El permiso se debe configurar para permitir al menos el acceso a:
body
query parameters
extractEventsFromMpv2
Traduce una solicitud entrante de Measurement Protocol V2 a una lista con eventos en formato de esquema unificado. Devuelve la lista de eventos extraídos. Si la solicitud no tiene el formato correcto, se produce un error.
Ejemplo
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.
}
}
Sintaxis
extractEventsFromMpv2();
Permisos asociados
Requiere el permiso read_request
. El permiso se debe configurar para permitir al menos el acceso a:
body
query parameters
fromBase64
Decodifica una cadena codificada en base64. Devuelve undefined
si el valor introducido no es válido.
Sintaxis
fromBase64(base64EncodedString);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
base64EncodedString |
string | Cadena codificada en base64. |
Ejemplo
const fromBase64 = require('fromBase64');
const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
// ...
}
Permisos asociados
Ninguno.
generateRandom
Devuelve un número (entero) aleatorio del intervalo que se indique.
Ejemplo
const generateRandom = require('generateRandom');
const randomValue = generateRandom(0, 10000000);
Sintaxis
generateRandom(min, max);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
min |
number | Es el valor mínimo posible del número entero que se devuelve (incluido). |
max |
number | Es el valor máximo posible del número entero que se devuelve (incluido). |
Permisos asociados
Ninguno.
getAllEventData
Devuelve una copia de los datos del evento.
Sintaxis
getAllEventData();
Permisos asociados
getClientName
Devuelve una cadena que contiene el nombre del cliente en cuestión.
Sintaxis
getClientName();
Permisos asociados
getContainerVersion
Devuelve un objeto que contiene datos sobre el contenedor concreto. El objeto devuelto tendrá los campos siguientes:
{
containerId: string,
debugMode: boolean,
environmentName: string,
environmentMode: boolean,
previewMode: boolean,
version: string,
}
Ejemplo
const getContainerVersion = require('getContainerVersion');
const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];
Sintaxis
getContainerVersion();
Permisos asociados
getCookieValues
Devuelve un array que contiene los valores de todas las cookies con el nombre especificado.
Ejemplo
const getCookieValues = require('getCookieValues');
const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
// ...
}
Sintaxis
getCookieValues(name[, noDecode]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
name |
string | Es el nombre de la cookie. |
noDecode |
boolean |
Si es true , los valores de la cookie no se decodifican antes de devolverlos. El valor predeterminado es false .
|
Permisos asociados
getEventData
Devuelve una copia del valor de la ruta indicada en los datos del evento. Devuelve undefined
si no hay datos del evento o si no hay ningún valor en la ruta indicada.
Ejemplo
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 | Descripción |
---|---|---|
keyPath |
any |
Ruta de la clave, con los componentes de la ruta separados por puntos. Los componentes de la ruta pueden ser las claves de un objeto o los índices de un array. Si keyPath no es una cadena, se convierte en una.
|
Sintaxis
getEventData(keyPath);
Permisos asociados
getGoogleScript
Obtiene un recurso de un conjunto predeterminado de secuencias de comandos de Google y devuelve una promesa con la secuencia de comandos y los metadatos de almacenamiento en caché asociados.
La promesa se resolverá en un objeto que contiene dos claves: script
y metadata
. Si la solicitud no se ejecuta correctamente, la promesa se rechazará con una clave reason
.
El objeto metadata
contendrá los metadatos de almacenamiento en caché que se indican a continuación. Estos metadatos se basan en los encabezados de respuesta del recurso. Cada uno de los campos aparecerá solo si el encabezado correspondiente está presente en la respuesta del recurso.
{
'cache-control': string,
'expires': string,
'last-modified': string,
}
Ejemplo
const getGoogleScript = require('getGoogleScript');
getGoogleScript('ANALYTICS').then((result) => {
// Operate on result.script and result.metadata here.
});
Sintaxis
getGoogleScript(script[, options]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
script |
string |
Nombre de la secuencia de comandos. Las secuencias de comandos admitidas son 'ANALYTICS' , 'GTAG' y 'GTM' .La opción 'ANALYTICS' obtiene la secuencia de comandos de Google Analytics de https://www.google-analytics.com/analytics.js .La opción 'GTAG' obtiene la secuencia de comandos de la etiqueta global de sitio web (gtag.js) de https://www.googletagmanager.com/gtag/js .La opción 'GTM' obtiene la secuencia de comandos de Google Tag Manager de https://www.googletagmanager.com/gtm.js .
|
options |
object | Opciones de solicitud alternativas. Consulta a continuación las opciones compatibles. |
Opciones
Opción | Tipo | Descripción |
---|---|---|
id |
string |
Se aplica a 'GTAG' con el ID de medición de gtag y a 'GTM' con el ID de contenedor web (por ejemplo, GTM-XXXX).
|
debug |
any | Si el valor es verdadero, solicita y devuelve la versión de depuración de la secuencia de comandos de medición. |
timeout |
number |
Es el tiempo de espera de la solicitud expresado en milisegundos; los valores no positivos no se tienen en cuenta. Si se agota el tiempo de espera de la solicitud, la retrollamada se invoca con undefined en el caso del valor de la secuencia de comandos y con {} en el caso del objeto de metadatos.
|
Las claves de opción no reconocidas no se tienen en cuenta.
Permisos asociados
Requiere el permiso send_http
. El permiso se debe configurar para permitir al menos el acceso a:
- Permitir Google Domains.
getRemoteAddress
Devuelve una representación en una cadena de la dirección IP donde se originó la solicitud (por ejemplo, 12.345.67.890
en el caso de IPv4 o 2001:0db8:85a3:0:0:8a2e:0370:7334
en el caso de IPv6), leyendo encabezados de solicitud como "Forwarded" y "X-Forwarded-For".
Nota: Esta API hace todo lo posible por descubrir la IP de origen, pero no puede garantizar que el resultado sea preciso.
Sintaxis
getRemoteAddress();
Permisos asociados
Requiere el permiso read_request
. El permiso se debe configurar para permitir al menos el acceso a:
- Encabezados
Forwarded
yX-Forwarded-For
- Dirección IP remota
getRequestBody
Devuelve el cuerpo de la solicitud en forma de cadena si está presente; de lo contrario, devuelve undefined
.
Sintaxis
getRequestBody();
Permisos asociados
getRequestHeader
Devuelve el valor del encabezado de la solicitud en cuestión en forma de cadena si está presente. De lo contrario, devuelve undefined
. Si el encabezado se repite, los valores devueltos se unen con ', '
.
Ejemplo
const getRequestHeader = require('getRequestHeader');
const host = getRequestHeader('host');
Sintaxis
getRequestHeader(headerName);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
headerName |
string | Es el nombre del encabezado. En lo que respecta a este valor, no se distingue entre mayúsculas y minúsculas. |
Permisos asociados
getRequestMethod
Devuelve el método de solicitud (por ejemplo, 'GET'
o 'POST'
) en forma de cadena.
Ejemplo
const getRequestMethod = require('getRequestMethod');
if (getRequestMethod() === 'POST') {
// Handle the POST request here.
}
Sintaxis
getRequestMethod();
Permisos asociados
Ninguno.
getRequestPath
Devuelve la ruta de solicitud sin la cadena de consulta. Por ejemplo, si la URL es '/foo?id=123'
, devuelve '/foo'
. Elimina automáticamente de la ruta el prefijo de URL del contenedor del servidor. Por ejemplo, si la URL del contenedor del servidor es https://example.com/analytics
y la ruta de solicitud es '/analytics/foo'
, devuelve '/foo'
.
Ejemplo
const getRequestPath = require('getRequestPath');
const requestPath = getRequestPath();
if (requestPath === '/') {
// Handle a request for the root path.
}
Sintaxis
getRequestPath();
Permisos asociados
getRequestQueryParameter
Devuelve el valor decodificado del parámetro de la cadena de consulta en cuestión en forma de cadena si está presente. De lo contrario, devuelve undefined
. Si el parámetro se repite en la cadena de consulta, se devolverá el primer valor que aparezca en dicha cadena.
Ejemplo
const getRequestQueryParameter = require('getRequestQueryParameter');
const query = getRequestQueryParameter('query');
if (query) {
// Process query here.
}
Sintaxis
getRequestQueryParameter(name);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
name |
string | Es el nombre del parámetro de consulta. |
Permisos asociados
getRequestQueryParameters
Devuelve los parámetros de consulta de la solicitud HTTP entrante como un objeto que mapea nombres de parámetros de consulta al valor o los valores correspondientes. Los nombres y los valores de los parámetros están decodificados.
Ejemplo
const getRequestQueryParameters = require('getRequestQueryParameters');
const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
// Handle the search query here.
const maxResults = queryParameters['max_results'];
}
Sintaxis
getRequestQueryParameters();
Permisos asociados
getRequestQueryString
Devuelve la consulta de la solicitud en forma de cadena, sin el signo de interrogación inicial, o una cadena vacía si la URL de solicitud no contiene ninguna cadena de consulta.
Ejemplo
const getRequestQueryString = require('getRequestQueryString');
const queryString = getRequestQueryString();
if (queryString !== '') {
// Handle the query string.
}
Sintaxis
getRequestQueryString();
Permisos asociados
getTimestamp
Obsoleta. Es preferible utilizar getTimestampMillis.
Devuelve un número que representa el tiempo transcurrido (en milisegundos) desde el inicio del registro de tiempo Unix, tal y como lo devuelve Date.now()
.
Sintaxis
getTimestamp();
Permisos asociados
Ninguno.
getTimestampMillis
Devuelve un número que representa el tiempo transcurrido (en milisegundos) desde el inicio del registro de tiempo Unix, tal y como lo devuelve Date.now()
.
Sintaxis
getTimestampMillis();
Permisos asociados
Ninguno.
getType
Devuelve una cadena que describe el tipo de valor proporcionado.
Tipo de entrada | Valor devuelto |
---|---|
string | 'string' |
number | 'number' |
boolean | 'boolean' |
null | 'null' |
undefined | 'undefined' |
Array | 'array' |
Object | 'object' |
Function | 'function' |
Ejemplo
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);
}
Sintaxis
getType(value);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
value |
any | Es un valor de entrada. |
Permisos asociados
Ninguno.
isRequestMpv1
Devuelve true
si la solicitud entrante es una solicitud de Measurement Protocol V1. De lo contrario, devuelve false
.
Ejemplo
const isRequestMpv1 = require('isRequestMpv1');
if (isRequestMpv1()) {
// Handle Measurement Protocol V1 request.
const events = extractEventsFromMpv1();
}
Sintaxis
isRequestMpv1();
Permisos asociados
Ninguno.
isRequestMpv2
Devuelve true
si la solicitud entrante es una solicitud de Measurement Protocol V2. De lo contrario, devuelve false
.
Ejemplo
const isRequestMpv2 = require('isRequestMpv2');
if (isRequestMpv2()) {
// Handle Measurement Protocol V2 request.
const events = extractEventsFromMpv2();
}
Sintaxis
isRequestMpv2();
Permisos asociados
Ninguno.
logToConsole
Registra sus argumentos en la consola.
Puedes consultar estos registros en el explorador de registros de la consola de Google Cloud.
En el explorador de registros, ejecuta la consulta logName =~ "stdout"
para ver las entradas de registro creadas por esta API.
Ejemplo
const logToConsole = require('logToConsole');
const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);
Sintaxis
logToConsole(argument1[, argument2, ...]);
Parámetros
La API toma uno o varios argumentos que, si fuera necesario, se convierten en cadenas, y se registran en la consola.
Permisos asociados
makeInteger
Convierte el valor proporcionado en un número (entero).
Sintaxis
makeInteger(value);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
value |
cualquier tipo | Es el valor que se convertirá. |
Permisos asociados
Ninguno.
makeNumber
Convierte el valor en un número.
Sintaxis
makeNumber(value);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
value |
cualquier tipo | Es el valor que se convertirá. |
Permisos asociados
Ninguno.
makeString
Devuelve el valor proporcionado como una cadena.
Sintaxis
makeString(value);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
value |
cualquier tipo | Es el valor que se convertirá. |
Permisos asociados
Ninguno.
makeTableMap
Convierte un objeto de tabla sencilla con dos columnas en un objeto Map
. Esta función se usa para
convertir un campo de plantilla SIMPLE_TABLE
con dos columnas en un formato
más manejable.
Por ejemplo, esta función podría convertir este objeto "table":
[
{'key': 'k1', 'value': 'v1'},
{'key': 'k2', 'value': 'v2'}
]
en este de mapeo:
{
'k1': 'v1',
'k2': 'v2'
}
Devuelve un objeto: si se han añadido pares clave-valor al objeto Map
, devuelve ese objeto convertido;
de lo contrario, devuelve null
.
Sintaxis
makeTableMap(tableObj, keyColumnName, valueColumnName);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
tableObj |
List |
Es el objeto "table" que se convertirá; una lista con mapeos donde cada fila está representada por un objeto Map . Cada nombre de propiedad que aparece en un objeto de fila es el nombre de columna, y el valor de la propiedad es el valor de columna de la fila.
|
keyColumnName |
string |
Es el nombre de la columna cuyos valores se convertirán en claves dentro del objeto Map convertido.
|
valueColumnName |
string |
Es el nombre de la columna cuyos valores se convertirán en valores dentro del objeto Map convertido.
|
Permisos asociados
Ninguno.
parseUrl
Devuelve un objeto que contiene todas las partes de una URL determinada, similar al objeto URL
.
Esta API devolverá undefined
en las URLs con formato incorrecto. En el caso de las URLs con formato correcto, los campos que no estén presentes en la cadena de URL tendrán un valor de cadena vacía o, en el caso de searchParams
, un objeto vacío.
El objeto devuelto tendrá los campos siguientes:
{
href: string,
origin: string,
protocol: string,
username: string,
password: string,
host: string,
hostname: string,
port: string,
pathname: string,
search: string,
searchParams: Object<string, (string|Array)>,
hash: string,
}
Ejemplo
const parseUrl = require('parseUrl');
const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');
Sintaxis
parseUrl(url);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
url |
string | La URL completa que se va a analizar. |
Permisos asociados
Ninguno.
returnResponse
Vacía la respuesta que otras plantillas han definido previamente mediante las APIs que modifican la respuesta, como setCookie, setPixelResponse, setResponseBody, setResponseHeader y setResponseStatus. El valor predeterminado es un código de estado HTTP 200, con el cuerpo vacío y sin encabezados.
Se recomienda utilizar esta API desde una plantilla de cliente.
Sintaxis
returnResponse();
Ejemplo
Consulta el ejemplo de runContainer
.
Permisos asociados
runContainer
Ejecuta la lógica del contenedor (variables, activadores y etiquetas) en el ámbito de un evento. Si se llama a esta API durante la ejecución del contenedor, el contenedor se vuelve a ejecutar.
Las retrollamadas onComplete
y onStart
reciben una función llamada bindToEvent
. Utiliza bindToEvent
para ejecutar una API en el contexto del evento.
Consulta más detalles en el ejemplo addEventCallback.
Se recomienda utilizar esta API desde una plantilla de cliente.
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());
Sintaxis
runContainer(event, onComplete, onStart);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
event |
object | Son los parámetros de evento. |
onComplete |
function | Retrollamada que se invoca después de que todas las etiquetas terminan de activarse. |
onStart |
function | Retrollamada que se invoca inmediatamente, antes de que las etiquetas empiecen a activarse. |
Permisos asociados
sendEventToGoogleAnalytics
Envía un único evento que usa datos de eventos habituales a Google Analytics y devuelve una promesa que se resuelve con un objeto que contiene una clave location
o se rechaza con un objeto que contiene una clave reason
. El destino, Universal Analytics o Google Analytics 4, se basa en el ID de medición de los datos de eventos.
Al campo location
se le asigna el encabezado location
, si está presente.
Ejemplo
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();
});
Sintaxis
sendEventToGoogleAnalytics(event);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
event |
object | Evento en formato de esquema unificado. |
Permisos asociados
Requiere el permiso send_http
. El permiso se debe configurar para permitir al menos el acceso a:
- Permitir Google Domains.
sendHttpGet
Envía una solicitud HTTP GET a la URL indicada y devuelve una promesa que se resuelve con el resultado una vez que la solicitud se completa o agota el tiempo de espera.
El resultado resuelto es un objeto que contiene tres claves: statusCode
, headers
y body
. Si se produce un error en la solicitud (por ejemplo, si la URL no es válida, no hay ruta al host, se produce un fallo en la negociación de SSL, etc.), la promesa se rechazará con {reason:
'failed'}
. Si se ha asignado la opción timeout
y se ha agotado el tiempo de espera de la solicitud, la promesa se rechazará con {reason: 'timed_out'}
.
Ejemplo
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);
Sintaxis
sendHttpGet(url[, options]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
url |
string | URL de la solicitud. |
options |
object | Opciones de solicitud alternativas. Las opciones admitidas son headers y timeout. Las claves de opción desconocidas no se tienen en cuenta. Consulta la sección Opciones más abajo. |
- headers: encabezados de solicitud adicionales representados como un objeto.
- timeout: el tiempo de espera, expresado en milisegundos, antes de que se anule la solicitud.
El valor predeterminado es
15000
.
Permisos asociados
sendHttpRequest
Envía una solicitud HTTP a la URL indicada y devuelve una promesa que se resuelve con la respuesta una vez que la solicitud se completa o agota el tiempo de espera.
El resultado resuelto es un objeto que contiene tres claves: statusCode
, headers
y body
. Si se produce un error en la solicitud (por ejemplo, si la URL no es válida, no hay ruta al host, se produce un fallo en la negociación de SSL, etc.), la promesa se rechazará con {reason:
'failed'}
. Si se ha asignado la opción timeout
y se ha agotado el tiempo de espera de la solicitud, la promesa se rechazará con {reason: 'timed_out'}
.
Ejemplo
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']);
});
Sintaxis
sendHttpRequest(url[, options[, body]]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
url |
string | URL de la solicitud. |
options |
object | Opciones de solicitud alternativas. Las opciones admitidas son: headers, method y timeout. Las claves de opción desconocidas no se tienen en cuenta. Consulta la sección Opciones más abajo. |
body |
string | Cuerpo de la solicitud opcional. |
- headers: encabezados de solicitudes adicionales.
- method: el método de solicitud; el valor predeterminado es "GET".
- timeout: el tiempo de espera, expresado en milisegundos, antes de que se anule la solicitud.
El valor predeterminado es
15000
.
Permisos asociados
sendPixelFromBrowser
Envía un comando al navegador para que cargue la URL proporcionada como una etiqueta <img>
. El protocolo de este comando se puede usar en las etiquetas web Google Analytics: configuración de GA4 y Google Analytics: evento de GA4. Debes habilitar la opción Enviar a contenedor de servidor en la etiqueta de configuración. Consulta más información en las instrucciones.
Esta API devuelve false
si la solicitud entrante no admite el protocolo del comando o si la respuesta ya se ha eliminado. De lo contrario, devuelve true
.
Ejemplo:
const sendPixelFromBrowser = require('sendPixelFromBrowser');
sendPixelFromBrowser('https://example.com/?id=123');
Sintaxis
sendPixelFromBrowser(url)
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
url |
string | Es la URL que se enviará al navegador. |
Permisos asociados
setCookie
Configura o elimina una cookie con las opciones especificadas.
Para eliminar una cookie, debes definir otra con la misma ruta y el mismo dominio con los que se creó la primera, y asignarle un valor "expires" que ya haya pasado, como "Thu, 01 Jan 1970 00:00:00 GMT"
.
Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de nuevo al cliente.
Ejemplo
const setCookie = require('setCookie');
// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});
Sintaxis
setCookie(name, value[, options[, noEncode]]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
name |
string | Nombre de la cookie. No se distingue entre mayúsculas y minúsculas. |
value |
string | Es el valor de la cookie. |
options |
object | Atributos opcionales de la cookie: domain, expires, fallbackDomain, httpOnly, max-age, path, secure y sameSite. Consulta la sección Opciones más abajo. |
noEncode |
boolean |
Si el valor de la cookie es "true", no se codifica. El valor predeterminado es false .
|
domain: el host al que se enviará la cookie. Si se le asigna el valor especial "auto", el host se calculará automáticamente siguiendo esta estrategia:
- eTLD+1 del encabezado
Forwarded
, si está presente. - eTLD+1 del encabezado
X-Forwarded-Host
, si está presente. - eTLD+1 del encabezado
Host
.
- eTLD+1 del encabezado
expires: el tiempo de vida máximo de la cookie. Debe tener una cadena de fecha con formato UTC como, por ejemplo, "Sat, 26 oct 1985 08:21:00 GMT". Si se han configurado
expires
ymax-age
,max-age
tiene prioridad.httpOnly: impide que JavaScript acceda a la cookie si el valor es
true
.max-age: indica los segundos que faltan para que caduque la cookie. Si el valor es cero o un número negativo, la cookie caducará inmediatamente. Si se han configurado
expires
ymax-age
,max-age
tiene prioridad.path: una ruta que debe haber en la URL solicitada; de lo contrario, el navegador no enviará el encabezado "Cookie".
secure:: si esta opción se define como
true
, la cookie solo se envía al servidor cuando se hace una solicitud desde un punto de conexiónhttps:
.sameSite: verifica que una cookie no se debe enviar con solicitudes de origen cruzado. Debe ser
'strict'
,'lax'
o'none'
.
Permisos asociados
setPixelResponse
Asigna un GIF de 1x1 como cuerpo de respuesta, especifica "image/gif" como encabezado "Content-Type", configura los encabezados de almacenamiento en caché de manera que los user-agents no almacenen la respuesta en caché y asigna un estado de respuesta 200.
Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de nuevo al cliente.
Sintaxis
setPixelResponse();
Permisos asociados
Requiere el permiso access_response
. El permiso se debe configurar para permitir al menos el acceso a:
headers
. Debe permitir las siguientes claves:content-type
cache-control
expires
pragma
body
status
setResponseBody
Asigna el cuerpo de la respuesta al argumento.
Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de nuevo al cliente.
Sintaxis
setResponseBody(body[, encoding]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
body |
string | Es el valor que se va a asignar como cuerpo de la respuesta. |
encoding |
string | Codificación de caracteres del cuerpo de la respuesta (de forma predeterminada es 'utf8' ). Los valores admitidos son 'ascii' , 'utf8' , 'utf16le' , 'ucs2' , 'base64' , 'latin1' , 'binary' y 'hex' . |
Permisos asociados
Requiere el permiso access_response
. El permiso se debe configurar para permitir al menos el acceso a:
body
setResponseHeader
Asigna un encabezado a la respuesta que se devuelve. Si la API ha definido anteriormente un encabezado con este nombre (no se distingue entre mayúsculas y minúsculas), la última llamada sobrescribirá o borrará el valor asignado por la llamada anterior.
Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de nuevo al cliente.
Sintaxis
setResponseHeader(name, value);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
name |
string | Es el nombre del encabezado. En los nombres de los encabezados HTTP, no se distingue entre mayúsculas y minúsculas, por lo que el nombre del encabezado aparecerá en minúsculas. |
value |
cadena no definida | Valor del encabezado. Si es nulo o no se ha definido, se borra el encabezado indicado de la respuesta que se devuelve. |
Permisos asociados
Requiere el permiso access_response
. El permiso se debe configurar para permitir al menos el acceso a:
headers
setResponseStatus
Asigna el código de estado HTTP de la respuesta que se devuelve.
Ten en cuenta que se debe llamar a returnResponse para que la respuesta se envíe de nuevo al cliente.
Sintaxis
setResponseStatus(statusCode);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
statusCode |
number | El código de estado HTTP que se devuelve. |
Permisos asociados
Requiere el permiso access_response
. El permiso se debe configurar para permitir al menos el acceso a:
status
sha256
Calcula la síntesis SHA-256 de la entrada e invoca una retrollamada con la síntesis codificada en base64, a menos que el objeto options
especifique una codificación de salida diferente.
El comportamiento y la sintaxis de esta API coinciden con los de la API sha256
de los contenedores web. Sin embargo, es mejor que en las plantillas personalizadas de los contenedores de servidor se use la API sha256Sync
para simplificar el código.
Ejemplo
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'});
Sintaxis
sha256(input, onSuccess, options = undefined);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
input |
string | La cadena que se va a comprimir. |
onSuccess |
function |
Función a la que se hace una llamada usando la síntesis resultante, codificada en base64, a menos que el objeto options especifique una codificación de salida diferente.
|
options |
object |
Opcional para que el objeto especifique la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding , con el valor base64 o hex .
|
Permisos asociados
Ninguno.
sha256Sync
Calcula y devuelve la síntesis SHA-256 de la entrada, codificada en base64, a menos que el objeto options
especifique una codificación de salida diferente.
Ejemplo
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));
Sintaxis
sha256Sync(input, options = undefined);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
input |
string | La cadena que se va a comprimir. |
options |
object |
Opcional para que el objeto especifique la codificación de salida. Si se especifica, el objeto debe contener la clave outputEncoding , con el valor base64 o hex .
|
Permisos asociados
Ninguno.
templateDataStorage
Devuelve un objeto que contiene métodos para acceder al almacenamiento de datos de la plantilla. Este almacenamiento permite compartir datos entre diversas ejecuciones de una sola plantilla. Los datos almacenados en el almacenamiento de datos de plantilla se conservan en el servidor que ejecuta el contenedor. En la mayoría de los casos, hay varios servidores que ejecutan el contenedor, por lo que el almacenamiento de datos de plantilla no garantiza que cada solicitud posterior vaya a tener acceso a los datos.
El término "Data" (datos) del nombre "templateDataStorage" indica que solo los tipos de datos simples, que no son funciones o no hacen referencia a funciones, se pueden almacenar mediante esta API. Todas las funciones o referencias a funciones que se transmiten a la API se almacenan como null
.
Sintaxis
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();
Ejemplo
const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
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, (statusCode, headers, body) => {
if (status >= 200 && status < 300) {
setResponseBody(body);
templateDataStorage.setItemCopy(data.key, body);
data.gtmOnSuccess();
} else {
data.gtmOnFailure();
}
setResponseStatus(statusCode);
});
Permisos asociados
toBase64
Codifica una cadena en base64.
Sintaxis
toBase64(input);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
input |
string | Cadena que se codificará. |
Ejemplo
const toBase64 = require('toBase64');
const base64Hello = toBase64('hello');
Permisos asociados
Ninguno.
BigQuery
Devuelve un objeto que proporciona funciones BigQuery.
La función BigQuery.insert
permite escribir datos en una tabla de BigQuery. Devuelve una promesa que se resuelve si se realiza una inserción correctamente o se rechaza si se produce un error.
Cuando la inserción se realiza correctamente, la promesa se resuelve sin argumentos.
Cuando no se puede realizar la inserción, se rechaza la promesa con una lista de objetos que contienen el motivo del error y posiblemente un objeto de fila si se produce un error. Es posible que una parte de la solicitud se complete correctamente y otras partes, no. En ese caso se rechaza la promesa con una lista de errores para cada fila con un objeto de fila que permite identificar qué filas se han insertado. Consulta la sección Ejemplos de errores que aparece más abajo. Consulta la documentación de BigQuery sobre los mensajes de error para obtener más información.
Sintaxis
BigQuery.insert(connectionInfo, rows[, options]);
Parámetro | Tipo | Descripción |
---|---|---|
connectionInfo |
object |
Define la información necesaria para conectarse a una tabla de BigQuery. Hay un parámetro opcional y dos obligatorios:
|
rows |
Array | Filas que se van a insertar en la tabla. |
options |
object | Opciones de solicitud alternativas. Las opciones admitidas son: ignoreUnknownValues y skipInvalidRows. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo. |
Parámetro | Tipo | Descripción |
---|---|---|
ignoreUnknownValues |
boolean | Si es true , acepta filas que contengan valores que no coincidan con el esquema. Se ignoran los valores desconocidos. El valor predeterminado es false . |
skipInvalidRows |
boolean | Si es true , inserta todas las filas válidas de una solicitud, aunque haya filas no válidas. El valor predeterminado es false . |
El error de módulo no encontrado puede deberse a que tu contenedor del servidor esté ejecutando una versión anterior de nuestra imagen que todavía no incluya el módulo de BigQuery. Vuelve a desplegar tu contenedor del servidor con la misma configuración usando nuestra secuencia de comandos de despliegue. El módulo se incluirá automáticamente cuando termine la operación.
Los errores que no son de inserción suelen incluir un objeto de error con una clave reason
:
[{reason: 'invalid'}]
Los errores de inserción pueden contener varios objetos de error con un array errors
y un objeto row
. A continuación se muestra un ejemplo de una respuesta de error obtenida tras insertar dos filas, donde solo una de las filas contiene un error:
[
{
"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
}
}
]
Ejemplo
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);
Permisos asociados
Firestore
Devuelve un objeto que proporciona funciones de Firestore.
Esta API solo permite usar Firestore en modo nativo, no en modo de almacén de datos.
Firestore.read
La función Firestore.read
lee los datos de un documento de Firestore y devuelve una promesa que se resuelve en un objeto que contiene dos claves: id
y data
. Si el documento no existe, la promesa rechaza la operación y envía un objeto que contiene una clave reason
igual a not_found
.
Sintaxis
Firestore.read(path[, options]);
Parámetro | Tipo | Descripción |
---|---|---|
path |
string | La ruta al documento o a la colección. No puede empezar ni terminar con una barra diagonal (/). |
options |
object | Opciones de solicitud alternativas. Las opciones admitidas son: projectId, disableCache y transaction. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo. |
Parámetro | Tipo | Descripción |
---|---|---|
projectId |
string | Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud. |
disableCache |
boolean | Opcional. Determina si se inhabilita la caché. El almacenamiento en caché está habilitado de forma predeterminada, por lo que se almacenan en caché los resultados mientras dura la solicitud. |
transaction |
string | Opcional. El valor obtenido de Firestore.runTransaction(). Marca la operación que se usará en una transacción. |
Ejemplo
const Firestore = require('Firestore');
return Firestore.read('collection/document', {
projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);
Firestore.write
La función Firestore.write
escribe datos en un documento o una colección de Firestore. Si la ruta lleva a una colección, se creará un documento con un ID generado de manera aleatoria. Si la ruta lleva a un documento y no existe, se creará. Esta API devuelve una promesa que se resuelve en el ID del documento añadido o modificado. Si se utiliza la opción de transacción, la API devuelve una promesa igualmente, pero no contendrá el ID, ya que las escrituras se realizan por lotes.
Sintaxis
Firestore.write(path, input[, options]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
path |
string | La ruta al documento o a la colección. No puede empezar ni terminar con una barra diagonal (/). |
input |
object | El valor que se debe escribir en el documento. Si se define la opción de combinación, la API combinará las claves de la entrada en el documento. |
options |
object | Opciones de solicitud alternativas. Las opciones admitidas son: projectId, merge y transaction. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo. |
Parámetro | Tipo | Descripción |
---|---|---|
projectId |
string | Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud. |
merge |
boolean | Opcional. Si se asigna el valor true , combina las claves de la entrada en el documento. De lo contrario, el método anulará todo el documento. El valor predeterminado es false . |
transaction |
string | Opcional. El valor obtenido de Firestore.runTransaction(). Marca la operación que se usará en una transacción. |
Ejemplo
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
La función Firestore.query
consulta la colección especificada y devuelve una promesa que da como resultado un array de documentos de Firestore que cumplen las condiciones de la consulta. El objeto de documento de Firestore es el mismo que se ha indicado anteriormente en Firestore.read
. Si no hay documentos que cumplan las condiciones de la consulta, la promesa devuelta dará como resultado un array vacío.
Sintaxis
Firestore.query(collection, queryConditions[, options]);
Parámetro | Tipo | Descripción |
---|---|---|
collection |
string | Es la ruta de la colección. No puede empezar ni terminar con una barra diagonal (/). |
queryConditions |
Array | Array de las condiciones de consulta. Cada consulta tiene el formato de un array con tres valores: key, operator y expectedValue. Por ejemplo:
[[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. Las condiciones se unen mediante el operador AND para crear el resultado de la consulta. Consulta los operadores de Firestore para saber qué operadores de consulta se admiten. |
options |
object | Opciones de solicitud alternativas. Las opciones admitidas son: projectId, disableCache, limit y transaction. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo. |
Parámetro | Tipo | Descripción |
---|---|---|
projectId |
string | Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud. |
disableCache |
boolean | Opcional. Determina si se inhabilita la caché. El almacenamiento en caché está habilitado de forma predeterminada, por lo que se almacenan en caché los resultados mientras dura la solicitud. |
limit |
number | Opcional. Cambia el número máximo de resultados que devuelve la consulta. El valor predeterminado es 5. |
transaction |
string | Opcional. El valor obtenido de Firestore.runTransaction(). Marca la operación que se usará en una transacción. |
Ejemplo
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
La función Firestore.runTransaction
permite al usuario leer y escribir atómicamente desde Firestore. Si se produce un conflicto de escritura simultánea o de otro tipo, se volverá a intentar la transacción hasta dos veces. Si falla después de tres intentos, la API rechazará la operación y mostrará un error. Esta API devuelve una promesa que se resuelve en un array de ID de documento, para cada operación de escritura, si la transacción se realiza correctamente y, si no se puede realizar, la rechazará.
Sintaxis
Firestore.runTransaction(callback[, options]);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
callback |
function | Retrollamada que se invoca con un ID de transacción de cadena. El ID de transacción se puede transferir a las llamadas a la API de lectura, escritura y consulta. Esta función de retrollamada debe devolver una promesa. La retrollamada puede ejecutarse hasta tres veces antes de fallar. |
options |
object | Opciones de solicitud alternativas. La única opción admitida es projectId. Las claves de opción desconocidas se ignoran. Consulta la sección Opciones más abajo. |
Parámetro | Tipo | Descripción |
---|---|---|
projectId |
string | Opcional. ID de proyecto de Google Cloud Platform. Si se omite, el projectId se obtiene de la variable de entorno GOOGLE_CLOUD_PROJECT siempre que se haya asignado el valor * o GOOGLE_CLOUD_PROJECT al ajuste del permiso access_firestore correspondiente al ID del proyecto. Si el contenedor del servidor se ejecuta en Google Cloud, GOOGLE_CLOUD_PROJECT ya se habrá definido como ID del proyecto de Google Cloud. |
Ejemplo
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);
Los errores disponibles en cada función de Firestore se rechazarán con un objeto que contenga una clave reason
:
Firestore.read(...).then(onSuccess, (error) => {
if (error.reason === 'unknown') {
// Handle the unknown error here.
}
});
Los motivos de error pueden incluir códigos de error de la API REST de Firestore, entre otros.
Permisos asociados
JSON
Devuelve un objeto que proporciona funciones JSON.
La función parse()
analiza una cadena JSON para crear el valor u objeto descrito por la cadena. Si no se puede analizar el valor (por ejemplo, si el formato de JSON no es correcto), la función devolverá undefined
. Si el valor de entrada no es una cadena, la entrada se convertirá en una cadena.
La función stringify()
convierte la entrada en una cadena JSON. Si el valor no se puede analizar (por ejemplo, si el objeto tiene un ciclo), el método devolverá undefined
.
Ejemplo
const JSON = require('JSON');
// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');
// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});
Sintaxis
JSON.parse(stringInput);
JSON.stringify(value);
Permisos asociados
Ninguno.
Math
Un objeto que proporciona funciones matemáticas Math
.
Sintaxis
const Math = require('Math');
// Retrieve the absolute value.
const absolute = Math.abs(-3);
// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);
// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);
// Round the input to the nearest integer.
const rounded = Math.round(3.1);
// Return the largest argument.
const biggest = Math.max(1, 3);
// Return the smallest argument.
const smallest = Math.min(3, 5);
// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);
// Return the square root of the argument.
const unsquared = Math.sqrt(9);
Parámetros
Los parámetros de las funciones matemáticas se convierten en números.
Permisos asociados
Ninguno.
Messages
Las siguientes APIs funcionan juntas para permitir que se transfieran mensajes entre diferentes partes de un contenedor.
addMessageListener
Añade una función que detecta mensajes de un tipo determinado. Cuando se envía un mensaje de ese tipo usando la API sendMessage
(suele hacerlo una etiqueta), la retrollamada se ejecuta de forma síncrona. La retrollamada se ejecuta con dos parámetros:
messageType:string
message:Object
Si la retrollamada se añade a un cliente, recibe mensajes en todos los eventos que crea el cliente. Si la retrollamada debe recibir mensajes de un solo evento, vincula esta API con el evento usando bindToEvent
en la función onStart
de la API runContainer
. Consulta el ejemplo.
Sintaxis
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 | Descripción |
---|---|---|
messageType |
string | Tipo de mensaje que se procesa para detectarlo. Si el valor no es una cadena, se convierte en una cadena. |
callback |
function | Retrollamada que se ejecuta cuando se envía un mensaje del tipo especificado. Si la retrollamada no es una función, la API no hace nada. |
Ejemplo
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.
});
}
});
});
Permisos asociados
Requiere el permiso use_message
. El permiso se debe configurar para permitir al menos:
- Un tipo de mensaje con
Usage
delisten
olisten_and_send
.
hasMessageListener
Devuelve el valor "true" si se ha añadido un procesador de mensajes para el tipo de mensaje especificado. En caso contrario, devuelve el valor "false".
Sintaxis
const hasMessageListener = require('hasMessageListener');
hasMessageListener('send_pixel');
Permisos asociados
Ninguno.
sendMessage
Envía un mensaje del tipo especificado a un procesador registrado. Esta función puede usarse para enviar mensajes desde una etiqueta al cliente que ha ejecutado el contenedor.
Sintaxis
const sendMessage = require('sendMessage');
sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
messageType |
string | El tipo de mensaje que se va a enviar. Si el valor no es una cadena, se convertirá en una cadena. |
message |
object | El mensaje que se va a enviar. Si el mensaje no es un objeto, la API no hará nada. |
Permisos asociados
Requiere el permiso use_message
. El permiso se debe configurar para permitir al menos:
- Un tipo de mensaje con
Usage
delisten_and_send
osend
.
Object
Devuelve un objeto que proporciona métodos Object
.
El método keys()
proporciona el comportamiento Object.keys() de la biblioteca estándar. Devuelve un array de los propios nombres de propiedades que se pueden enumerar de un objeto determinado en el mismo orden en que lo haría un bucle for...in...
. Si el valor de entrada no es un objeto, se convertirá en un objeto.
El método values()
proporciona el comportamiento Object.values() de la biblioteca estándar. Devuelve un array de los propios valores de propiedades que se pueden enumerar de un objeto determinado en el mismo orden en que lo haría un bucle for...in...
. Si el valor de entrada no es un objeto, se convertirá en un objeto.
El método entries()
proporciona el comportamiento Object.entries() de la biblioteca estándar. Devuelve un array de los propios pares [key, value]
de propiedades que se pueden enumerar de un objeto determinado en el mismo orden en que lo haría un bucle for...in...
. Si el valor de entrada no es un objeto, se convertirá en un objeto.
El método freeze()
proporciona el comportamiento Object.freeze() de la biblioteca estándar. Un objeto inmovilizado ya no se puede cambiar. Inmovilizar un objeto impide que se le añadan nuevas propiedades, que se eliminen las propiedades que ya tenga y que se modifiquen los valores de dichas propiedades. freeze()
devuelve el mismo objeto que se ha transferido. Un argumento primitivo o nulo se trata como si fuera un objeto inmovilizado y se devuelve.
El método delete()
proporciona el comportamiento del operador de eliminación de la biblioteca estándar. Quita la clave proporcionada del objeto, a menos que se inmovilice.
Al igual que el operador de eliminación de la biblioteca estándar, devuelve true
si el primer valor de entrada (objectInput
) es un objeto que no se inmoviliza, aunque el segundo valor de entrada (keyToDelete
) especifique una clave que no existe. Devuelve false
en los demás casos. Sin embargo, se diferencia del operador de eliminación de la biblioteca estándar en lo siguiente:
keyToDelete
no puede ser una cadena delimitada por puntos que especifique una clave anidada.delete()
no se puede usar para quitar elementos de una matriz.delete()
no se puede usar para quitar propiedades del permiso global.
Sintaxis
Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)
Parámetros
Object.keys
Parámetro | Tipo | Descripción |
---|---|---|
objectInput | any | Es el objeto cuyas claves se van a enumerar. Si la entrada no es un objeto, se convertirá en un objeto. |
Object.values
Parámetro | Tipo | Descripción |
---|---|---|
objectInput | any | Es el objeto cuyos valores se van a enumerar. Si la entrada no es un objeto, se convertirá en un objeto. |
Object.entries
Parámetro | Tipo | Descripción |
---|---|---|
objectInput | any | Es el objeto cuyos pares clave-valor se van a enumerar. Si la entrada no es un objeto, se convertirá en un objeto. |
Object.freeze
Parámetro | Tipo | Descripción |
---|---|---|
objectInput | any | Es el objeto que se va a inmovilizar. Si la entrada no es un objeto, se tratará como un objeto inmovilizado. |
Object.delete
Parámetro | Tipo | Descripción |
---|---|---|
objectInput | any | Es el objeto cuya clave se va a eliminar. |
keyToDelete | string | Es la clave de nivel superior que se va a eliminar. |
Ejemplo
const Object = require('Object');
// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});
// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});
// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});
// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});
// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.
Promise
Devuelve un objeto que proporciona métodos para interactuar con promesas.
En términos de funcionalidad, estas promesas son equivalentes a las promesas de JavaScript. Cada instancia tiene tres métodos que devuelven una promesa, lo que permite realizar más acciones cuando se determina una promesa:
.then()
: gestiona los casos resueltos y los casos rechazados. Utiliza dos retrollamadas como parámetros (una para usar en caso de éxito y otra para usar si se producen fallos)..catch()
: solo gestiona los casos rechazados. Utiliza una retrollamada como parámetro..finally()
: proporciona una forma de ejecutar el código tanto si la promesa se ha resuelto como si se ha rechazado. Utiliza una retrollamada como parámetro, que se invoca sin argumento.
Una variable que devuelve una promesa equivale al valor resuelto de la promesa, o bien false
si la promesa agota el tiempo de espera (rechazo).
Ejemplo
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
Devuelve una promesa que:
- Se resuelve cuando se han resuelto todas las entradas.
- Se rechaza cuando se rechaza cualquiera de las entradas.
Sintaxis
Promise.all(inputs);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
inputs |
Array | Array de valores o promesas. Si una entrada no es una promesa, la entrada se envía como si fuera el valor resuelto de una promesa. Devuelve un error si la entrada no es un array. |
Ejemplo
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: ''}]
});
Permisos asociados
Ninguno.
Promise.create
Crea una promesa con funciones equivalentes a las de una promesa de JavaScript.
Sintaxis
Promise.create(resolver);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
resolver |
function | Función que se invoca con dos funciones: resolve y reject. La promesa devuelta se resuelve o se rechaza cuando se invoca el parámetro correspondiente. Devuelve un error si la resolución no es una función. |
Ejemplo
const Promise = require('Promise');
return Promise.create((resolve, reject) => {
// Do asynchronous work that eventually calls resolve() or reject()
});
Permisos asociados
Ninguno.
APIs de prueba
Estas APIs funcionan junto con pruebas de JavaScript en entorno aislado para probar plantillas personalizadas en Google Tag Manager. Estas APIs para pruebas no necesitan una instrucción require()
. [Más información sobre las pruebas de plantillas personalizadas]
assertApi
Devuelve un objeto de comparación que se puede usar para comprobar de manera fluida si determinados valores de la API en cuestión son verdaderos.
Sintaxis
assertApi(apiName)
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
apiName |
string | Nombre de la API que se va a comprobar. Es la misma cadena que se ha enviado a require() . |
Objetos de comparación
Subject.wasCalled()
Subject.wasNotCalled()
Subject.wasCalledWith(...expected)
Subject.wasNotCalledWith(...expected)
Ejemplos
assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');
assertThat
La API assertThat
se basa en la biblioteca [Truth] de Google. Devuelve un objeto que se puede utilizar para comprobar de manera fluida que el valor de un sujeto es verdadero. Si no se puede hacer la verificación, la prueba se detendrá inmediatamente y se marcará como incompleta. No obstante, si no se puede hacer una prueba, los otros casos de prueba no se verán afectados.
Sintaxis
assertThat(actual, opt_message)
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
actual |
any | El valor que se debe utilizar en las comprobaciones. |
opt_message |
string | Mensaje opcional que se mostrará si no se puede hacer la verificación. |
Objetos de comparación
Objeto de comparación | Descripción |
---|---|
isUndefined() |
Verifica que el sujeto es undefined . |
isDefined() |
Verifica que el sujeto no es undefined . |
isNull() |
Verifica que el sujeto es null . |
isNotNull() |
Verifica que el sujeto no es null . |
isFalse() |
Verifica que el sujeto es false . |
isTrue() |
Verifica que el sujeto es true . |
isFalsy() |
Verifica que el sujeto es falso. Los valores falsos son undefined , null , false , NaN , 0 y '' (cadena vacía). |
isTruthy() |
Verifica que el sujeto es verdadero. Los valores falsos son undefined , null , false , NaN , 0 y '' (cadena vacía). |
isNaN() |
Verifica que el sujeto es el valor NAN. |
isNotNaN() |
Verifica que el sujeto es cualquier valor que no sea NAN. |
isInfinity() |
Verifica que el sujeto es un valor infinito positivo o infinito negativo. |
isNotInfinity() |
Verifica que el sujeto es cualquier valor que no sea infinito positivo o infinito negativo. |
isEqualTo(expected) |
Verifica que el sujeto es igual al valor proporcionado. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
isNotEqualTo(expected) |
Verifica que el sujeto no es igual al valor proporcionado. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
isAnyOf(...expected) |
Verifica que el sujeto es igual a uno de los valores proporcionados. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
isNoneOf(...expected) |
Verifica que el sujeto no es igual a ninguno de los valores proporcionados. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
isStrictlyEqualTo(expected) |
Verifica que el sujeto es exactamente igual (=== ) al valor proporcionado. |
isNotStrictlyEqualTo(expected) |
Verifica que el sujeto no es exactamente igual (!== ) al valor proporcionado. |
isGreaterThan(expected) |
Verifica que el sujeto es mayor que (> ) el valor proporcionado en una comparación ordenada. |
isGreaterThanOrEqualTo(expected) |
Verifica que el sujeto es mayor o igual que (>= ) el valor proporcionado en una comparación ordenada. |
isLessThan(expected) |
Verifica que el sujeto es menor que (< ) el valor proporcionado en una comparación ordenada. |
isLessThanOrEqualTo(expected) |
Verifica que el sujeto es menor o igual que (<= ) el valor proporcionado en una comparación ordenada. |
contains(...expected) |
Verifica que el sujeto es un array o una cadena que contiene todos los valores proporcionados en cualquier orden. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
doesNotContain(...expected) |
Verifica que el sujeto es un array o una cadena que no contiene ninguno de los valores proporcionados. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
containsExactly(...expected) |
Verifica que el sujeto es un array que contiene todos los valores proporcionados en cualquier orden y ningún otro valor más. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
doesNotContainExactly(...expected) |
Verifica que el sujeto es un array que contiene un conjunto de valores distinto de los valores proporcionados en cualquier orden. Se trata de una comparación de valores, no de una comparación de referencias. El contenido de los objetos y los arrays se compara repetidamente. |
hasLength(expected) |
Verifica que el sujeto es un array o una cadena con la longitud proporcionada. La verificación siempre falla si el valor no es un array o una cadena. |
isEmpty() |
Verifica que el sujeto es un array o una cadena que está vacía (longitud = 0). La verificación siempre falla si el valor no es un array o una cadena. |
isNotEmpty() |
Verifica que el sujeto es un array o una cadena que no está vacía (longitud > 0). La verificación siempre falla si el valor no es un array o una cadena. |
isArray() |
Verifica que el tipo del sujeto es un array. |
isBoolean() |
Verifica que el tipo del sujeto es un valor booleano. |
isFunction() |
Verifica que el tipo del sujeto es una función. |
isNumber() |
Verifica que el tipo del sujeto es un número. |
isObject() |
Verifica que el tipo del sujeto es un objeto. |
isString() |
Verifica que el tipo del sujeto es una cadena. |
Ejemplos
assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();
fail
Provoca inmediatamente que la prueba actual no se pueda completar y muestra el mensaje que se haya indicado.
Sintaxis
fail(opt_message);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
opt_message |
string | Texto del mensaje de error opcional. |
Ejemplo
fail('This test has failed.');
mock
La API mock
permite anular el comportamiento de las APIs en entorno aislado. La API de ejemplo se puede utilizar de forma segura en el código de las plantillas, pero no funciona cuando no se está usando el modo de prueba. Los ejemplos se restablecen antes de ejecutar cada prueba.
Sintaxis
mock(apiName, returnValue);
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
apiName |
string | Nombre de la API que se debe usar como ejemplo. Es la misma cadena que se ha enviado a require() . |
returnValue |
any | Valor que se debe devolver de la API o la función a la que se llama en lugar de la API. Si returnValue es una función, se llama a esa función en lugar de la API en entorno aislado; si returnValue no es una función, se devuelve ese valor en lugar de la API en entorno aislado. |
Ejemplos
mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
onSuccess();
});
runCode
Ejecuta el código de la plantilla, es decir, el contenido de la pestaña Código, en el entorno de prueba vigente con el objeto de datos de entrada indicado.
Sintaxis
runCode(data)
Parámetros
Parámetro | Tipo | Descripción |
---|---|---|
data |
object | Es el objeto de datos que se va a usar en la prueba. |
Valor devuelto
Devuelve el valor de una variable en el caso de las plantillas de variables. Cuando se trata de otros tipos de plantilla, devuelve undefined
.
Ejemplo
runCode({field1: 123, field2: 'value'});