WalkMe Player SDK

Abstract

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.

Installation

Add this dependency to your WalkMe Application:

npm i @walkme/sdk

Production Code

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.

Testing

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();

SDK Testkit

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

Example

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})
  })
})

Init Modes

There exist two modes for loading and initializing the SDK proxy:

common

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.

iframe

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.

:warning: You must create a particular callback function named 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>

Supported data types

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.

Serialization

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:

1. The object contains more than MAX_ITERATIONS keys overall (including nested keys of course).
2. • 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.

example:

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...