API per modelli personalizzati

API di base

Queste API funzionano con JavaScript con sandbox per creare modelli personalizzati in Google Tag Manager. Ogni API viene aggiunta con un'istruzione require(), ad esempio:

const myAPI = require('myAPI');

addConsentListener

Registra una funzione listener da eseguire quando cambia lo stato del tipo di consenso specificato.

Il listener specificato verrà richiamato ogni volta che lo stato del tipo di consenso specificato cambia da negato a concesso o da concesso a negato. Un tipo di consenso senza stato viene considerato concesso, quindi il listener non verrà chiamato se un tipo di consenso non impostato viene aggiornato a concesso. Le funzioni di listener saranno responsabili di garantire che il codice venga eseguito il numero appropriato di volte.

Esempio:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

Sintassi

addConsentListener(consentType, listener)

Parametri

Quando viene richiamato un listener, gli vengono passati il tipo di consenso che viene modificato e il nuovo valore di quel tipo di consenso:

Autorizzazioni associate

Autorizzazione access_consent con accesso in lettura per il tipo di consenso.

addEventCallback

L'API addEventCallback consente di registrare una funzione di callback che verrà richiamata al termine di un evento. Il callback verrà richiamato quando tutti i tag per l'evento sono stati eseguiti o se viene raggiunto un timeout dell'evento nella pagina. Alla funzione di callback vengono passati due valori: l'ID del contenitore che richiama la funzione e un oggetto che contiene informazioni sull'evento.

Sintassi

addEventCallback(callback)

Parametri

L'oggetto eventData contiene i seguenti dati:

Esempio

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

Autorizzazioni associate

read_event_metadata

aliasInWindow

L'API aliasInWindow ti consente di creare un alias (ad es. window.foo = window.bar), che aiuta a supportare determinati tag che richiedono l'utilizzo di alias. Assegna il valore nell'oggetto window trovato in fromPath alla chiave nell'oggetto window in toPath. Restituisce true in caso di esito positivo, false in caso contrario.

Sintassi

aliasInWindow(toPath, fromPath)

Parametri

Esempio

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

Autorizzazioni associate

access_globals è obbligatorio sia per toPath sia per fromPath; toPath richiede l'accesso in scrittura, fromPath richiede l'accesso in lettura.

callInWindow

Consente di chiamare funzioni da un percorso diverso dall'oggetto window, in modo controllato dai criteri. Chiama la funzione nel percorso specificato in window con gli argomenti specificati e restituisce il valore. Se il tipo restituito non può essere mappato direttamente a un tipo supportato in JavaScript in sandbox, verrà restituito undefined. Gli otto tipi supportati in JavaScript in sandbox sono null, undefined, boolean, number, string, Array, Object e function. Se il percorso specificato non esiste o non fa riferimento a una funzione, verrà restituito undefined.

Sintassi

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

Parametri

Autorizzazioni associate

access_globals con l'autorizzazione execute abilitata.

callLater

Pianifica una chiamata a una funzione in modo asincrono. La funzione verrà chiamata dopo la restituzione del codice corrente. È equivalente a setTimeout(<function>, 0).

Sintassi

callLater(function)

Parametri

copyFromDataLayer

Restituisce il valore attualmente assegnato alla chiave specificata nel livello dati: il valore trovato nella chiave specificata se è un tipo primitivo, una funzione o un valore letterale oggetto oppure undefined in caso contrario.

Sintassi

copyFromDataLayer(key[, dataLayerVersion])

Parametri

Autorizzazioni associate

read_data_layer

copyFromWindow

Copia una variabile dall'oggetto window. Se il valore in window non può essere mappato direttamente a un tipo supportato in JavaScript in sandbox, verrà restituito undefined. Gli otto tipi supportati in JavaScript in modalità sandbox sono null, undefined, boolean, number, string, Array, Object e function. Restituisce il valore recuperato (e forzato).

Sintassi

copyFromWindow(key)

Parametri

Autorizzazioni associate

access_globals

createArgumentsQueue

Crea una coda popolata con oggetti argomento, a supporto delle soluzioni di tag che lo richiedono.

Crea una funzione nell'ambito globale (ovvero window) utilizzando l'argomento fnKey (stessa semantica di createQueue). Dopo aver creato la funzione, questa API crea un array in window (se non esiste già) utilizzando l'argomento arrayKey.

Quando viene chiamata la funzione creata in fnKey, il relativo oggetto arguments viene inserito nell'array creato in arrayKey. Il valore restituito dall'API è la funzione creata in fnKey.

