@ketch-sdk/ketch-data-layer v1.3.2

ketch-data-layer

The ketch-data-layer library implements a Watcher and a set of Fetcher and Structure implementations for fetching and structuring identities.

The following Fetchers are implemented:

• cookie
• dataLayer
• localStorage
• managed
• queryString
• sessionStorage
• window

The following Structures are implemented:

• json
• jwt
• queryString
• semicolon
• string

Identity

An Identity can be described using the following interface:

export interface Identity {
  /**
   * type is the location on the page from which to retrieve identity information
   */
  type: IdentityType;

  /**
   * variable is the name to look up the identity value in the specified location
   */
  variable: string;

  /**
   * format is the encoding of the value
   */
  format: IdentityFormat;

  /**
   * key is the identifier to find the identity within the value if the format is IDENTITY_FORMAT_STRING
   * then key will be undefined
   */
  key?: string;

  /**
   * priority of the identity for consent conflict resolution
   */
  priority?: number;
}

Priority is ignored by this library.

Watcher

The primary class is the Watcher which contains a series of registered identities that it watches for changes to.

Creating a Watcher

const w = new Watcher(window, {interval, timeout})

Creates a new Watcher attached to the given window. The watcher will poll every interval until timeout seconds.

Add an identity

const name: string = ''
const identity: Identity | (() => Promise<string[]> = {}
w.add(name, identity)

Registers an identity with the given name using the provided identity configuration. There are two types of configuration allowed. The first type is an instance of an Identity object. If given this, the watcher selects from it's know library based on the specification in the Identity. The second option, which is a function returning a Promise of string values, can be used if the required identity cannot be described using Identity.

Start watching

await w.start()

Starts the Watcher watching based on the interval and timeout provided in the constructor.

Stop watching

w.stop()

Stops the Watcher.

Immediately notifying

await w.notify()

Immediately fetches and notifies about identities by emitting an identities event.

Add a listener

const listener: (...args: any[]) => void = () => {}
w.addListener('identities', listener)
w.on('identities', listener)

Add a listener function that gets called each time identities change. The argument to the listener will be an Identities map.

Add a one-time listener

const listener: (...args: any[]) => void = () => {}
w.once('identities', listener)

Adds a one-time listener function. The argument to the listener will be an Identities map.

Remove a listener

const listener: (...args: any[]) => void = () => {}
w.removeListener('identities', listener)
w.off('identities', listener)

Removes the given listener.

Remove all listeners

w.removeAllListeners('identities')

Removes all listeners.

Fetcher

A Fetcher is a function with the following signature:

type Fetcher = async (w: Window, name: string) => Promise<any[]>

The w parameter is the Window to attach to. The name is the name of the identity. The return must be an array of discovered, structured identities. The structured identities will be destructured using a Structure function to provide the identity value.

Structure

A Structure is a function with the following signature:

type Mapper = {
  [key: string]: string
}

type Structure = (value: any) => Mapper

Given some structured value, the job of the Structure function is to return a key-value map representing the values in that structure. If there is only a single identifiable value, then the key should be value.

Cookie

This library also exposes some utility functions that may be useful outside of the library's core purpose.

getCookie

import { getCookie } from '@ketch-sdk/ketch-data-layer/cookie'

const name: string = ''
const value = getCookie(window, name)

Retrieves the full raw value of the cookie with the given name.

setCookie

import { setCookie } from '@ketch-sdk/ketch-data-layer/cookie'

const name: string = ''
const value: any = ''
const ttl: number = 2 // 2 days
setCookie(window, name, value, ttl)

Sets the value of the cookie with the given name. The TTL of the cookie is set to ttl days. Note that long-lasting cookies are subject to Intelligent Tracking Prevention limitations.