Configuration

All aspects of the Lytics JSTag are configurable using a monolithic configuration object. Any options not provided by the user will have reasonable defaults wherever possible.

Configuring JSTag

You have four options for configuring the JSTag. Options 1 and 2 are analogous to options 3 and 4, respectively, with the difference that in the latter case where the async tag is used, the tag is being configured before the SDK is actually downloaded. Using the async tag is the recommended best practice for performance reasons.

Option 1: passing the config directly to jstag.init will configure the tag and initialize it.

jstag.init({ cid: 'XXXX' })

Option 2: assigning to jstag.config before jstag.init is called. This can be more convenient in some scenarios, allowing the user to decouple configuration and implementation.

// Assign to the config...
jstag.config = { cid: 'XXXX' };

// Mutate the config
jstag.config.loadid = true;

// Before using jstag, init must be called.
jstag.init();

Assigning to jstag.config post initialization is not supported. However, you can force reinitialization by simply calling jstag.init() again after mutating the config.

// Mutating the config is possible, if not recommended
jstag.config.loadid = false;

// ...but it's necessary to reinitialize the tag after mutation
jstag.init();

Option 3: passing the config to the async tag. Probably the most common way to configure JSTag is by passing the config to the async tag:

<script>/* jstag async snippet elided */</script>
<script>
// Pass the config to the async tag's init method
jstag.init({ cid: 'XXXX' });
</script>

Option 4: assigning the config to jstag.config using the async tag:

<script>/* jstag async snippet elided */</script>
<script>
// Set up the config
jstag.config = { cid: 'XXXX' };

// Mutate the config
jstag.config.blocked = true;

// Initialize the instance
jstag.init();
</script>

General Configuration

The configuration has a few top-level items:

cid

• Type string or string[]
• Required
• The Lytics cid to use for collecting data

One or more CIDs which will be used for collecting data. The Lytics JSTag will broadcast all messages to the Lytics API endpoint for each CID provided.

example

jstag.config = {

  // Your account's cid should be provided below in lieu of XXXX
  cid: 'XXXX'
}

loadid

• Type boolean
• Optional
• Defaults to false

Used for 3rd party identity resolution. When enabled, the Lytics JSTag will make a preflight request to a provided endpoint in order to link 3rd party identifiers to the user's prior to sending any messages.

example

jstag.config = {
  loadid: true
}

blocked

• Type boolean
• Optional
• Defaults to true

When true, the tag will be initialized in "blocked" mode. This mode will enqueue messages until one of the following conditions is true:

• The entity is loaded
• The unblock method is called explicitly

example

jstag.init({
  blocked: true
});

jstag.send({ test: 123 });
jstag.send({ test: 88 });

// No messages have been sent yet...

jstag.unblock();

// Blocked messages are sent in FIFO order...

stream

• Type string
• Optional
• Defaults to 'default'

The name of the Lytics stream to send messages to, by default. This can be overridden on a per-message basis by passing a string parameter to the send method:

example

jstag.config = {
  stream: 'web_traffic'
}

jstag.init();

// This message will be sent to the `web_traffic` stream
jstag.send({ message: 'example message' });

// This message will be sent to the `other` stream
jstag.send('other', { message: 'another example message' });

Advanced options

jstag.config = {

  // You can provide an alternative url for testing...
  url: '//lyticstest.appspot.com'
}

jstag.config = {

  // You can provide an alternative url for testing...
  payloadQueue: [
    message1,
    message2,
    message3
  ]
}

jstag.config = {
  delay: 5000 // 5 seconds
}

jstag.config = {
  cookie: 'altseerid'
}

jstag.config = {
  cookie: 'altsesname'
}

jstag.config = {
  // Pass through `page` and `sort` query param values, if any, with page analysis
  qsargs: [ 'page', 'sort' ]
}

Plugin-level Configuration

The JSTag is plugin-based. All functionality is provided by plugins. Most plugins are configurable. Plugin configuration follows a namespace-based convention, whereby all applicable configuration options are housed under a key reflecting the plugin's namespace. For example, the audit plugin is configurable by passing its options under the key audit in the config.

jstag.init({
  cid: '...',
  audit: {
    topic: '*',
    level: 'verbose'
  }
})

Figure 1: an example of a plugin configuration from the audit plugin.

Refer to plugin documentation for information about each plugin's configuration options.