Ctrlk
HomeCreator GuideIntegration GuideReference
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Custom Element

Embed Experiences using the JS SDK

Overview

If you are aiming for simplicity, you can embed your app using a declarative API. Here's how it works:

Step 1. 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. Also see Download & Initialise the SDK

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.4/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.

import '@monterosa/sdk-widget';

Step 2. Embed Using Custom HTML Tag

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.

Step 3. 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.

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

Last updated