DocsCreator GuideIntegration Guide

Dynamic Embedding

Use the flexible dynamic embedding to take further control

To use the dynamic embedding method follow this guide and the various operating system-specific behaviours.

Get the SDK

First, you'll need to configure your development environment to gain access to the SDK. You'll need the credentials included in your "Welcome pack" to achieve this. See also Download & Initialise the SDK

If you're an existing customer and can't find your Welcome Pack, please raise a ticket via [email protected] or speak to your Account Manager.

If you use Swift Package Manager, add the following GIT repository URL as a new package dependency in Xcode:

https://<package-username>:<package-token>@gitlab.com/monterosa-sdk/ios.git

Finally, select MonterosaSDKCore and MonterosaSDKLauncherKit from the list of available Package Products.

If you use CocoaPods, add the following to your app target in your Podfile

target 'MyApp' do
  username = "<YOUR USERNAME>"
  token = "<YOUR TOKEN>"
  version = "0.16.12"

  url = "https://#{username}:#{token}@gitlab.com/monterosa-sdk/ios.git"

  pod 'MonterosaSDKCommon', :git => url, :tag => version
  pod 'MonterosaSDKConnectKit', :git => url, :tag => version
  pod 'MonterosaSDKCore', :git => url, :tag => version
  pod 'MonterosaSDKLauncherKit', :git => url, :tag => version
  pod 'MonterosaSDKIdentifyKit', :git => url, :tag => version
end

Once you have access to the SDK, you'll have to configure it during the startup of your application, so it is able to access your project. For that, you'll need a static host and a project id, which can be retrieved in Studio.

import UIKit
import MonterosaSDKCore

@UIApplicationMain
class AppDelegate: UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        ...
        Core.configure(host: "<static host>", projectId: "<project id>")
        ...
    }
}

Launch an App/Experience

All Projects are associated with an App, also known as an Experience.

You can check Monterosa / Interaction Cloud core concepts and read about platform terminology if you need more information.

You will need to obtain an Experience Object — a programmatic interface to the Monterosa / Interaction Cloud Experience you're launching — and then place it in your views:

let experience = Launcher.getExperience()
<yourView>.addSubview(experience)

// You need to ensure you layout the experience correctly
// For instance, to display on full screen using autolayout,
// you'll need something like this:
experience.translatesAutoresizingMaskIntoConstraints = false
experience.topAnchor.constraint(equalTo: <yourView>.safeAreaLayoutGuide.topAnchor, constant: 0).isActive = true
experience.bottomAnchor.constraint(equalTo: <yourView>.bottomAnchor, constant: 0).isActive = true
experience.leadingAnchor.constraint(equalTo: <yourView>.leadingAnchor, constant: 0).isActive = true
experience.trailingAnchor.constraint(equalTo: <yourView>.trailingAnchor, constant: 0).isActive = true

Then, simply place the Experience Object you've just created on the screen and it will initiate automatically.

In the Javascript SDK, the app will start loading as soon as embedded.

On Android and iOS, it will start loading as soon as created. Additionally, iOS's and Android's ExperienceViews can notify you when the loading of the page has completed, allowing you to add a loading state if you chose to.

class MyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        ...
        let experience = Launcher.getExperience()
        experience.delegate = self
        ...
        view.addSubview(experience)
        
        // You need to ensure the experience is laid out however you see fit.
        // For instance, could use autolayout constraints, or setting 
        // its frame
    }
}

extension MyViewController: ExperienceViewDelegate {

    func didStartLoading(experienceView: ExperienceView) {
        displayLoadingUI()
    }

    func didEndLoading(experienceView: ExperienceView) {
        hideLoadingUI()
    }

    func didFailLoading(experienceView: ExperienceView, error: Error) {
        hideLoadingUI()
        displayErrorUI(with: error)
    }
    
    func didBecomeReady(experienceView: ExperienceView) {
        // Called when Experience is ready to receive messages.
    }
    
    func didReceiveMessage(experienceView: ExperienceView, message: MessageData) {
        // Receive messages sent by Experience.
    }
    
    // [...]
    // Implementation of the rest of ExperienceViewDelegate 
    // [...]
}

Additionally you can launch a specific Event within your app using the following snippet. 

let eventId = "<event id>"
let config = ExperienceConfiguration(eventId: eventId)
let experience = Launcher.getExperience(config: config)
<yourView>.addSubview(experience)

// You need to ensure the experience is laid out however you see fit.
// For instance, could use autolayout constraints, or setting 
// its frame

How to launch multiple Apps/Experiences

In some cases you may find it useful to embed multiple apps within your application. For example, if you have multiple games or shows you're covering and want each to have a vote associated with them, each set up to look differently in their own Project.

The SDK supports multiple apps by allowing you to configure multiple SDK instances as long as you provide a unique name to identify them.

Core.configure(
    host: "<host 1>", 
    projectId: "<project 1>", 
    name: "<name 1>"
)
let sdk1 = Core.core(by: "<name 1>")
let launcher1 = Launcher()
sdk1!.register(kit: launcher1)

let experience1 = launcher1.getExperience()

Core.configure(
    host: "<host 2>", 
    projectId: "<project 2>", 
    name: "<name 2>"
)
let sdk2 = Core.core(by: "<name 2>")
let launcher2 = Launcher()
sdk2!.register(kit: launcher2)

let experience2 = launcher2.getExperience()

let sdk2 = Core.configure(
    host: "<host 2>", 
    projectId: "<project id 2>", 
    name: "<name 2>"
)

<yourView>.addSubview(experience1)
<yourView>.addSubview(experience2)

// You need to ensure the experiences are laid out however you see fit.
// For instance, could use autolayout constraints, or setting 
// their frame

Note that when launching multiple experiences, it is necessary to configure Identify Kit for each individual experience.

See the section here

How to configure Identify Kit for multiple apps

If you're embedding more than one app you'll need to set the credentials of each using the snippit below: 

class MyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        ...
        
        // You need to ensure you have followed the Configure Multiple
        // Experiences step
        
        experience1.identify.setCredentials(credentials: UserCredentials(token: "token1")
        experience2.identify.setCredentials(credentials: UserCredentials(token: "token2")

        experience1.identify.add(delegate: self)
        experience2.identify.add(delegate: self)
        
        ...
    }
}

extension MyViewController: IdentifyKitDelegate {

    // [...]
    // Implementation of IdentifyKitDelegate
    // [...]
}

Disposing of an Experience

Once the user is done with an Experience, you'll want to make sure that the resources used by the SDK are freed up. For instance, when they swap from one to another, or if they navigate back in your navigation hierarchy,

To do so, take the following steps:

  • Remove the ExperienceView from the parent view or DOM element

  • Ensure you don't have any reference to it in memory

Once you do that, the garbage collector or reference counter of your language of choice will take care of disposing of the memory used.

Last updated

Was this helpful?