SDK
This page explains the purpose of the SDK, what does it do and how to use the SDK to communicate between the user interface and the experience.
The SDK is one of the components that make up a virtual experience. It allows to:
- Easily embed the experience.
- Inform listeners on events that are happening within the experience.
- Send analytics events.
The SDK takes the virtual experience skeleton that you’ve built, attaches the user interface to it, and creates a full virtual experience.
Getting Started
To get started, you need to add two script tags to the index.html file of your application.
Embed the SDK
To embed the SDK, simply paste this line of code into your html file:
<script type="module" async src="https://sdk.emperiavr.com/Production/latest/emperia-sdk.min.js"></script>This will embed a small (~42KB) logic file into your application. Please note the type=module attribute, as that is required for the SDK to work. It is also best practice to use the async attribute, which does not block the main thread and improves the loading times of your application.
Add the initialisation logic
We also need to add a initialisation function, which allows you to pass parameters and customise the way the experience is going to be created:
<script>
window.emperiaAsyncInit = function () {
emperia.init({
id: "experience-root",
experience_url: "https://experience.emperiavr.com/example/experience/experience.html",
ui_url: "https://ui.emperiavr.com/Standard-UI/Production/1.1.0/static/",
attach_ui: true
});
};
</script>Below you will find all the available parameters that you can pass:
Parameter | Required? | Default Value | Description | Example |
id | Required | - | The id of the div element that the experience and the UI should be attached to. | experience-root |
experience_url | Required | - | The url of the experience. Ensure that the URL is pointing to experience.html | |
ui_url | Optional | Defines where the user interface code is stored. Must be a public link, and end with either /static or /static/ | ||
attach_ui | Optional | true | Should the user interface be attached, or should the attachment process be skipped? | true |
organisation_id | Optional | “” | What is your organisation ID? (Upcoming feature) | 256d2a04-14a3-4724-b536-89b193b862c1 |
locale | Optional | en | What is the locale of the experience? Used for analytics and to distinguish which locale the user is in | en_CA, en_GB, es_ES |
market | Optional | gb | What is the market of the experience? Used for analytics and to distinguish which market the user is in. Can be used for checking stock information | GB, US, Region-1, MX |
debug | Optional | false | Turn on debug information. The console will output debug information, such as events and warnings. | - |
analytics | Optional | true | Should analytics be enabled? (Upcoming feature) | true |
Final code
The final code should look something like this:
<!DOCTYPE html>
<html>
<head>
<!-- other tags -->
<script>
window.emperiaAsyncInit = function () {
emperia.init({
id: "experience-root",
experience_url: "https://experience.emperiavr.com/example/experience/experience.html",
ui_url: "https://ui.emperiavr.com/Standard-UI/Production/1.1.0/static/",
attach_ui: true
});
};
</script>
<script
type="module"
async
src="https://sdk.emperiavr.com/Production/latest/emperia-sdk.min.js"
></script>
</head>
<body>
<!-- other tags -->
<div id="experience-root" style="width:100%; height: 950px"></div>
</body>
</html>You should now see a full-screen experience inside your page. You can read more about embedding and other use cases in the Embedding the Experience page.
FAQ
The AR model allows you to visualize 3D models within the experience.
To create a new AR model, follow these steps:
- Right-click in the Content Browser.
- Go to Miscellaneous → Data Asset.
- Search for "ARModel" and select the corresponding type.
- Click "Create" to generate the asset.
- The AR Data Asset contains all necessary configurations for the AR Viewer.
Key | Description |
MeshURL | The URL or references for the 3D Mesh to display in the AR model. |
iFrame Model
The iFrame model allows you to embed websites or iframes within the experience.
To create a new iFrame model, follow these steps:
- Right-click in the Content Browser.
- Navigate to Miscellaneous → Data Asset.
- Search for "iFrame" and select the appropriate type.
- Click "Create" to generate the asset.
- The iFrame Data Asset contains all necessary configurations for the iFrame Viewer.
Key | Description |
URL | The URL or references for the web page to display in the iFrame model. |
Media Model
The Media model allows you to embed videos and images within the experience.
To create a new Media model, follow these steps:
- Right-click in the Content Browser.
- Navigate to Miscellaneous → Data Asset.
- Search for "Media" and select the appropriate type.
- Click "Create" to generate the asset.
- The Media Data Asset contains all necessary configurations for the Media Viewer.
Key | Description |
URLs | The URL or references for the Videos, Images to display in the Media model. |
Automated Action Model Creation Process
To streamline the process of creating action models, assets, and attaching them to interactables, we now support direct editing within the Details Panel of interactables placed in the scene.
Using the Action Type dropdown, you can specify the type of interactable action. Once selected, the relevant properties will appear below the dropdown for configuration. This automatically creates and attaches the corresponding action models and action type assets to the interactable, significantly reducing the number of steps required.
If you forget to save your action models or action type assets, you can simply clear the action models array on the interactable and make a slight modification to any Action Type property. This will automatically regenerate the entire asset.
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.