Use the SDK to communicate with the embedded Experience
The SDK allows 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.
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:
iOS
Android
Javascript
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
class MyActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
val experienceConfiguration: ExperienceConfiguration = ExperienceConfiguration(parameters = hashMapOf("custom_key" to "custom_value"))
val experienceView = Launcher.default.getExperience(this, url, configuration = experienceConfiguration))
}
}
import {
embed,
getExperience,
} from '@monterosa-sdk/launcher-kit';
const exp = getExperience({
parameters: {
myCustomParameter: 'myCustomValue',
anotherParameter: 'true'
}
})
await embed(experience, 'container-id');
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, ande.- Parameters prefixed with
mic.
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.
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:
iOS
Android
Javascript
class MyClass: ExperienceViewDelegate {
func didBecomeReady(from controller: ExperienceView) {
// experience is ready to accept incoming messages
}
// Other methods of the delegate
}
class MyActivity : AppCompatActivity(), ExperienceViewListener {
override fun onCreate(savedInstanceState: Bundle?) {
val experienceView = Launcher.default.getExperience(this, testConfiguration.customUrl, eventId = testConfiguration.eventId, configuration = testConfiguration.experienceConfiguration)
experienceView.listener = this
}
override fun onReady(experienceView: ExperienceView) {
// experience is ready to accept incoming messages
}
}
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');
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:
iOS
Android
Javascript
let experience = Launcher.getExperience()
let encodable = ["my": "payload]
experience.sendMessage(action: "my_action", payload: ["my": "payload"])
val experience = Launcher.default.getExperience(context = this, configuration = ExperienceConfiguration())
experience.sendMessage(action = "my_action", payload = mapOf("my" to "payload"))
import {
embed,
getExperience,
sendUserMessage,
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');
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:
iOS
Android
Javascript
class MyClass: ExperienceViewDelegate {
func embedExperience() -> ExperienceView {
let experience = Launcher.getExperience()
experience.delegate = self
// We assume the caller sets the Experience in the UI
return experience
}
func didReceiveMessage(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_action
default:
return
}
}
// Other methods of the delegate
}
class MyClass: ExperienceViewListener {
fun embedExperience() : ExperienceView {
val experience = Launcher.default.getExperience(context = this, configuration = ExperienceConfiguration())
experience.listener = this
// We assume the caller sets the Experience in the UI
return experience
}
override fun onMessage(experienceView: ExperienceView, message: Message) {
when (message.action){
"my_action" -> {
handlePayload(message.payload)
}
else -> {}
}
}
}
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
}
});
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:
iOS
Android
Javascript
func didReceiveMessage(experienceView: ExperienceView, message: MessageData) {
switch message.action {
case "my_action":
experienceView.respondToRequest(message: message, payload: ["my": "payload"])
default:
return
}
}
override fun onMessage(experienceView: ExperienceView, message: Message) {
when (message.action){
"my_action" -> {
respondToRequest(message, mapOf("my" to "payload"))
}
else -> {}
}
}
onMessage(experience, (message) => {
if (message.action === 'my_action') {
respondToMessage(experience, message, { my: "payload" });
}
});
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:
iOS
Android
Javascript
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)
}
}
val experience = Launcher.default.getExperience(context = this, configuration = ExperienceConfiguration())
experience.sendRequest(action = "my_action", payload = mapOf("my" to "payload")){
it.onSuccess { payload ->
Log.d("Launcher", "Response payload: $payload")
}
it.onFailure { error ->
Log.e("Launcher", "Response payload: ${error.message}")
}
}
import {
embed,
getExperience,
onReady,
sendUserRequest,
} 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');
Last modified 1mo ago