Satellite object reference

This document serves as a reference for the client-side _satellite object and the various functions you can perform with it.

track

Code

_satellite.track(identifier: string [, detail: *] )

Example

_satellite.track('contact_submit', { name: 'John Doe' });

track fires all rules using the Direct Call event type that has been configured with the given identifier from the Core tag extension. The above example triggers all rules using a Direct Call event type where the configured identifier is contact_submit. An optional object containing related information is also passed. The detail object can be accessed by entering %event.detail% within a text field in a condition or action or event.detail inside the code editor in a Custom Code condition or action.

getVar

Code

_satellite.getVar(name: string) => *

Example

var product = _satellite.getVar('product');

In the example provided, if a data element exists with a matching name, the data element’s value will be returned. If no matching data element exists, it will then check to see if a custom variable with a matching name has previously been set using _satellite.setVar(). If a matching custom variable is found, its value will be returned.

When an event triggers a rule, you can pass the rule’s corresponding event object into _satellite.getVar() like so:

// event refers to the calling rule's event
var rule = _satellite.getVar('return event rule', event);

setVar

Code

_satellite.setVar(name: string, value: *)

Example

_satellite.setVar('product', 'Circuit Pro');

setVar() sets a custom variable with a given name and value. The value of the variable can later be accessed using _satellite.getVar().

You may optionally set multiple variables at once by passing an object where the keys are variable names and the values are the respective variable values.

_satellite.setVar({ 'product': 'Circuit Pro', 'category': 'hobby' });

getVisitorId

Code

_satellite.getVisitorId() => Object

Example

var visitorIdInstance = _satellite.getVisitorId();

If the Adobe Experience Cloud ID extension is installed on the property, this method returns the Visitor ID instance. See the Experience Cloud ID Service documentation for more information.

logger

Code

_satellite.logger.log(message: string)

_satellite.logger.info(message: string)

_satellite.logger.warn(message: string)

_satellite.logger.error(message: string)

Example

_satellite.logger.error('No product ID found.');

The logger object allows for a message to be logged to the browser console. The message will only be displayed if tag debugging is enabled by the user (by calling _satellite.setDebug(true) or using an appropriate browser extension).

Logging Deprecation Warnings

_satellite.logger.deprecation(message: string)

Example

_satellite.logger.deprecation('This method is no longer supported, please use [new example] instead.');

This logs a warning to the browser console. The message is displayed whether or not tag debugging is enabled by the user.

cookie cookie

_satellite.cookie contains functions for reading and writing cookies. It is an exposed copy of the third-party library js-cookie. For details on more advanced usage of this library, please review the js-cookie documentation.

Set a cookie cookie-set

To set a cookie, use _satellite.cookie.set().

Code

_satellite.cookie.set(name: string, value: string[, attributes: Object])

Example

The following function call writes a cookie that expires in one week.

_satellite.cookie.set('product', 'Circuit Pro', { expires: 7 });

Retrieve a cookie cookie-get

To retrieve a cookie, use _satellite.cookie.get().

Code

_satellite.cookie.get(name: string) => string

Example

The following function call reads a previously set cookie.

var product = _satellite.cookie.get('product');

Remove a cookie cookie-remove

To remove a cookie, use _satellite.cookie.remove().

Code

_satellite.cookie.remove(name: string)

Example

The following function call removes a previously set cookie.

_satellite.cookie.remove('product');

buildInfo

Code

_satellite.buildInfo

This object contains information about the build of the current tag runtime library. The object contains the following properties:

turbineVersion

This provides the Turbine version used inside the current library.

turbineBuildDate

The ISO 8601 date when the version of Turbine used inside the container was built.

buildDate

The ISO 8601 date when the current library was built.

This example demonstrates the object values:

{
  turbineVersion: "14.0.0",
  turbineBuildDate: "2016-07-01T18:10:34Z",
  buildDate: "2016-03-30T16:27:10Z"
}

environment

This object contains information about the environment that the current tag runtime library is deployed on.

Code

_satellite.environment

The object contains the following properties:

{
  id: "ENbe322acb4fc64dfdb603254ffe98b5d3",
  stage: "development"
}

notify

Code

_satellite.notify(message: string[, level: number])

Example

_satellite.notify('Hello world!');

notify logs a message to the browser console. The message will only be displayed if tag debugging is enabled by the user (by calling _satellite.setDebug(true) or using an appropriate browser extension).

An optional logging level can be passed which will affect the styling and filtering of the message being logged. Supported levels are as follows:

3 - Informational messages.

4 - Warning messages.

5 - Error messages.

If you do not provide a logging level or pass any other level value, the message will be logged as a regular message.

setCookie setCookie

Code

_satellite.setCookie(name: string, value: string, days: number)

Example

_satellite.setCookie('product', 'Circuit Pro', 3);

This sets a cookie in the user’s browser. The cookie will persist for the number of days specified.

readCookie

Code

_satellite.readCookie(name: string) => string

Example

var product = _satellite.readCookie('product');

This reads a cookie from the user’s browser.

removeCookie

Code

_satellite.removeCookie(name: string)

Example

_satellite.removeCookie('product');

This removes a cookie from the user’s browser.

Debugging Functions

The following functions should not be accessed from the production code. They are intended only for debugging purposes and will change over time as needed.

container

Code

_satellite._container

Example

monitor

Code

_satellite._monitors

Example

Sample

On your web page running a tag library, add a snippet of code to your HTML. Typically, the code is inserted into the <head> element before the <script> element that loads the tag library. This allows the monitor to catch the earliest system events that occur in the tag library. For example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
  <script>
    window._satellite = window._satellite || {};
    window._satellite._monitors = window._satellite._monitors || [];
    window._satellite._monitors.push({
      ruleTriggered: function (event) {
        console.log(
          'rule triggered',
          event.rule
        );
      },
      ruleCompleted: function (event) {
        console.log(
          'rule completed',
          event.rule
        );
      },
      ruleConditionFailed: function (event) {
        console.log(
          'rule condition failed',
          event.rule,
          event.condition
        );
      }
    });
  </script>
  <script src="//assets.adobedtm.com/launch-EN5bfa516febde4b22b3e7c6f96f6b439f.min.js"
          async></script>
</head>
<body>
  <h1>Click me!</h1>
</body>
</html>

In the first script element, because the tag library has not been loaded yet, the initial _satellite object is created and an array on _satellite._monitors is initialized. The script then adds a monitor object to that array. The monitor object can specify the following methods which will later be called by the tag library:

ruleTriggered

This function is called after an event triggers a rule but before the rule’s conditions and actions have been processed. The event object passed to ruleTriggered contains information about the rule that was triggered.

ruleCompleted

This function is called after a rule has been fully processed. In other words, the event has occurred, all conditions have passed, and all actions have been executed. The event object passed to ruleCompleted contains information about the rule that was completed.

ruleConditionFailed

This function is called after a rule has been triggered and one of its conditions has failed. The event object passed to ruleConditionFailed contains information about the rule that was triggered and the condition that failed.

If ruleTriggered is called, either ruleCompleted or ruleConditionFailed will be called shortly thereafter.

Testing the Monitor

The example above specifies all three methods in the monitor. When they’re called, the monitor logs out relevant information. To test this, set up two rules in the tag library:

If you open the page in Chrome, open the browser console, and select the page, the following appears in the console:

Additional hooks or additional information might be added to these handlers as needed.