Classes

DDLTools

Typedefs

DDLToolsConfigResetOptions: DDLTools reset options.
DDLToolsConfigLogger: A logger.
DDLToolsConfigValidator: A digital data layer validator.
DDLToolsConfigEmitEventsOptions: DDLTools DOM event emission options.
DDLToolsConfig: DDLTools configuration object.

DDLTools

Kind: global class
See: https://www.w3.org/2013/12/ceddl-201312.pdf

DDLTools
- new DDLTools()
- .reset() ⇒ object
- .set(path, value) ⇒ object
- .get(path, [defaultValue])
- .merge(path, source) ⇒ object
- .push(path, value) ⇒ object
- .publish(path) ⇒ Promise
- .validate() ⇒ boolean
- .configure() ⇒ object
- .use(plugin) ⇒ object
- .setPageInstanceId(value) ⇒ object

new DDLTools()

Provides digital data layer helper functions supporting data layer schema validation for highly-decoupled analytics reporting.

ddlTools.reset() ⇒ `object`

Empties the digital data layer prior to populating data for a new page. Provided for single-page apps to call during page-level widget initialization prior to populating new data in the data layer.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining
Example

ddlTools.reset();

ddlTools.set(path, value) ⇒ `object`

Updates or inserts a data layer entry at the given path with the given value if the given path and value are valid for the data layer schema. If the base path does not already exist, it will be created.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining

Param	Type	Description
path	`string` \| `Array.<string>`	Where the data layer entry should reside
value	`mixed`	What the data layer entry should contain

Example

ddlTools.set("page.pageInfo.pageID", "Nikon Camera");

ddlTools.get(path, [defaultValue])

Retrieves the data layer entry at the given path if the given path contains a value, or the default value if a default value is specified and the given path does not contain a value.

Kind: instance method of DDLTools

Param	Type	Default	Description
path	`string` \| `Array.<string>`		Where the data layer entry resides
[defaultValue]	`mixed`		Optional value to return if the path does not contain a value

Example

const pageId = ddlTools.get("page.pageInfo.pageID");

Example

const pageId = ddlTools.get("page.pageInfo.pageName", 'UnknownPage');

ddlTools.merge(path, source) ⇒ `object`

Deeply merges the data layer entry at the given path with the given value if the given path and value are valid for the data layer schema. If the base path does not already exist, it will be created.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining

Param	Type	Description
path	`string` \| `Array.<string>`	Where the data layer entry should reside
source	`object`	Key/value pairs to merge

Example

ddlTools.merge("transaction.profile", {
  profileInfo: {
    shippingAddress: {
      line1: '1234 Test Dr',
      city: 'Portland',
      stateProvince: 'OR',
      postalCode: '97211',
      country: 'USA'
    }
  }
});

ddlTools.push(path, value) ⇒ `object`

Adds a new data layer entry onto the end of an array at the path given within the digital data layer. If the base path does not already exist, it will be created. If an array does not exist at the path given, a new array will be created at the given path.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining

Param	Type	Description
path	`string` \| `Array.<string>`	Where the data layer array resides within the data layer
value	`mixed`	The data to be added to the array

Example

ddlTools.push("transaction.item", {
  "productId": "N117MP9",
  "sku": "N117MP9-31778",
  "color": "blue"
});

ddlTools.publish(path) ⇒ `Promise`

With event emission enabled, dispatches a "publish" event. This is useful for some types of analytics event handling.

Kind: instance method of DDLTools
Returns: Promise - - Promise to be resolved when publish is complete

Param	Type	Description
path	`string`	Indicates what has been published

Example

ddlTools.publish('page');

ddlTools.validate() ⇒ `boolean`

Validates the existing digitalData object against the DDL Schema, returning true upon success (digitalData is valid), or false otherwise.

NOTE: It is not necessary to use this method for validating changes caused by the DDLTools objects -- those changes are already validated. This method is for validating an initialized value of digitalData which is typically set by server-side processing.

Kind: instance method of DDLTools
Returns: boolean - - Whether or not the digitalData object is valid
Example

window.digitalData = {
  pageInstanceID: 'example-pageInstanceId',
  invalidField: 'bad'
};
const ddlTools = new DDLTools(window.digitalData, ddlValidator);
if (!ddlTools.validate()) {
  console.warn('`window.digitalData` is invalid');
}

ddlTools.configure() ⇒ `object`

Allows package consumers to customize the functionality of the other methods in this class.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining
Params: object options - The new settings to be used
Example

ddlTools.configure({
  logger: specialLogger,
  throw: true
});

ddlTools.use(plugin) ⇒ `object`

Extends the DDLTools instance with the methods from the provided plugin.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining

Param	Type	Description
plugin	`object`	The plugin to use

Example

const pagePlugin = require('ddl-tools-plugin-page');
ddlTools.use(page);

Example

const pagePlugin = require('ddl-tools-plugin-page');
const trxsPlugin = require('ddl-tools-plugin-transactions');
ddlTools.use(pagePlugin, trxsPlugin);

ddlTools.setPageInstanceId(value) ⇒ `object`

Sets the page instance identifier.

The Page Identifier is among the most widely used web analytics data properties. This value SHOULD distinguish among environments, such as whether this page is in development, staging, or production.

Kind: instance method of DDLTools
Returns: object - - Self reference for chaining

Param	Type	Description
value	`string`	value to set