Embed SDK
Onirix Embed SDK allows you to listen to events and control the scene when embedding experiences in a custom domain or from the online code editor.
Include the library
If you use ESM modules, you can just import the library as:
import OnirixEmbedSDK from "https://unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.umd.js";If not, use the UMD library instead by adding a new script tag inside your page's head section:
<script src="https://unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.umd.js"></script>If you're using the online code editor, you'll have to create this script dynamically from the Javascript block in order to add it to the head section:
const script = document.createElement('script');
script.src = "https://unpkg.com/@onirix/embed-sdk@latest/dist/ox-embed-sdk.umd.js";
script.onload = async () => {
// You're now ready to instantiate and use the embed SDK.
};
document.head.appendChild(script);If you're using a JavaScript framework or a bundler like Webpack, it is recommended to use the NPM package instead.
Instantiate and connect
Create a new instance of the SDK by passing the iframe HTML element in the constructor and call the connect method:
const iframeElement = document.getElementById("your_iframe_id_here");
const embedSDK = new OnirixEmbedSDK(iframeElement);
embedSDK.connect();If there is not any iframe (when using the code editor), you can just instantiate the SDK with arguments:
const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();Connect method returns a promise. If you want to ensure there is not any error and connection was done successfully, you can add an await keyword before or use the old promise syntax with then and catch functions.
Listen to Events
You can listen to the following events for the experience:
| Event | Description |
|---|---|
| OnirixEmbedSDK.Events.READY | Will be triggered when all permissions are accepted and the camera becomes visible |
| OnirixEmbedSDK.Events.SCENE_LOAD_START | Will be triggered when the scene starts loading. This is, when an image is detected or you select a surface to place the scene |
| OnirixEmbedSDK.Events.SCENE_LOAD_END | Will be triggered when the scene finishes loading, and thus, the assets are visible |
| OnirixEmbedSDK.Events.SCENE_LOST | Will be triggered when you lose sight of the image and the scene is removed |
| OnirixEmbedSDK.Events.SCENE_RADIUS_ENTER | Will be triggered when the user enters the activation radius of a geolocated scene |
| OnirixEmbedSDK.Events.SCENE_RADIUS_EXIT | Will be triggered when the user exits the activation radius of a geolocated scene |
| OnirixEmbedSDK.Events.ELEMENT_CLICK | Will be triggered when an element is clicked, receiving its oid as argument |
| OnirixEmbedSDK.Events.OPEN_MARKERS_PANEL | Will be triggered when image markers panel is opened |
| OnirixEmbedSDK.Events.CLOSE_MARKERS_PANEL | Will be triggered when image markers panel is closed |
In order to listen to any of those events, you just need to use the subscribe method:
embedSDK.subscribe(OnirixEmbedSDK.Events.ELEMENT_CLICK, (params) => {
console.log("Element with oid: " + params.oid + " was clicked!");
});
SCENE_LOAD and ELEMENT_CLICK events return params with useful information about the scene and clicked element respectively.
susbcribe method returns a subscription id you can use later to unsubscribe by calling the unsubscribe method.
Control the scene with Actions
Actions are useful to create custom behaviour and be able to trigger changes in the scene from HTML elements.
These are the actions you can run with Onirix Embed SDK:
| Action | Params |
|---|---|
| enable(oid, transition, time) | oid: element oid / name, transition: NONE = 0 (default), FADE = 1, GROW = 2, GROW_X = 3, GROW_Y = 4, GROW_Z = 5, BOUNCE = 6, time: transition time in seconds (default = 1) |
| disable(oid, transition, time) | oid: element oid / name, transition: NONE = 0 (default), FADE = 1, GROW = 2, GROW_X = 3, GROW_Y = 4, GROW_Z = 5, BOUNCE = 6, time: transition time in seconds (default = 1) |
| toggle(oid, transition, time) | oid: element oid / name, transition: NONE = 0 (default), FADE = 1, GROW = 2, GROW_X = 3, GROW_Y = 4, GROW_Z = 5, BOUNCE = 6, time: transition time in seconds (default = 1) |
| enableAll() | - |
| disableAll() | - |
| play(oid) | oid: element oid / name |
| pause(oid) | oid: element oid / name |
| translate(oid, x, y, z, time, loop) | oid: element oid / name, x: amount on x axis, y: amount on y axis, z: amount on z axis: time: duration, loop: repeat indefinitely |
| rotate(oid, x, y, z, time, loop) | oid: element oid / name, x: amount on x axis, y: amount on y axis, z: amount on z axis: time: duration, loop: repeat indefinitely |
| scale(oid, x, y, z, time, loop) | oid: element oid / name, x: amount on x axis, y: amount on y axis, z: amount on z axis: time: duration, loop: repeat indefinitely |
| playAnimation(oid, name, loop) | oid: element oid / name, name: animation name, loop: whether you want the animation loop or not (boolean) |
| stopAnimation(oid) | oid: element oid / name |
| reset | resets the scene |
| setLabelText(oid, text) | oid: element oid / name, text: new label text |
| translateToPosition(oid, x, y, z, time, lookAt) | oid: oid of the element to be moved / x,y,z: coordinates where the object will be moved / time: movement duration / lookAt: true if the element must look in the direction of the movement |
| translateToPosition(oid, targetOid, time, lookAt) | oid: oid of the element to be moved / targetOid: oid of the target element / time: movement duration / lookAt: true if the element must look in the direction of the movement |
If you use element names instead of oids for action params, a new action will launch for each element with that name.
In order to run an action, just call its method with required parameters:
embedSDK.disable('your_element_oid');