Telia ACE Web SDK package for handling data storage in ACE Web SDK clients.
Common storage for Telia ACE clients.
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.
All variants of idContainers implement the same interface (except for the constructors). The interface, idStorage is declared in the filetypes.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
setCobKey: (key: string, lifetime: number) => void;
getCobKey: () => Promise
setCobPrivateKey: (key: string, lifetime: number) => void;
getCobPrivateKey: () => Promise
setCobAccept: (value: string, lifetime: number) => void;
getCobAccept: () => Promise
setCobWsUrl: (value: string, lifetime: number) => void;
getCobWsUrl: () => Promise
setCobLang: (value: string, lifetime: number) => void;
getCobLang: () => Promise
setCobType: (value: string, lifetime: number) => void;
getCobType: () => Promise
setChatUID: (value: string, lifetime: number) => void;
getChatUID: () => Promise
setChatEntrance: (value: string, lifetime: number) => void;
getChatEntrance: () => Promise
setPWUID: (value: string, lifetime: number) => void;
getPWUID: () => Promise
setXDItem: (
client: string,
storageType: 'local' | 'session',
keyName: string,
keyValue: Object
) => void;
getXDItem: (client: string, storageType: 'local' | 'session', keyName: string) => Promise
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.)
The single-origin idContainer is exported as the class
IdContainerSingleOrigin. You instantiate it with
``
const idContainer = await new IdContainerSingleOrigin({
instanceName: 'yourInstance',
companyName: 'yourCompanyName' | null,
});
The multi-origin idContainer is exported as the class IdContainerMultiOrigin.
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.
Instantiate the IdContainerMultiOrigin class:
`some_URL
const idContainer = await new IdContainerMultiOrigin({
iframeURL: ,`
instanceName: 'dev_inst',
companyName: 'ford' | null,
});
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:
`some_URL
const defaultContainer = await new IdContainerMultiOrigin({
iframeURL: ,
instanceName: 'dev_inst',
companyName: 'ford' | null,
});
setDefaultIdContainer(defaultContainer);
``
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.)
We use SemVer for versioning.
See the LICENSE.txt file for details