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:
let config =ExperienceConfiguration( parameters: ["customKey":"customValue"])let experience = Launcher.getExperience(config: config)<yourView>.addSubview(experience)// You need to ensure the experiences are laid out however you see fit.// For instance, could use autolayout constraints, or setting // their frame
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:
classMyClass:ExperienceViewDelegate {funcdidBecomeReady(fromcontroller: ExperienceView) {// experience is ready to accept incoming messages }// Other methods of the delegate}
....val experience = Launcher.default.getExperience(this, config)experience.sendMessage("my_action", mapOf("my" to "payload"))
import { embed, getExperience, sendUserMessage, onReady,} from'@monterosa-sdk/launcher-kit';constexperience=getExperience();onReady(experience, () => {constpayload= {}; // payload is a key-value objectsendMessage(experience,'my_action', payload);});awaitembed(experience,'container-id');
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:
classMyClass:ExperienceViewDelegate {funcembedExperience() -> ExperienceView {let experience = Launcher.getExperience() experience.delegate = self// We assume the caller sets the Experience in the UIreturn experience }funcdidReceiveMessage(experienceView: ExperienceView, message: MessageData) {switch message.action {case"my_action":let payload = message.payload// Do something with the payload received that relates to // the action my_actiondefault:return } }// Other methods of the delegate}
classMyClass: ExperienceViewListener {funembedExperience() : ExperienceView {....val experience = Launcher.default.getExperience(this, config) experience.listener =this// We assume the caller sets the Experience in the UIreturn experience }overridefunonMessage(experienceView: ExperienceView, message: Message) {when (message.action){"my_action"-> {handlePayload(message.payload) }else-> {} } }}
import { embed, getExperience, onMessage,} from'@monterosa-sdk/launcher-kit';constexperience=getExperience();awaitembed(experience,'container-id');onMessage(experience, (message) => {if (message.action ==='my_action') {constpayload=message.payload;// Do something with the payload received that relates to // the action my_action }});
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:
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:
let experience = Launcher.getExperience()let encodable = ["my":"payload]experience.sendRequest(action: "my_action", payload: payload) { result in switch result { case .success(let message): print(message.action) print(message.payload) case .failure(let error): print(error) }}
import { embed, getExperience, onReady, sendUserRequest,} from'@monterosa-sdk/launcher-kit';constexperience=getExperience();onReady(experience,async () => {constpayload= {}; // payload is a key-value objecttry {constresponse=awaitsendRequest(experience,'my_action', payload); } catch (err) {console.error("Didn't obtain a response", err); }});awaitembed(experience,'container-id');
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:
By adjusting the logging level, you can choose to display only essential information while silencing less critical or verbose log messages.
case silentcase errorcase warningcase infocase debugcase verbose
Core.enableLogging(true)
After enabling logs, they will be shown in Logcat under the kit's corresponding tag, in this scenario, you'll need to filter using the tag LauncherKit.