Communicate with embedded apps

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:

iOS

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

Android

class MyActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        val config = ExperienceConfiguration(
            parameters = hashMapOf("custom_key" to "custom_value")
        )
        
        val experienceView = Launcher.default.getExperience(this, config))
    }
}

Javascript

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, 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:

iOS

class MyClass: ExperienceViewDelegate {
    
    func didBecomeReady(from controller: ExperienceView) {
        // experience is ready to accept incoming messages
    }
    
    // Other methods of the delegate
}

Android

class MyActivity : AppCompatActivity(), ExperienceViewListener {

    override fun onCreate(savedInstanceState: Bundle?) {
        ....
        val experienceView = Launcher.default.getExperience(this, config)
        experienceView.listener = this
    }

    override fun onReady(experienceView: ExperienceView) {
        // experience is ready to accept incoming messages
    }
}

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');

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:

iOS

let experience = Launcher.getExperience()
let encodable = ["my": "payload]
experience.sendMessage(action: "my_action", payload: ["my": "payload"])

Android

....
val experience = Launcher.default.getExperience(this, config)
experience.sendMessage("my_action", mapOf("my" to "payload"))

Javascript

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');

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:

iOS

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
}

Android

class MyClass: ExperienceViewListener {
   fun embedExperience() : ExperienceView {
        ....
        val experience = Launcher.default.getExperience(this, config)
        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 -> {}
        }
    }
}

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
  }
});

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:

iOS

func didReceiveMessage(experienceView: ExperienceView, message: MessageData) {
    switch message.action {
    case "my_action":
        experienceView.respondToRequest(message: message, payload: ["my": "payload"])
    default:
        return
    }
}

Android

override fun onMessage(experienceView: ExperienceView, message: Message) {
    when (message.action){
        "my_action" -> {
            respondToRequest(message, mapOf("my" to "payload"))
        }
        else -> {}
    }
}

Javascript

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

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:

iOS

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)
    }
}

Android

val experience = Launcher.default.getExperience(this, config)

experience.sendRequest("my_action", mapOf("my" to "payload")){    
    it.onSuccess { payload ->        
        Log.d("Launcher", "Response payload: $payload")
    }    
    it.onFailure { error ->        
        Log.e("Launcher", "Response payload: ${error.message}")
    }
}

Javascript

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');

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:

iOS

By adjusting the logging level, you can choose to display only essential information while silencing less critical or verbose log messages.

import MonterosaSDKCommon

let logLevel: Log.Level = .debug
Log.setLogLevel(level: logLevel)

The available log levels are:

case silent
case error
case warning
case info
case debug
case verbose

Android

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.

Javascript

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

enableLogging();