A WalkMe Application runs in its own iframe
but consumes the services exposed in its container by the Player.
A WalkMe Application developer may use this @walkme/sdk
module to establish
transparently the link with the Player, and to invoke its services.
Add this dependency to your WalkMe Application:
npm i @walkme/sdk
import walkme from '@walkme/sdk';
You must first initialize the SDK library:
await walkme.init();
and then you can use the services.
The walkme
object implements the ISdk interface.
Because the WalkMe Application acts as a client for the Player SDK services, the SDK client library requires many external parts to run, among others the actual Runtime of the SDK, owned and operated by the Player context.
For testing purposes, you may instead use the Testkit provided by the library:
import { testkitFactory } from '@walkme/sdk/dist/testkit';
const testkit = testkitFactory();
The Testkit offers a builder pattern for you to prepare various initial conditions for your test:
const {sdk} = testkit.withStorageItem( ... )
.withArticle( ... )
.with...
.build();
and then you can use the sdk
object normally:
await sdk.init();
// example:
const myContent = await sdk.content.getContent();
please note that this capabilities are still WIP, we'll keep on improving them over time
code.js
import walkme from '@walkme/sdk'
export const init = walkme.init
export const getContent = (options = {}) => walkme.content.getContent(options)
code.test.js
import {init, getContent} from './code'
import {testkitFactory} from '@walkme/sdk/dist/testkit'
describe('demo test', () => {
it('should get content from sdk', async () => {
const {sdk} = testkitFactory().build()
await init()
jest.spyOn(sdk.content, 'getContent')
await getContent({segmentation: true})
expect(sdk.content.getContent).toHaveBeenCalledWith({segmentation: true})
})
})
There exist two modes for loading and initializing the SDK proxy:
This is how a WalkMe App will initialize the SDK:
import walkme from '@walkme/sdk';
await walkme.init({mode: 'common'});
// or simply omitted:
// await walkme.init();
This mode is used in order to obtain a reference to the SDK runtime, when it is owned by the parent frame, which is typically the case for an App.
In this mode, it is assumed that the application is executing in the same context as the Website. This is typically the case if the Customer's Website needs to use directly the services of the platform, exposed by the SDK.
walkme_ready
on the window
object,
in which you can execute init
:
import walkme from '@walkme/sdk';
window.walkme_ready = async () => {
await walkme.init({ mode: 'iframe' });
};
window.walkme_ready = async (sdk) => {
await sdk.init();
const key = 'some key';
const val = 'some key';
await sdk.storage.setItem(key, val, 600);
const res = await sdk.storage.getItem(key);
console.log(res === val); // will print true
}
</script>
The RPC allows for using Functions, and serializable data (i.e. JSON stringify).
You cannot invoke a method via the SDK RPC, whose arguments are deeper objects with methods, or class instances (in particular: no Set, or DOM Elements etc.). Additionally, the depth of compound structures is limited to 150.
When the rpc throws this error message: not serializable
, it means that the number of iterations
executed for serializing the object properties, has exceeded the maximum acceptable number - which is: MAX_ITERATIONS.
This can happen for two main reasons:
- The object contains more than MAX_ITERATIONS keys overall (including nested keys of course).
-
- The object has a getter function which returns the execution call of a function.
- This function returns an object.
- Iterating over this object's properties, can trace us back to the original getter function.
- The result is an infinite loop of interations.
const unresonable = () => ({
get a() {
return unresonable();
},
get b() {
return unresonable();
},
});
This object that the unreasonable
function gives us, without any limitation, can cause the rpc to iterate over its keys forever (or
until he gets a StackOverflowError error).
unresonable().a.b.b.a.b.a.b.a.a.a.a.a.a.b.b.b // And on and on...