Communicate with the Experience

The SDK allows you to pass parameters, as well as send and receive custom messages to the embedded Experience so as to assist in developing more complex integrations.

This enables us to share information, such as authentication or user preferences (such as language), between the app and Experience, or to react to user interactions in either, such as notifying your app that the user requested to log in.

Sending parameters to the Experience initialisation

The first and simplest way to provide data to the Experience is via embed parameters. This allows the parent application to pass a dictionary of strings to the embedded Experience at the time the Experience is being initialised.

This approach is specially useful for data you want to seed the Experience with from its very inception, such as the language the user prefers, or a parameter that will customise the Experience from start to finish.

The following snippet outlines how this is achieved on each platform:

JavaScript

import { 
  embed,
  getExperience,
} from '@monterosa/sdk-launcher-kit';

const exp = getExperience({
  parameters: {
    myCustomParameter: 'myCustomValue',
    anotherParameter: 'true'
  }
})

await embed(experience, 'container-id');

JavaScript (deprecated)

Please note that some parameters are reserved by the SDK. If you were to pass a parameter that overlaps one of the ones we use, we will print a warning on the console, and ignore the value you provided in favour of the value the SDK needs to provide.

The protected parameters are:

• h, p, and e.

• Parameters prefixed with mic.

Sending and receiving messages

The other way to exchange data to the Experience is via sending and receiving messages. This allows the parent application and the Experience to send and receive messags between each other.

This is useful for updating the state of the Experience during its runtime, such as notifying about changes in the user log in status, as well as to notify about events, such as a change in the preferred user language.

Awaiting for the Experience to be ready

Given that embedding the Experience on the page is an asynchronous process, we need to await for it to become ready before we can start sending messages, otherwise they wouldn't be received correctly.

If you don't await for the Experience to be ready, your message might be lost.

To identify that the Experience is ready, we can register to receive a notification. The following snippet showcases how to do so:

JavaScript

import { 
    embed,
    getExperience,
    onReady,
} from '@monterosa/sdk-launcher-kit';

const experience = getExperience();

onReady(experience, () => {
  // experience is ready to accept incoming messages
});

await embed(experience, 'container-id');

JavaScript (deprecated)

Sending a message

A message is an object composed of the following:

• An action identifying its purpose.

• A data payload to be exchanged.

It is important to wait before experience is fully embedded before sending messages.

We can send a message by using the following code:

JavaScript

import { 
    embed,
    getExperience,
    sendMessage,
    onReady,
} from '@monterosa/sdk-launcher-kit';

const experience = getExperience();

onReady(experience, () => {
  const payload = {}; // payload is a key-value object

  sendMessage(experience, 'my_action', payload);
});

await embed(experience, 'container-id');

JavaScript (deprecated)

Receiving messages from the Experience

Just as your application can send messages to the Experience, so can the Experience send you messages. Using a snippet similar to the next you'll be notified about messages sent by the Experience, and allow you to treat them as expected:

JavaScript

import { 
  embed,
  getExperience,
  onMessage,
} from '@monterosa/sdk-launcher-kit';

const experience = getExperience();

await embed(experience, 'container-id');

onMessage(experience, (message) => {
  if (message.action === 'my_action') {
    const payload = message.payload;
    
    // Do something with the payload received that relates to 
    // the action my_action
  }
});

JavaScript (deprecated)

Responding to a message

In some scenarios, you'll want to have a request/response pattern when communicating with the Experience. To do so, you will need to first receive a message to respond to, and then respond to it using a snippet similar to the following:

JavaScript

import {
  onMessage,
  respondToMessage,
} from '@monterosa/sdk-launcher-kit';

onMessage(experience, (message) => {
  if (message.action === 'my_action') {
    respondToMessage(experience, message, { my: "payload" });
  }
});

JavaScript (deprecated)

Awaiting a response

We also offer the possibility of sending a message, and await for a response from the Experience. The following snippet demonstrates how to do so in each of the supported platforms:

JavaScript

import {
  embed,
  getExperience,
  onReady,
  sendRequest,
} from '@monterosa/sdk-launcher-kit';

const experience = getExperience();

onReady(experience, async () => {
  const payload = {}; // payload is a key-value object

  try {
    const response = await sendRequest(experience, 'my_action', payload);
  } catch (err) {
    console.error("Didn't obtain a response", err);
  }
});

await embed(experience, 'container-id');

JavaScript (deprecated)

Enable Logging

You can enable logging of the messages being sent between your app and Experience so as to help diagnose and fix potential issues in the integration. To do so, you can follow the next snippets:

JavaScript

import { enableLogging } from '@monterosa/sdk-launcher-kit';

enableLogging();

JavaScript (deprecated)