BETA JavaScript Detection API (ai.detection)

The JS Detection API is a means to add information to the delivery context by running detection functions and passing the results via the fitdetection cookie. User-defined key/value pairs go to the detection group of the delivery context.

ai.detection

The namespace for the JS Detection API.

ai.detection.add

Adds a detection result.

ai.detection.add(key, value)

Parameters:

key
{string} The key.
value
{string|number|boolean} The detected value.

Throws

  • {RangeError} if key is a reserved key
  • {RangeError} if key contains ‘=’
  • {RangeError} if key or value contains a character forbidden by the cookie specification or ‘:’

ai.detection.remove

Removes a detection result.

ai.detection.remove(key)

Parameters:

key
{string} The key.

Throws

  • {RangeError} if key is a reserved key

ai.detection.create

Creates a detection object for the given detection function.

var detection = ai.detection.create(detectFunction)

Parameters:

detectFunction
{ai.detection.DetectFunction} The detection function.

Returns {ai.detection.Detection} The detection object, or null if detectFunction is no function.

ai.detection.DetectFunction

A detection function. The function will be run in the window context (this points to the window object).

detectFunction(ev) {}

Parameters:

ev
{Event} The event passed to the detection function. Is passed only, when the detection function is used by an EventDetectionHandle.

Returns {Object} The key/value pairs to add.

ai.detection.Detection

A detection.

ai.detection.Detection#run

Runs the detection function once and adds the returned key/value pairs. Passes errors to ai.config.detection.errorHandler.

detection.run()

ai.detection.Detection#byEvent

Creates an event detection handle and registers it.

detection.byEvent(eventType, eventTarget)

Parameters:

eventType
{string} The event type.
[eventTarget=window]
{Object} The event target (default: window). This object must be either an EventTarget, or provide appropriate addEventListener(eventType, listener) and removeEventListener(eventType, listener) methods (like the FIT ai object).

Returns {ai.detection.EventDetectionHandle} The detection handle, or null if eventType is no string or if eventTarget is no object providing addEventListener() (or at least attachEvent()) and removeEventListener() (or at least detachEvent()).

ai.detection.Detection#byInterval

Creates an interval detection handle and registers it.

detection.byInterval(delay)

Parameters:

delay
{number} The delay [ms].

Returns {ai.detection.IntervalDetectionHandle} The detection handle, or null if delay is no number.

ai.detection.Detection#start

Starts all registered detection handles.

detection.start()

ai.detection.Detection#end

Ends all registered detection handles.

detection.end()

ai.detection.EventDetectionHandle

A detection handle for events.

ai.detection.EventDetectionHandle#start

Starts detecting by adding an event listener for the given type at the given target. Errors during detection are passed to ai.config.detection.errorHandler.

eventDetectionHandle.start()

ai.detection.EventDetectionHandle#end

Ends detecting by removing the event listener for the given type at the given target.

eventDetectionHandle.end()

ai.detection.IntervalDetectionHandle

A detection handle for intervals.

ai.detection.IntervalDetectionHandle#start

Starts detecting by starting a repeated action with the given delay between calls. Errors during detection are passed to ai.config.detection.errorHandler.

intervalDetectionHandle.start()

ai.detection.IntervalDetectionHandle#end

Ends detecting by cancelling the repeated action.

intervalDetectionHandle.end()

ai.detection.ErrorHandler

An error handler which detections pass errors to. The error handler to be used can be configured by setting the ai.config.detection.errorHandler property.

ai.detection.ErrorHandler#error

Handles the given error.

errorHandler.error(e)

Parameters:

e
{Error} The error.

Events

The detectioninit Event

The detectioninit event is fired when the Detection API is available. The event object has no properties in addition to the event type.

Reserved Keys

The following keys are used by FIT and will not appear in the detection group in the delivery context. See the Detection Page for more information about the detected values.

key purpose
cv cookie version
vwp viewport width portrait
vhp viewport height portrait
vwl viewport width landscape
vhl viewport height landscape
vo viewport orientation
dpr device pixel ratio
sw screen width
sh screen height
hps history push state
ph can parse HTML
pe pointer events
ciw webp images
ciwl lossless webp images
ciwa webp images with alpha channel
cis svg images

Example

function _myDetection() {
  function _detectWindowInner(ev) {
    return {
        wiw: window.innerWidth
      , wih: window.innerHeight
    };
  }
  function _detectOnline() {
    return {
      online: navigator.onLine
    };
  }
  function _detectTitle() {
    return {
      title: document.title
    };
  }
  var
    det = ai.detection.create(_detectWindowInner)
  ;
  ai.config.detection.errorHandler = console;
  ai.detection.add('foo', 'bar');
  ['load', 'resize'].forEach(function(eventType/*, pos*/) {  /* byEvent cannot be used directly as parameter for forEach */
    det.byEvent(eventType/*, eventTarget=window*/);
  });
  det.start();
  ai.detection.create(_detectOnline).byInterval(10000).start();
  ai.detection.create(_detectTitle).run();
  ai.detection.remove('foo');
}
ai.addEventListener('detectioninit', _myDetection);