Embedding Experiences
How to embed Experiences into your products using Monterosa / Interaction SDK
The SDK can be used to embed an app into your web or native app. This provides loading and resizing capabilities which save you integration effort and make for a smooth user experience.
Embedding the Experience using the SDK enables or greatly simplifies the following:
Dynamic resizing of the Experience container following content size changes — removes double scrolling and allows lazy loading when required.
Browser storage sharing with the parent — allows cross-domain embeds even in the strictest environments, such as Safari browser (applicable to web embeds only).
Programmatic analytics pass-through — allows seamless integration with your existing browser analytics solution in cross-domain embeds.
Programmatic control over Experience's headers and footers to suit the parent page context.
Preloading the Experience to allow instant display (available in native apps only).
Terminology
When an app is styled, setup and offered up to the audience, we refer to it as an Experience.
For the purposes of embedding integration, an Experience is a responsive web app which has been designed to behave as if native to the environment it will live in.
We therefore refer to an Experience as an app in this guide.
You can load a ready-made apps from the The Store or those that have been developed specifically for you and made available in the platform.
Click here to see a working example of an app embedded using the SDK.
Choosing Static or Dynamic Embedding
You'll need to decide which integration method you want to use.
We recommend starting with static embedding:
Embed an Experience
Fix the Experience on a specific Event
Autoresize height
Hide the header and footer of the Experience
If you need any further functionality, such as sharing data or session with the Experience or passing parameters to it, you'll need to use dynamic embedding approach.
First get your app metadata from Studio
In order to embed an Experience, you'll need its Project ID and Static host. This information can be retrieved from Studio by navigating to the project, then accessing the API tab within the Settings section.
There you'll find a convenient way to copy the data you need:
Handling cross-domain issues
"Cross-domain" refers to a scenario when the parent page (your website) and the embedded page (Monterosa Experience) sit on different domains. In this scenario, modern web browsers restrict the embedded page from using persistent data storage, in order to protect end-users from malicious tracking. At Monterosa, we support the industry's move towards enhanced privacy, but expectedly, it creates technical hurdles for fair players too. E.g. the strictest browsers, such as Safari, wipe all the data stored by the embedded pages as soon as the user closes the browser window, which means the next time they open it, Monterosa Experience does not have any "memory" of the user's past interactions, which leads to an inconsistent UX.
Additionally, most of the modern browser analytics systems (such as Google Analytics) do not allow the embedded Experience to send browser analytics to the server in cross-domain scenarios. This usually may be rectified by custom code, whereas the SDK offers a programmatic API that solves this problem out-of-the-box.
There are three ways Monterosa Experiences work around this limitation:
Using the SDK to embed the Experience allows it to store the data within the parent page, where it is safe from deletion.
Requiring users to log in before using the Experience allows it to fetch user data from the server on launch, even when no data is stored locally on the device.
Monterosa Experience may be configured to appear on exactly the same domain as the parent page (please note that subdomains do not solve the problem). This way browser treats the embedded Experience as "trusted" and does not restrict data storage.
Last updated