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:

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:

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

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:

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

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:

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
}

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:

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

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:

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

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.

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