@d-cat/tag-manager

A fully node, web and TypeScript supported Tag Manager. It offers 100% control on manipulating your environment through a Tag Manager. The built-in dataLayer provides everything you need to futurize your Tag Management.

Install

npm i @d-cat/tag-manager

Usage

The constructor accepts 1 parameter: a manifest, with the following keys:

| parameter | type | Description | | ----------- | :---------------: | :-------------------------------------------------------------------------------------- | | dataLayer | Object | Object that is used to initialize DDM. | | date | Date | Release date of Tag Manager. | | id | Number | Container ID. | | prefix | String | The prefix of the container. | | releaseId | String | Unique releaseID of this deployment. | | tags | ITags[] | An array with the object structure of a tag. More about tags in the next chapter. | | version | String | Version of the used Tag Manager package. |

The render method is the main method of the class. The other methods are invoked within the constructor. You can override this behavior.

import TagManager from '@d-cat/tag-manager';

const myTagManager = () => {
  const tagManager = new TagManager({
    dataLayer: {
      events: ['_ddm.loaded', '_dd.loaded', '_ddm.core.initiated.ready'],
      listenKey: '_ddm.restored',
      version: '2.0.1',
      hooks: '4.0.0',
    },
    date: new Date(Date.now()),
    id: Math.random(),
    prefix: 'vodafone',
    tags: [], // tags array
    version: '1.0.0',
  });

  return tagManager.render(); // undefined
};

NOTE: for convenience the constructor invokes initializeDataLayer, filterTagsOnUrl and sortTagsOnPriority.

initializeDataLayer: void

The initializeDataLayer method initializes DDM on either global (Node) or window (Web). DDM is our Event Emitter and state tree and only communication layer between services.

Once DDM is initialized, it will trigger tag-manager:start.

Example

import TagManager from '@d-cat/tag-manager';

class MyTagManager extends TagManager {
  constructor(...args: any[]) {
    super(...args);
  }

  protected initializeDataLayer(...args: any[]): void {
    super.initializeDataLayer(...args);
    // your logic
  }
}

const myTagManager = () => {
  const tagManager = new MyTagManager({
    dataLayer: {
      events: ['_ddm.loaded', '_dd.loaded', '_ddm.core.initiated.ready'],
      listenKey: '_ddm.restored',
      version: '2.0.1',
      hooks: '4.0.0',
    },
    date: new Date(Date.now()),
    id: Math.random(),
    prefix: 'vodafone',
    tags: [], // tags array
    version: '1.0.0',
  });

  return tagManager.initializeDataLayer(); // undefined
};

filterTagsOnUrl(tags?: ITags[]): ITags[]

The filterTagsOnUrl is used to return only the tags that should execute on the current page. To determine which tags are applicable, it uses the urls array in manifest.

Example

import TagManager from '@d-cat/tag-manager';

class MyTagManager extends TagManager {
  constructor(...args: any[]) {
    super(...args);
  }

  protected filterTagsOnUrl(...args: any[]): void {
    super.filterTagsOnUrl(...args);
    // your logic
  }
}

const myTagManager = () => {
  const tagManager = new MyTagManager({
    dataLayer: {
      events: ['_ddm.loaded', '_dd.loaded', '_ddm.core.initiated.ready'],
      listenKey: '_ddm.restored',
      version: '2.0.1',
      hooks: '4.0.0',
    },
    date: new Date(Date.now()),
    id: Math.random(),
    prefix: 'vodafone',
    tags: [], // tags array
    version: '1.0.0',
  });

  return tagManager.filterTagsOnUrl(tagManager.tags); // []
};

sortTagsOnPriority(tags: ITags[]): ITags[]

The sortTagsOnPriority is used to order tags on a given priority.

Example

import TagManager from '@d-cat/tag-manager';

class MyTagManager extends TagManager {
  constructor(...args: any[]) {
    super(...args);
  }

  protected sortTagsOnPriority(...args: any[]): void {
    super.sortTagsOnPriority(...args);
    // your logic
  }
}

