Embedding the Experience to a website
This page describes the different methods of embedding an experience to a website.
Getting Started
There are two ways to embed an experience into a website, using the SDK or using the <iframe> tag. This page will cover the implementation process for both of the approaches. Pros and cons of each approach are listed below:
Embedding through an iframe
- Can control iframe properties such as sandbox
- Will always have the same user interface attached
- Less control compared to the SDK
- Easier implementation
Embedding through the SDK
- Enables communication with parent website
- Allows to attach self-built user interfaces
- Gives developer more control
- Harder implementation
Requirements
In order to embed an experience, you first need to publish it. Head over to the dashboard, select an experience that you have built, and hit ‘Publish’.
Please note that only users who have the ‘admin’ or ‘owner’ role can publish experiences.
This will kick off a process that will start publishing the experience. Once that is done, it will generate a link that must be used when embedding the experience.
Embedding through the SDK
To keep things modular, we have built an SDK to:
- Facilitate the experience embedding
- Simplify the communication between the parent website and the experience
- Attach a custom user interface to the experience
The code below embeds the SDK and the experience in an async manner, so it would not block the main thread and other important processes.
1. Creating the parent container
Create the parent container where you want the experience to be placed. It will dynamically create all the HTML tags that are necessary to run the experience under this container.
<div id='experience-root'></div>The id of this component is important, as that’s what will be used by the SDK to find where the experience tags should be placed. It is possible to style the component however you want, to adapt to size and resolution requirements within the website.
2. Creating the initialisation function
To initialise the experience, create a function called emperiaAsyncInit and attach it to the window object. This function will get called once the SDK is ready.
<script>
window.emperiaAsyncInit = function () {
emperia.init({
id: "experience-root", //The id of the tag where the experience should be mounted
experience_url: <YOUR_PUBLISHED_EXPERIENCE_URL>, //The experience URL that was published. Please note to replace the end index.html with experience.html
ui_url: "https://ui.emperiavr.com/Standard-UI/Development/1.1.0/static/", //The static folder where the user interface should come from
attach_ui: true, //(optional) Should the SDK attach the user interface?
debug: false, //(optional) Do we want to see the debug mode?
organization_id: "", //(optional) Your organisation ID
});
};
</script>Breakdown of the parameters that are passed:
id: The id of the tag where the experience should be mounted.experience_url: The experience URL that was published. The published experience URL from the dashboard will point toindex.html, however while using the integration with the SDK, you must replaceindex.htmlwithexperience.html
You can read more about the complete list of parameters that the SDK accepts in the SDK page.
3. Adding the SDK
Finally, you need to add the SDK via the <script> tags:
<script type="module" async src="https://sdk.emperiavr.com/Production/latest/emperia-sdk.min.js"></script>This makes the SDK load in an async manner which does not block the main thread.
End result
The end result should look something like this:
<!DOCTYPE html>
<html>
<head>
<script>
window.emperiaAsyncInit = function () {
emperia.init({
id: "experience-root",
experience_url: "https://experience.emperiavr.com/example/experience/experience.html"
});
};
</script>
<script
type="module"
async
src="https://sdk.emperiavr.com/Production/latest/emperia-sdk.min.js"
></script>
</head>
<body>
<div id="experience-root" style="width:800px; height: 800px"></div>
</body>
</html>Embedding through an iframe
Embedding an experience through an iframe is a simple and straightforward process:
<iframe src="YOUR_PUBLISHED_EXPERIENCE_URL"></iframe>You can use this code below to check the implementation:
<!DOCTYPE html>
<html>
<head> </head>
<body>
<iframe
src="https://experience.emperiavr.com/example/experience/index.html"
style="width:800px; height: 800px"
sandbox="allow-scripts allow-same-origin allow-popups-to-escape-sandbox"
></iframe>
</body>
</html>Help & Support
If you have questions, suggestions, or feature requests, please join the Official Emperia Discord channel!
You can find support here through private support tickets or general conversation. You will also have the opportunity to showcase your work and chat with like-minded individuals across industries using Creator Tools, Unreal Engine, those creating immersive experiences, and more!
If you prefer, you can also reach out to us via email.