Working with Component Events

Everee Embed Components use events to communicate with the host application. You should listen for these events as they include important information and helpful errors.

These events carry data payloads with the following shape:

{
  eventType: string, see below
  error: boolean
  errorCode: string [optional]
  errorMessage: string [optional]
  eventHandlerName: string 
}

The Components can broadcast the following kinds of events:

React Native using React Native Webview

In React Native using the react-native-webview library, pass the string ”ReactNativeWebView” as the value of the eventHandlerName parameter when creating an embedded session. Then pass an onMessage prop to your WebView to receive events published by the embedded UX:

<WebView
    ...
    onMessage={(event) => {
        handleEvent(event.nativeEvent.data);
    }}
    ...
 />

When your callback receives an event, its event.nativeEvent.data property will be a JSON string representing the event shape defined above.

For reference, you can look at this sample Expo Snack showing how to register an event handler and receive events.

Native iOS

Add a custom WKScriptMessageHandler to the WKWebView’s WKUserContentController. Use the created session’s eventHandlerName as the name parameter of the WKScriptMessageHandler when adding it to the WKUserContentController. When your handler receives a WKScriptMessage, its body property will be an NSDictionary with the event shape defined above.

Native Android

Create a pair of WebMessagePorts with WebView#createMessageChannel(). Set a WebMessageCallback on the first WebMessagePort, which will receive events from the embedded UX. Wrap the second WebMessagePort in an array, then wrap that in a WebMessage to send the port to the embedded UX:

WebMessagePort[] channel = webView.createMessageChannel();
channel[0].setWebMessageCallback(webMessageCallback);
WebMessage webMessage = new WebMessage("", Array.of(channel[1]));
webView.postWebMessage(webMessage, embeddedSessionUrl);

When your callback receives a WebMessage, its getData() method will return a JSON string representing the event shape defined above.

The web in an <iframe>

Use the MessageChannel API to create a new channel. You’ll use the two ports connected to the channel to communicate between your application and the Embed Component inside the iframe.

const channel = new MessageChannel();

Send port2 into the iframe embedding the Component using the onLoad callback of the <iframe> element:

iframe.addEventHandler(“load”, (event) => {
    event.target.contentWindow.postMessage("", "*", [channel.port2]);
});

Now that the Component has received port2, listen to events from the iframe on port1, the port you retained earlier:

channel.port1.onmessage = (event) => {
    // check event.data.handlerName and event.data.eventType,
    // and handle messages sent from the Everee embedded UX
};

The event's data property will be a JavaScript object with the event shape defined above.

Successful registration

Once an event handler has been successfully registered with the Embed Component, your handler will receive an initial event with eventType: "MESSAGE_PORT_REGISTERED". This event will be delivered strictly before any other events are published from the Component, and confirms that the Component is able to communicate with your host application.

Error codes

You may see errors during development or production. Use these error codes below to identify and resolve issues.