Questa funzione richiede l'impostazione di lettura e scrittura per fnKey e arrayKey nell'autorizzazione access_globals.

Esempio:

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

Sintassi

createArgumentsQueue(fnKey, arrayKey)

Parametri

Autorizzazioni associate

access_globals

createQueue

Crea un array in window (se non esiste già) e restituisce una funzione che inserisce i valori nell'array.

Questa funzione richiede l'impostazione di lettura e scrittura per arrayKey nell'autorizzazione access_globals.

Esempio:

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

Sintassi

createQueue(arrayKey)

Parametri

Autorizzazioni associate

access_globals

decodeUri

Decodifica tutti i caratteri codificati nell'URI fornito. Restituisce una stringa che rappresenta l'URI decodificato. Restituisce undefined se viene fornito un input non valido.

Esempio:

const decode = require('decodeUri');

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

Sintassi

decodeUri(encoded_uri)

Parametri

Autorizzazioni associate

Nessuno.

decodeUriComponent

Decodifica tutti i caratteri codificati nel componente URI fornito. Restituisce una stringa che rappresenta il componente URI decodificato. Restituisce undefined quando viene fornito un input non valido.

Esempio:

const decode = require('decodeUriComponent');

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

Sintassi

decodeUriComponent(encoded_uri_component)

Parametri

Autorizzazioni associate

Nessuno.

encodeUri

Restituisce un URI (Uniform Resource Identifier) codificato eseguendo l'escape dei caratteri speciali. Restituisce una stringa che rappresenta la stringa fornita codificata come URI. Restituisce undefined se viene fornito un input non valido (un surrogato solitario).

Esempio:

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

Sintassi

encodeUri(uri)

Parametri

Autorizzazioni associate

Nessuno.

encodeUriComponent

Restituisce un URI (Uniform Resource Identifier) codificato eseguendo l'escape dei caratteri speciali. Restituisce una stringa che rappresenta la stringa fornita codificata come URI. Restituisce undefined se viene fornito un input non valido (un surrogato solitario).

Esempio:

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

Sintassi

encodeUriComponent(str)

Parametri

Autorizzazioni associate

Nessuno.

fromBase64

L'API fromBase64 consente di decodificare le stringhe dalla relativa rappresentazione base64. Restituisce undefined quando viene fornito un input non valido.

Sintassi

fromBase64(base64EncodedString)

Parametri

Esempio

const fromBase64 = require('fromBase64');

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

Autorizzazioni associate

Nessuno

generateRandom

Restituisce un numero (intero) casuale all'interno dell'intervallo specificato.

Sintassi

generateRandom(min, max)

Parametri

Autorizzazioni associate

Nessuno.

getContainerVersion

Restituisce un oggetto contenente i dati sul contenitore corrente. L'oggetto restituito contiene i seguenti campi:

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

Esempio

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

Sintassi

getContainerVersion();

Autorizzazioni associate

read_container_data

getCookieValues

Restituisce i valori di tutti i cookie con il nome specificato.

Sintassi

getCookieValues(name[, decode])

Parametri

Autorizzazioni associate

get_cookies

getQueryParameters

Restituisce il primo o tutti i parametri del queryKey dell'URL corrente. Restituisce il primo valore di queryKey o un array di valori di queryKey.

Sintassi

getQueryParameters(queryKey[, retrieveAll])

Parametri

Ad esempio, se l'URL corrente è https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, allora:

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

Autorizzazioni associate

get_url deve consentire il componente query e deve specificare queryKey nelle chiavi di query consentite (o consentire qualsiasi chiave di query).

getReferrerQueryParameters

L'API getReferrerQueryParameters funziona allo stesso modo di getQueryParameters, ma agisce sul referrer anziché sull'URL corrente. Restituisce il primo o tutti i parametri per il queryKey del referrer specificato. Restituisce il primo valore di queryKey o un array di valori di queryKey.

Sintassi

getReferrerQueryParameters(queryKey[, retrieveAll])

Parametri

Ad esempio, se l'URL referrer è https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, allora:

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

Autorizzazioni associate

get_referrer deve consentire il componente query e deve specificare queryKey nelle chiavi di query consentite (o consentire qualsiasi chiave di query).

getReferrerUrl

Dato un tipo di componente, l'API legge l'oggetto documento per il referrer e restituisce una stringa che rappresenta una parte del referrer. Se non viene specificato alcun componente, viene restituito l'URL referrer completo.