const myTagManager = () => {
  const tagManager = new MyTagManager({
    dataLayer: {
      events: ['_ddm.loaded', '_dd.loaded', '_ddm.core.initiated.ready'],
      listenKey: '_ddm.restored',
      version: '2.0.1',
      hooks: '4.0.0',
    },
    date: new Date(Date.now()),
    id: Math.random(),
    prefix: 'vodafone',
    tags: [], // tags array
    version: '1.0.0',
  });

  return tagManager.sortTagsOnPriority(tagManager.tags); // []
};

render(): void

The render method is used to loop over all the tags and assign a generator to each tag, that keep pending untill all triggers apply.

Example

import TagManager from '@d-cat/tag-manager';

class MyTagManager extends TagManager {
  constructor(...args: any[]) {
    super(...args);
  }

  protected render(...args: any[]): void {
    super.render(...args);
    // your logic
  }
}

const myTagManager = () => {
  const tagManager = new MyTagManager({
    dataLayer: {
      events: ['_ddm.loaded', '_dd.loaded', '_ddm.core.initiated.ready'],
      listenKey: '_ddm.restored',
      version: '2.0.1',
      hooks: '4.0.0',
    },
    date: new Date(Date.now()),
    id: Math.random(),
    prefix: 'vodafone',
    tags: [], // tags array
    version: '1.0.0',
  });

  return tagManager.render(); // undefined
};

ITags

Tags are objects with business rules and a handler that will be invoked when all business rules apply.

const tags = [
  {
    name: `example tag`,
    id: '1234-4567-79810',
    urls: [
      {
        url: '.*',
        reverse: false,
      },
    ],
    handler: () => console.log('all business rules apply'),
    triggers: [
      {
        type: 'instantly',
        id: '12345',
      },
    ],
    priority: 1,
    firingAmount: 1,
  },
];

| Tag property | type | Description | | -------------- | :------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | String | The name of the tag. | | id | String | Unique tag ID. Note that for TypeScript projects uuid/v1 type is used. | | urls | Array<{url: String, reverse: Boolean}> | Array of objects with 2 keys: url (string) and reverse (boolean). The objects in this array determine on what pages the tag should be initialized. Url is a regular expression that matches certain urls and reverse determine if url should match or that it should not match the regex. On each page the regex is tested against the current document.location.href. Note that single page applications should always use ".*" as the Tag Manager will only initialize once. | | handler | Function | The handler that should be invoked. | | triggers | ITrigger | An Array of ITrigger. | | priority | Number | Number that indicates the importancy of a tag. Where 1 is highest priority. | | firingAmount | Number | Number that indicates the amount a tag should fire when all business rules meet. When a tag should always fire, use Infinity as number type. |

ITrigger

Each tag can have unlimited amount of triggers, there are 5 trigger types:

| TriggerType | Description | | ----------- | :---------------------------------------------------------------------------- | | instantly | wildcard to execute immediatelly, without waiting for other triggers | | datalayer | Specific datalayer value of DDM that should or should not equal given values. | | event | Specific DDM event that should trigger. | | domEvent | Specific DOM Event, either on the window, document or on an element id. | | persisted | A specific cookie or localStorage value. |

Example of triggers:

triggers: [
  {
    id: '1',
    type: 'dataLayer',
    name: 'user.id',
    reverse: false,
    value: '.*',
  },
  {
    id: '12345',
    type: 'datalayer',
    name: 'user.bladder',
    reverse: false,
    value: 'bladder1',
  },
  {
    id: '1234567',
    type: 'event',
    name: 'userr',
  },
];

| Trigger property | type | Description | | ---------------- | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Number | Unique tag ID. | | type | String | The type of the trigger: domEvent, event, datalayer, persisted or instantly. | | name | String | The name linked to the trigger type. For each trigger type the name property has a different function. When using domEvent the name property will be the DOM event. When using event, the name property will be the name to listen to (i.e. dataLayer.listen(name) ). When using triggerType dataLayer the name property will be the name of the dataLayer value (i.e. dataLayer.get(name)). When using triggerType persisted the name property will be the cookie or localStorage name. When using triggerType instantly the name property is unneccessary. | | reverse | Boolean | Indicates wether the business rules should match ( false ) or should not match ( true ). | | value | any | The value that should match the business rule. | | element | String | Either window, document or an element ID. |