ADsafe API reference

This reference separates the archived API’s intent from behavior visible in the bundled source. The local adsafe.js header is dated 2017-06-12; the archived documentation is not a promise that every revision behaves identically.

ADSAFE.go(id, callback)

ADSAFE.go starts a widget identified by its containing DIV. The historical structure rules place the call in the last inline script of that fragment, once only. The callback receives dom and, when libraries were initialized, lib. The simple no-library form can use just dom.

In the local implementation, go checks an outstanding library ID for a match, finds the root, checks that it is a DIV and removes its script elements. It constructs the mediated interface, invokes registered host interceptors, then invokes the callback. Callback exceptions are caught and logged. These runtime steps do not replace the static structure checks: they do not independently prove that arbitrary guest code obeys the subset.

ADSAFE.id(id) and ADSAFE.lib(name, factory)

id establishes the current library-loading context and initializes its library object. The local source permits only one outstanding ID. lib requires that context, rejects a forbidden library name and stores the factory’s result under the supplied name. The factory receives the libraries registered so far. Registration must happen between id and go.

// Shape of an approved library file, displayed only.
ADSAFE.lib("format", function (lib) {
  "use strict";
  return {
    label: function (value) {
      return "Value: " + value;
    }
  };
});

The archived rules allow lib only at the top of a library script and id at the top of the widget’s first script. The final go call must use the same root ID. A library’s returned methods are capabilities; review what they can reach and what they return.

ADSAFE.get(object, name) and ADSAFE.set(object, name, value)

These helpers mediate dynamic property access. get returns the selected property’s value. set assigns a value and returns no useful result; it is not a chainable DOM setter. In the local source, the property guard accepts object operands and rejects forbidden names. A numeric key is allowed by the name guard; a string key is checked against the blocked list and underscore rules.

// Ordinary data, not a browser object.
var settings = {label: "Ready"};
ADSAFE.set(settings, "label", "Updated");
var label = ADSAFE.get(settings, "label");

Neither helper sanitizes a value returned by an unsafe host API. They also do not limit retrieval to own properties: the local get implementation performs object[name]. The separate ADSAFE.has helper tests ownership. Prototype contents and the objects supplied by the host therefore remain relevant to the security model.

The dom and bunch objects

The callback’s dom represents the widget root. dom.q(query) returns a bunch wrapping zero or more selected nodes; it does not return a raw browser node. A bunch has its own query and update methods. The query language resembles CSS selectors but is implemented by ADsafe’s parser.

Queries start with a hunter that finds nodes, such as a tag name or a prefixed ID. Filters, called peckers in the original documentation, narrow a selection. dom.q("p.notice") starts with paragraphs and keeps those with the named class. dom.q("#HELLO_MESSAGE") selects a prefixed identifier. A leading class filter is not interchangeable with a complete browser CSS query.

The archived documentation distinguishes singular getters, which return the first node’s result or undefined for an empty bunch, from plural getters, which return an array. Setters generally act across the selection and return the bunch. Creation methods return detached nodes until they are appended. Consult the DOM guide before treating a root operation and a similarly named bunch operation as equivalent.

Events: on, off and fire

bunch.on(type, handler) registers a function on each selected node and returns the bunch. The runtime constructs a mediated event record with fields including type, key, modifier keys, coordinates, and wrapped target and that. Its preventDefault method requests cancellation of a browser default action; its bubble method follows the wrapper’s event path.

var button = dom.q("#HELLO_BUTTON");
button.on("click", function (event) {
  event.preventDefault();
  dom.q("#HELLO_MESSAGE").value("Clicked.");
});
// In the bundled runtime, remove this selection's click handlers:
button.off("click");

fire dispatches through ADsafe’s handler registry. It does not simulate a complete browser interaction or invoke browser default actions. Use a string event name for a straightforward reading example; the bundled implementation dispatches object events using their type property. Root and protected-node markers constrain mediated bubbling and parent access.

Banned member names and why

The bundled list is arguments, callee, caller, constructor, eval, prototype, stack, unwatch, valueOf and watch. String member names that start or end with an underscore are rejected too. These restrictions address paths to functions, execution state, prototypes or browser-specific behavior that could defeat containment. This is a member-name policy, not a list of forbidden words in ordinary text.

The archived language rules also restrict this, the arguments object, with, eval, direct global access and unsafe dynamic subscripts. Some bracket forms, such as numeric expressions, are permitted. The runtime’s name guard is only one part of that broader verifier policy.

Other ADSAFE methods

The original homepage lists create, has, isArray, keys, later, log and remove alongside the startup and property methods. In the local source, later schedules a function with a timeout; log is a debugging convenience; remove deletes a guarded property. The host-only _intercept hook can alter the capabilities delivered before startup. Such changes form part of the trusted policy and must be assessed separately.

For the assumptions behind these APIs, read security and limits. For terms used throughout the documentation, see the glossary.