Sintassi

getReferrerUrl([component])

Parametri

Autorizzazioni associate

get_referrer deve consentire il componente query e deve specificare queryKey nelle chiavi di query consentite (o consentire qualsiasi chiave di query).

getTimestamp

Deprecato. Preferisci getTimestampMillis.

Restituisce un numero che rappresenta l'ora corrente in millisecondi a partire dall'epoca Unix, come restituito da Date.now().

Sintassi

getTimestamp();

Autorizzazioni associate

Nessuno.

getTimestampMillis

Restituisce un numero che rappresenta l'ora corrente in millisecondi a partire dall'epoca Unix, come restituito da Date.now().

Sintassi

getTimestampMillis();

Autorizzazioni associate

Nessuno.

getType

Restituisce una stringa che descrive il tipo del valore specificato. A differenza di typeof, getType distingue tra array e object.

Sintassi

getType(data.someField)

Note

La tabella seguente elenca le stringhe restituite per ogni valore di input.

Autorizzazioni associate

Nessuno.

getUrl

Restituisce una stringa che rappresenta l'intero URL corrente o una sua parte, dato un tipo di componente e alcuni parametri di configurazione.

Sintassi

getUrl(component)

Parametri

Autorizzazioni associate

get_url

gtagSet

Inserisce un comando gtag set nel data layer, da elaborare il prima possibile dopo che l'evento corrente e i tag che ha attivato hanno terminato l'elaborazione (o è stato raggiunto il timeout di elaborazione dei tag). L'aggiornamento viene elaborato in questo contenitore prima di qualsiasi elemento in coda nella coda del data layer.

Ad esempio, se viene chiamato da un tag attivato in Inizializzazione del consenso, l'aggiornamento verrà applicato prima dell'elaborazione dell'evento di inizializzazione. Ad esempio, ads_data_redaction impostato su true o false o url_passthrough impostato su true o false.

Esempi:

const gtagSet = require('gtagSet');

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

Sintassi

gtagSet(object)

Parametri

Autorizzazioni associate

write_data_layer verifica l'autorizzazione di scrittura per dataLayer per tutte le chiavi specificate. Se l'input di gtagSet è un oggetto semplice, l'API verificherà l'autorizzazione di scrittura per tutte le chiavi appiattite all'interno di quell'oggetto, ad esempio per gtagSet({foo: {bar: 'baz'}}), l'API verificherà l'autorizzazione di scrittura per foo.bar.

Se l'input di gtagSet è una chiave e un valore di oggetto non semplice, l'API controlla l'autorizzazione di scrittura per quella chiave, ad esempio per gtagSet('abc', true) , l'API controlla l'autorizzazione di scrittura per 'abc'.

Tieni presente che se è presente un ciclo nell'oggetto di input, verranno controllate solo le chiavi prima di raggiungere lo stesso oggetto.

injectHiddenIframe

Aggiunge un iframe invisibile alla pagina.

I callback vengono forniti come istanze di funzioni e sono inclusi in funzioni JavaScript che li chiamano.

Sintassi

injectHiddenIframe(url, onSuccess)

Parametri

Autorizzazioni associate

inject_hidden_iframe

injectScript

Aggiunge un tag script alla pagina per caricare l'URL specificato in modo asincrono. I callback vengono forniti come istanze di funzione e sono racchiusi in funzioni JavaScript che li chiamano.

Sintassi

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

Parametri

Autorizzazioni associate

inject_script

isConsentGranted

Restituisce true se il tipo di consenso specificato è concesso.

Il consenso per un determinato tipo di consenso viene considerato concesso se il tipo di consenso è stato impostato su "concesso" o non è stato impostato. Se il tipo di consenso è impostato su un altro valore, verrà considerato non concesso.

L'interfaccia utente di Tag Manager per le impostazioni dei tag offrirà un'opzione per l'attivazione sempre. Se un tag con l'opzione Attiva sempre attivata utilizza questa API, il consenso viene considerato concesso e verrà restituito true, indipendentemente dallo stato effettivo del consenso.

Esempio:

const isConsentGranted = require('isConsentGranted');

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

Sintassi

isConsentGranted(consentType)

Parametri

Autorizzazioni associate

Autorizzazione access_consent con accesso in lettura per il tipo di consenso.

JSON

Restituisce un oggetto che fornisce funzioni JSON.

