Sandboxed JavaScript

Sandboxed JavaScript is a simplified subset of the JavaScript language that provides a safe way to execute arbitrary JavaScript logic from Google Tag Manager's custom templates. To provide a safe execution environment, some features of JavaScript are restricted or removed. Sandboxed JavaScript is based on ECMAScript 5.1. Some ECMAScript 6 features such as arrow functions and const/let declarations are available.

Global execution environment

Sandboxed JavaScript is not executed in the standard global execution environment like normal JavaScript, so the window object and its properties are not available. This includes methods defined in the global scope like encodeURI or setTimeout, global values like location or document, and global values defined by loaded scripts. In place of these, a global require function is available to all sandboxed JavaScript that provides many of these functions. Values can be read from the window with the copyFromWindow utility.

Note: copyFromWindow creates a deep copy of the values, and it can be an expensive operation to pass those values into and out of the sandbox.

Simplified type system

Sandboxed JavaScript supports the following types: null, undefined, string, number, boolean, array, object, and function. Arrays and objects are created using the literal syntax ( [] {} ), and because there's no access to the standard global execution environment, global constructors like String() and Number() aren't available. There is no new keyword in sandboxed JavaScript, and functions do not have access to the this keyword. Some native type methods have also been removed. See standard library for an exhaustive list of supported native type methods.

Custom template code format

The code written to implement a custom template represents the body of a function that will be executed whenever your tag is fired or your variable is evaluated. This function has a single data parameter (data) that holds all the values configured in the UI for that tag or variable instance, with the keys set to the names of the template parameters specified in the custom template.

Sample beacon tag implementation

const sendPixel = require('sendPixel');
const encodeUri = require('encodeUri');
const encodeUriComponent = require('encodeUriComponent');

let url = encodeUri(data['url']);

if (data['useCacheBuster']) {
  const encode = require('encodeUriComponent');
  const cacheBusterQueryParam = data['cacheBusterQueryParam'] || 'gtmcb';
  const last = url.charAt(url.length - 1);
  let delimiter = '&';
  if (url.indexOf('?') < 0) {
    delimiter = '?';
  } else if (last == '?' || last == '&') {
    delimiter = '';
  }
  url += delimiter +
      encodeUriComponent(cacheBusterQueryParam) + '=' + encodeUriComponent(data['randomNumber']);
}
sendPixel(url, data['gtmOnSuccess'], data['gtmOnFailure']);