@telia-ace/websdk-id-container

Common storage for Telia ACE clients.

Overview

The idContainer is a system for storing session ids and other settings, for the sub-functions in ACE Web SDK (Chat, Proactive Web, and Cobrowsing). Instead of just saving to local storage, idContainer can provide a storage that works even if the user navigates over different origins, provided that these origins are declared as a part of the web site solutions.

For simplicity, mostly in development and test scenarios, a version of idContainer that only supports storage for only one origin is also provided.

In the future, even more variants of the idContainer will be realised, since browser behaviour when the user opts in for "Block third-party tracking" restricts the possibilities to share storage between origins.

ACE Web SDK uses the concepts instance and companyName. These parameters are provided when an idContainer is created, and that container will not be able to handle data for other instances or companyNames, even if they are on the same origin.

Storage interface

All variants of idContainers implement the same interface (except for the constructors). The interface, idStorage is declared in the file types.ts. The interface looks like

type Ids = {
  cobKey: string;
  cobPrivateKey: string;
  cobAccept: string;
  cobWsUrl: string;
  cobLang: string;
  cobType: string;
  chatUid: string;
  chatEntrance: string;
  PWUID: string;
};

export type eventHandlerFunction = (event: Event) => void;

export interface idStorage {
  getIds: () => Promise<Ids>;
  setCobKey: (key: string, lifetime: number) => void;
  getCobKey: () => Promise<string>;
  setCobPrivateKey: (key: string, lifetime: number) => void;
  getCobPrivateKey: () => Promise<string>;
  setCobAccept: (value: string, lifetime: number) => void;
  getCobAccept: () => Promise<string>;
  setCobWsUrl: (value: string, lifetime: number) => void;
  getCobWsUrl: () => Promise<string>;
  setCobLang: (value: string, lifetime: number) => void;
  getCobLang: () => Promise<string>;
  setCobType: (value: string, lifetime: number) => void;
  getCobType: () => Promise<string>;
  setChatUID: (value: string, lifetime: number) => void;
  getChatUID: () => Promise<string>;
  setChatEntrance: (value: string, lifetime: number) => void;
  getChatEntrance: () => Promise<string>;
  setPWUID: (value: string, lifetime: number) => void;
  getPWUID: () => Promise<string>;
  setXDItem: (
    client: string,
    storageType: 'local' | 'session',
    keyName: string,
    keyValue: Object
  ) => void;
  getXDItem: (client: string, storageType: 'local' | 'session', keyName: string) => Promise<Object>;
  getXDAllItems: (
    client: string,
    storageType: 'local' | 'session'
  ) => Promise<Array<{ keyName: string; keyValue: Object }>>;
  removeXDItem: (client: string, storageType: 'local' | 'session', keyName: string) => void;
  registerXDEventHandler: (client: string, eventHandler: eventHandlerFunction) => void;
  clearIdContainer: () => void;
}

The functions with Chat, PW, and Cob in their names are intended to serve the corresponding functions. There is also a general-purpose interface, XD storage. XD stands for cross-domain, but the cross-domain functionality depends on the idContainer system, presently it works only for the multi-origin version. (In the single-origin version it still works, but only on the same origin.)

Single Origin

The single-origin idContainer is exported as the class IdContainerSingleOrigin. You instantiate it with

    const idContainer = await new IdContainerSingleOrigin({
      instanceName: 'yourInstance',
      companyName: 'yourCompanyName' | null,
    });

Multi Origin

The multi-origin idContainer is exported as the class IdContainerMultiOrigin.

The server - the iframe

The multi-origin storage works by adding an invisible iframe to the web page, that always loads an idContainer server from a web page normally called idContainer.html, that always is accessed from the same origin. The idContainer server web page can be built using the exported object idContainerServer. Build a web page that calls idContainerServer.init.

idContainerServer.init({
  instanceName: 'dev_inst',
  allowedOriginsOrURL: ['http://localhost:9876', 'http://cust.websdk.se:9876'],
});

The instanceName must match the configuration on the client side.

The allowedOriginsOrURL can either be

• a whitelist of trusted origins, i.e. the origins that are a part of the web site solution where ACE Web SDK is inluded.
• a URL to the "secure web clients service" on ClusterWare. This service will provide the idContainerServer with the whitelist.

If a client an on origin not on list sends a request to the idContainerServer, the request is neglected. This protects from fraud sites on e.g. honey-pot domain to access the data in the idContainer. Therefore it is crucial the the web page containing the idContainerServer NOT can have its configuration manipulated, since that would open up for a hacker to add his own origins.

The client - on the top level web page

Instantiate the IdContainerMultiOrigin class:

   const idContainer = await new IdContainerMultiOrigin({
      iframeURL: `some_URL`,
      instanceName: 'dev_inst',
      companyName: 'ford' | null,
    });

Set default idContainer instance

A lot of legacy code, written when the idContainer was a kind of singleton, just imports the idContainer object, and starts using it, assuming that someone else (and only one) has initialized it in a proper way. In order to facilitate compatibility, the code that instantiates an idContainer can set is as "default". Code that imports the idContainer object will then get the default instance, and the code works as previously. The setDefaultIdContainer is exported for this purpose. Example:

   const defaultContainer = await new IdContainerMultiOrigin({
      iframeURL: `some_URL`,
      instanceName: 'dev_inst',
      companyName: 'ford' | null,
    });

    setDefaultIdContainer(defaultContainer);

Build process

This component is compiled with typescript, even though some modules are javascript.

The dependencies have to be declared as depenencies, not peerDependencies. yarn workspace does not use peerDependencies when determining the topological order. So if a package not is built, the typescript compiler won't find any type-info in the dependency, and it fails. (For javascript, that we compile with babel, there is no type check, so if a dependency not is ready in compile time, it does not matter. So using peerDependencies in the js packages works.)

Versioning

We use SemVer for versioning.

License

See the LICENSE.txt file for details