La funzione parse() analizza una stringa JSON per costruire il valore o l'oggetto descritto dalla stringa. Se il valore non può essere analizzato (ad es. JSON non valido), la funzione restituirà undefined. Se il valore di input non è una stringa, l'input verrà convertito in una stringa.

La funzione stringify() converte l'input in una stringa JSON. Se il valore non può essere analizzato (ad es. l'oggetto ha un ciclo), il metodo restituirà undefined.

Sintassi

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

Parametri

JSON.parse

JSON.stringify

Esempio

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

localStorage

Restituisce un oggetto con metodi per accedere allo spazio di archiviazione locale.

Sintassi

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

Autorizzazioni associate

access_local_storage

Esempio

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

Registra gli argomenti nella console del browser.

Sintassi

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

Parametri

Autorizzazioni associate

logging

makeInteger

Converte il valore specificato in un numero (intero).

Sintassi

makeInteger(value)

Parametri

Autorizzazioni associate

Nessuno.

makeNumber

Converte il valore specificato in un numero.

Sintassi

makeNumber(value)

Parametri

Autorizzazioni associate

Nessuno.

makeString

Restituisce il valore specificato come stringa.

Sintassi

makeString(value)

Parametri

Autorizzazioni associate

Nessuno.

makeTableMap

Converte un oggetto tabella semplice con due colonne in un Map. Viene utilizzato per modificare un campo del modello SIMPLE_TABLE con due colonne in un formato più gestibile.

Ad esempio, questa funzione potrebbe convertire un oggetto tabella:

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

in una mappa:

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

Restituisce un oggetto: il valore Map convertito se sono state aggiunte coppie chiave-valore o null in caso contrario.

Sintassi

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parametri

Autorizzazioni associate

Nessuno.

Math

Un oggetto che fornisce funzioni Math.

Sintassi

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

Parametri

I parametri delle funzioni matematiche vengono convertiti in numeri.

Autorizzazioni associate

Nessuno.

Object

Restituisce un oggetto che fornisce metodi Object.

Il metodo keys() fornisce il comportamento della libreria standard Object.keys(). Restituisce un array di nomi di proprietà enumerabili di un determinato oggetto nello stesso ordine di un ciclo for...in.... Se il valore di input non è un oggetto, verrà forzato a un oggetto.

Il metodo values() fornisce il comportamento della libreria standard Object.values(). Restituisce un array dei valori delle proprietà enumerabili di un determinato oggetto nello stesso ordine di un ciclo for...in.... Se il valore di input non è un oggetto, verrà forzato a un oggetto.

Il metodo entries() fornisce il comportamento della libreria standard Object.entries(). Restituisce un array di coppie [key, value] della proprietà enumerabile di un determinato oggetto nello stesso ordine di un ciclo for...in.... Se il valore di input non è un oggetto, verrà forzato a un oggetto.

Il metodo freeze() fornisce il comportamento di Object.freeze() della libreria standard. Un oggetto bloccato non può più essere modificato; il blocco di un oggetto impedisce l'aggiunta di nuove proprietà, la rimozione di quelle esistenti e la modifica dei valori delle proprietà esistenti. freeze() restituisce lo stesso oggetto passato. Un argomento primitivo o nullo verrà trattato come se fosse un oggetto bloccato e verrà restituito.

Il metodo delete() fornisce il comportamento dell'operatore di eliminazione della libreria standard. Rimuove la chiave specificata dall'oggetto, a meno che l'oggetto non sia bloccato. Come l'operatore di eliminazione della libreria standard, restituisce true se il primo valore di input (objectInput) è un oggetto non bloccato, anche se il secondo valore di input (keyToDelete) specifica una chiave inesistente. In tutti gli altri casi, restituisce false. Tuttavia, differisce dall'operatore di eliminazione della libreria standard per i seguenti motivi:

• keyToDelete non può essere una stringa delimitata da punti che specifica una chiave nidificata.
• delete() non può essere utilizzato per rimuovere elementi da un array.
• delete() non può essere utilizzato per rimuovere proprietà dall'ambito globale.

Sintassi

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

Parametri

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Esempio

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

parseUrl

Restituisce un oggetto che contiene tutte le parti componenti di un determinato URL, simile all'oggetto URL.

Questa API restituirà undefined per qualsiasi URL non valido. Per gli URL formattati correttamente, i campi non presenti nella stringa URL avranno un valore di stringa vuota o, nel caso di searchParams, un oggetto vuoto.

L'oggetto restituito avrà i seguenti campi:

{
  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,
}

Esempio

const parseUrl = require('parseUrl');

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

Sintassi

