intandem-app-com

official usage documentation

Getting started

npm i @vcita/intandem-app-com

Initializing your app or widget

In order to initialize the communication with the host simply call the init method on the handler object, await the result and from this point, the widget communication is ready for use. You should receive a unique widget uid when the widget is set up in the host. The value should be identical to the value held by the host, or the initialization will fail. When using this code snippet, replace [YOUR_WIDGET_UID] with the widget uid you received from the host.

import messageHandler from '@vcita/intandem-app-com';

const hostWindow = window.parent;
const widgetWindow = window;
const widgetUid = '[YOUR_WIDGET_UID]';
let initialized = false;

await messageHandler.init(hostWindow, widgetWindow, widgetUid).then(() => {
    // The widget is ready to communicate with the host
    initialized = true;    
}).catch((error) => {
    // In case there is an error during initialization
    console.log(error);
});

Listening to messages sent from the host

There are two ways available to listen to messages sent from the host:

1. The result is received as a promise

import messageHandler from '@vcita/intandem-app-com';

messageHandler.getJWKSToken((result) => {
  console.log(result);
});

2. The result is received as a callback, after a listener is added by calling addEventListener.

import messageHandler from '@vcita/intandem-app-com';
import { MessageType, WidgetState } from '@vcita/intandem-app-com';

messageHandler.addEventListener(MessageType.GetJWKSToken, (result, ack) => {
  console.log(result.isAck); // The value here will be true
  console.log(result);
  ack(success, result); // Optional
});

messageHandler.getJWKSToken();

This can used in case there is a need to listen to the result in a different location than where the data is requested.

The ack function is used to send an acknowledgment to the host, in case the widget needs to respond to the host. The ack function should be called with two parameters, the first is a boolean value that indicates if the operation was successful, and the second is the data that should be sent to the host. Both parameters are optional, and if the first parameter is not provided, the default value is true.

To remove the listener, call the removeEventListener method.

Sending messages to the host

There is a set of messages that can be sent to the host, and the host will respond with the requested information. The messages are:

1. getJWKSToken
2. getUser
3. getState
4. setState
5. navigate
6. openModal
7. openAppMarket This is a shortcut to open the app market modal

Exiting the widget

When the widget wishes to exit, it should call the destroymethod on the handler object.

messageHandler.destroy();

This will release open listeners and other resources.

Troubleshooting

There are a few common issues that can occur when using the widget

1. Trying to send a message when the widget is not initialized

messageHandler.getState().catch((error) => {
  console.log(error); // The error message will be 'The widget is not initialized'
});

2. Trying to send a message and the answer is not received before timeout

messageHandler.getState().catch((error) => {
  console.log(error); // The error message will be 'Timeout'
});

This situation should not occur, the host is expected to always respond to the messages sent by the widget. In case no data is requested, the host will send an object with {isAck:true}. If you encounter this situation, it's best to contact the host developers to resolve this issue.