Web

Seamlessly integrate Monterosa's interactive Experiences into your website or application.

Overview

Seamlessly embed Monterosa's interactive Experiences into your website or app. We offer several methods, with the HTML & JavaScript approach being the most straightforward.

Embed using HTML & JavaScript

Import the SDK

Choose one of the methods below to import the SDK into your web page. This step is crucial to ensure the SDK is available within your HTML page for embedding the app.

Using a <script> tag in the <head> of your HTML:

This method should be used when you don't want or can not use a JavaScript bundler like Webpack or Babel, e.g. when the HTML page is generated by a CMS:

<!-- The rest of your head contents -->
<script src="https://sdk.monterosa.cloud/0.18.11/static-embed/index.js" defer="defer"></script>

Importing as an npm module in your JavaScript code:

This approach is ideal for complex applications that utilise modern JavaScript bundling tools, allowing developers to integrate the SDK into a single JavaScript file alongside their code. This integration offers a seamless inclusion of the SDK within the application's build process.

Embed Using Custom HTML Tag

import '@monterosa/sdk-widget';

Once you have imported our SDK, you can embed an app by using a custom HTML tag of type <monterosa-experience> anywhere in the <body> of your web page. Notice you must provide the host and Project ID of the app you want to embed. It will not function properly without those parameters. For example:

<monterosa-experience 
    host="<host>" 
    projectId="<project id>"
> 
</monterosa-experience>

For the app to be correctly embedded you'll need to serve your webpage via HTTP or HTTPS. Opening it as a file on your browser is currently not supported.

Customising the app (optional)

In order to configure your app, the following attributes of the Experience tag can be customised:

host, specifies the host of the app (mandatory)
project, specifies the project of the app (mandatory)
eventId, specifies the event that will be displayed when more than one is present in the app. If left unspecified, the app will display content from all events.
autoresizesHeight, when present, the app will autoresize its own height depending on the size needed by the app. This mirrors the behaviour of Manage the Experience's size.
hidesHeadersAndFooters , when present, the app will remove its own headers and footers to let you use your own instead.
persistentStorage , when present, enables persistence for shared storage
allow , sets a Permissions Policy for an <iframe>, controlling which browser features the embedded experience is permitted to use — such as access to the microphone, camera, battery status, and so on.
allowFullScreen , enables fullscreen mode support for the iframe, including compatibility with older browsers when set to true.
title, custom title for the iframe element. If provided, this title will be set on the iframe's title attribute in the generated embed code.

Additionally, the Experience tag can be styled as any other HTML element, allowing you to further customise its look and feel.

Project vs Event embedding

When specifying embedding parameters a projectId parameter is mandatory, but eventId is not. If eventId is set then embedded Experience will open event with this id. Otherwise it will load the list of events available in the given project and open the most recent event (one that started last).

Use case

Set event id?

Reasoning

Embed Experience on a front page

When users open the front page you want them to see the most recent event (match), so there is no hard link between the home page and specific event (match).

Embed Experience for a specific football match on a web page dedicated to this match.

yes

You want the same event (match) to be open on this page for the foreseeable future, irrespective of how many and which events are published subsequently.

Embed using NPM

Retrieve credentials from Studio

First, you'll have to configure SDK 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. To get access to Studio, check out getting an account.

Install the Monterosa SDK

All Interaction SDK packages are scoped as @monterosa. Execute the following commands to install the required packages:

npm install @monterosa/sdk-core
npm install @monterosa/sdk-launcher-kit
npm install @monterosa/sdk-interact-kit

Important: The JavaScript SDK can only be run in a browser environment and is not intended to be used with Node.js.

Configure for Project

Configure the SDK 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 { configure } from '@monterosa/sdk-core';

// E.g. this could be the root component of your ReactJS application
// or in the first file you import with a <link> HTML tag
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:

import { 
  getExperience,
  embed,
} from '@monterosa/sdk-launcher-kit';

const experience = getExperience();

await embed(experience, 'container-id');

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.

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

import { 
  getExperience,
  embed,
} from '@monterosa/sdk-launcher-kit';

const eventId = '<event id>';
const experience = getExperience({ 
  eventId,
  // Other ExperienceConfiguration values can be added, 
  // such as autoresizesHeight, hidesHeadersAndFooters, etc...
});

await embed(experience, 'container-id');

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.

import { configure } from '@monterosa/sdk-core';
import {
  getExperience,
  embed,
} from '@monterosa/sdk-launcher-kit';

const sdk1 = configure({
  host: '<host 1>',
  projectId: '<project 1>',
}, '<name 1>');

const sdk2 = configure({
  host: '<host 2>',
  projectId: '<project 2>',
}, '<name 2>');

const experience1 = getExperience(sdk1);
const experience2 = getExperience(sdk2);

await embed(experience1, '<container 1>');
await embed(experience2, '<container 2>');

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:

import { configure } from '@monterosa/sdk-core';
import { 
  setCredentials,
  getIdentify,
  getUserData,
} from '@monterosa/sdk-identify-kit';

const sdk1 = configure({ host: '<host 1>', projectId: '<project 1>' });
const sdk2 = configure({ host: '<host 2>', projectId: '<project 2>' });

const identify1 = getIdentify(sdk1);
const identify2 = getIdentify(sdk2);

await setCredentials(identify1, { token: '<token 1>' });
await setCredentials(identify2, { token: '<token 2>' });

const user1 = await getUserData(identify1);
const user2 = await getUserData(identify2);

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 Experience from the DOM element

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

unmount('container-id');

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

Once you do that, the garbage collector will take care of disposing of the memory used.

Last updated 14 days ago