parseUrl(url);

Parametri

Autorizzazioni associate

Nessuno.

queryPermission

Esegui query sulle autorizzazioni consentite e ristrette. Restituisce un valore booleano: true se è stata concessa un'autorizzazione, false altrimenti.

Sintassi

queryPermission(permission, functionArgs*)

Parametri

Argomenti della funzione

sendPixel, injectScript, injectHiddenIframe: il secondo parametro deve essere una stringa URL.

writeGlobals, readGlobals: il secondo parametro deve essere la chiave scritta o letta.

readUrl: non sono necessari argomenti aggiuntivi per verificare se è possibile leggere l'intero URL. Per eseguire una query per verificare se un determinato componente può essere letto, passa il nome del componente come secondo argomento:

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

Per verificare se una chiave di query specifica è leggibile, passa la chiave di query come terzo parametro:

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

Autorizzazioni associate

Nessuno.

readAnalyticsStorage

Recupera i dati archiviati per l'analisi e restituisce un oggetto con client_id e sessions.

• client_id: una stringa che rappresenta l'ID client utilizzato per Analytics.
• sessions: un array di oggetti contenenti informazioni sulle sessioni attuali. Ogni oggetto include:
  • measurement_id: una stringa che rappresenta l'ID misurazione della destinazione Analytics.
  • session_id: una stringa che rappresenta il timestamp che identifica la sessione corrente.
  • session_number: un numero che rappresenta il conteggio delle sessioni che un utente ha avviato fino alla sessione corrente.

Sintassi

const readAnalyticsStorage = require('readAnalyticsStorage');

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

readAnalyticsStorage(cookieOptions);

Parametri

Autorizzazioni associate

read_analytics_storage

Esempio

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

Restituisce il valore di document.characterSet.

Sintassi

readCharacterSet()

Parametri

Nessuno.

Autorizzazioni associate

read_character_set

readTitle

Restituisce il valore di document.title.

Sintassi

readTitle()

Parametri

Nessuno.

Autorizzazioni associate

read_title

require

Importa una funzione integrata in base al nome. Restituisce una funzione o un oggetto che può essere chiamato dal tuo programma. Restituisce undefined quando il browser non supporta la funzione integrata.

Sintassi

require(name)

Parametri

Esempio

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

Autorizzazioni associate

Nessuno.

sendPixel

Invia una richiesta GET a un endpoint URL specificato.

Sintassi

sendPixel(url, onSuccess, onFailure)

Parametri

Autorizzazioni associate

send_pixel

setCookie

Imposta o elimina il cookie con il nome, il valore e le opzioni specificati.

Sintassi

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

Parametri

Opzioni

• Domain:impostato dalla proprietà options['domain'], se presente. Imposta questo valore su 'auto' per tentare di scrivere il cookie utilizzando il dominio più ampio possibile, in base alla posizione del documento. Se non riesce, proverà con sottodomini sempre più ristretti. Se tutti questi tentativi non vanno a buon fine, proverà a scrivere il cookie senza un dominio. Se non viene impostato alcun valore, verrà tentato di scrivere il cookie senza specificare un dominio. Nota: quando un cookie senza un dominio specificato viene scritto in document.cookie, lo user agent imposta per impostazione predefinita il dominio del cookie sull'host della posizione corrente del documento.
• Percorso:impostato da options['path'], se presente. Quando un cookie senza un percorso specificato viene scritto in document.cookie, lo user agent imposta il percorso del cookie sul percorso della posizione del documento corrente.
• Max-Age: impostato da options['max-age'], se presente.
• Scadenza impostata da options['expires'], se presente. Se presente, deve essere una stringa di data formattata in formato UTC. Date.toUTCString() può essere utilizzato per formattare un Date per questo parametro.
• Sicuro:impostato da options['secure'], se presente.
• SameSite:impostato da options['samesite'], se presente.

Autorizzazioni associate

set_cookies

setDefaultConsentState

Invia un aggiornamento del consenso predefinito al livello dati, da elaborare il prima possibile dopo che l'evento corrente e i tag che ha attivato hanno terminato l'elaborazione (o è stato raggiunto il timeout di elaborazione dei tag). L'aggiornamento viene elaborato in questo contenitore prima di qualsiasi elemento in coda nel data layer. Scopri di più sul consenso.

Esempio:

const setDefaultConsentState = require('setDefaultConsentState');

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

Sintassi

setDefaultConsentState(consentSettings)

Parametri

L'oggetto consentSettings è una mappatura di stringhe di tipo di consenso arbitrarie a 'granted' o 'denied'. Supporta i seguenti valori:

Autorizzazioni associate

Autorizzazione access_consent con accesso in scrittura per tutti i tipi di consenso nell'oggetto consentSettings.

setInWindow

Imposta il valore specificato in window in corrispondenza della chiave specificata. Per impostazione predefinita, questo metodo non imposta il valore in window se è già presente un valore. Imposta overrideExisting su true per impostare il valore in window indipendentemente dalla presenza di un valore esistente. Restituisce un valore booleano: true se il valore è stato impostato correttamente e false in caso contrario.

Sintassi

setInWindow(key, value, overrideExisting)

Parametri

Autorizzazioni associate

access_globals

sha256

Calcola il digest SHA-256 dell'input e richiama un callback con il digest codificato in base64, a meno che l'oggetto options non specifichi una codifica di output diversa.

Esempio:

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

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

Sintassi

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

Parametri

Autorizzazioni associate

Nessuno.

templateStorage

Restituisce un oggetto con metodi per accedere all'archiviazione dei modelli. L'archiviazione dei modelli consente di condividere i dati tra le esecuzioni di un singolo modello. I dati memorizzati nell'archivio dei modelli vengono conservati per tutta la durata della pagina.

Sintassi

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

Autorizzazioni associate

access_template_storage

Esempio

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

L'API toBase64 consente di codificare una stringa in una rappresentazione base64.

Sintassi

toBase64(input)

Parametri

Esempio

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Autorizzazioni associate

Nessuno

updateConsentState

Invia un aggiornamento del consenso al data layer, da elaborare il prima possibile dopo che l'evento corrente e tutti i tag che ha attivato hanno terminato l'elaborazione (o è stato raggiunto il timeout di elaborazione dei tag). L'aggiornamento viene elaborato in questo container prima di qualsiasi elemento in coda nel livello dati. Scopri di più sul consenso.

Esempio:

const updateConsentState = require('updateConsentState');

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

Sintassi

updateConsentState(consentSettings)

Parametri

L'oggetto consentSettings è una mappatura di stringhe di tipo di consenso arbitrarie a 'granted' o 'denied'. Supporta i seguenti valori:

Autorizzazioni associate

Autorizzazione access_consent con accesso in scrittura per tutti i tipi di consenso nell'oggetto consentSettings.

Testare le API

Queste API funzionano con i test JavaScript in sandbox per creare test per i modelli personalizzati in Google Tag Manager. Queste API di test non richiedono una dichiarazione require(). Scopri di più sui test dei modelli personalizzati.

assertApi

Restituisce un oggetto matcher che può essere utilizzato per fare asserzioni in modo fluido sull'API specificata.

Sintassi

assertApi(apiName)

Parametri

Matchers

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

Esempi

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

assertThat

L'API assertThat è modellata sulla libreria [Truth] di Google. Restituisce un oggetto che può essere utilizzato per fare asserzioni in modo fluido sul valore di un soggetto. Un errore di asserzione interromperà immediatamente il test e lo contrassegnerà come non riuscito. Tuttavia, un errore in un test non influirà sugli altri scenari di test.

Sintassi

assertThat(actual, opt_message)

Parametri

Matchers

Esempi

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

Interrompe immediatamente il test corrente e stampa il messaggio specificato, se fornito.

Sintassi

fail(opt_message);

Parametri

Esempio

fail('This test has failed.');

mock

L'API mock ti consente di ignorare il comportamento delle API in sandbox. L'API mock è sicura da utilizzare nel codice del modello, ma è operativa solo in modalità test. I mock vengono reimpostati prima dell'esecuzione di ogni test.

Sintassi

mock(apiName, returnValue);

Parametri

Esempi

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

mockObject

L'API mockObject ti consente di eseguire l'override del comportamento delle API sandbox che restituiscono un oggetto. L'API può essere utilizzata in modo sicuro nel codice del modello, ma è operativa solo in modalità di test. I mock vengono reimpostati prima dell'esecuzione di ogni test.

Sintassi

mockObject(apiName, objectMock);

Parametri

Esempi

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

Esegue il codice per il modello, ovvero il contenuto della scheda Codice, nell' ambiente di test corrente con un determinato oggetto dati di input.

Sintassi

runCode(data)

Parametri

Valore restituito

Restituisce il valore di una variabile per i modelli di variabili; restituisce undefined per tutti gli altri tipi di modelli.

Esempio

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