Onirix hosting: Embed SDK

Our SDKs work on two levels. On the first level you can use our cloud hosting, i.e. host all your experiences in our Onirix Studio, and through the online code editor, build the necessary logic and modifications to your experiences. For this we have created a high-level SDK, with which you can connect, listen to different events, and control a large number of actions and features of the AR scenes.

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.

site-player

Include the library

If you use ES modules, you can just import the library as:

import OnirixEmbedSDK from "https://unpkg.com/@onirix/embed-sdk@1.9.0/dist/ox-embed-sdk.esm.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@1.9.0/dist/ox-embed-sdk.umd.js"></script>

If you're using the online code editor, since there is not direct access to the head section, it is recommended to use the ESM import (first option above).

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 It will be activated when you lose sight of the image or surface and the scene is deleted.
OnirixEmbedSDK.Events.SCENE_DETECTED It will be activated when when a surface is detected.
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 and the element's center position(x, y, z) and intersection point.
OnirixEmbedSDK.Events.SCENE_CLICK Will be triggered when a scene is clicked. Returns an object with the scene coordinates where the user has touched. If an element has been touched, it returns the exact point where it was touched and the information of the touched element
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
OnirixEmbedSDK.Events.MAP_READY Will be triggered when map is loaded or when there is some error during the map loading process. In the latter case, the event params object will have an error field whose value is the error occurred.
OnirixEmbedSDK.Events.SCENE_LOCATION_CLICK Will be triggered when the user clicks on a location in the map, receiving its oid as argument.
OnirixEmbedSDK.Events.BACK_TO_MAP Will be triggered when the user leaves a scene and goes back to the map screen.
OnirixEmbedSDK.Events.ON_TOUCH_START Will be triggered immediately after the finger touches an element, receiving its oid as argument and the element's center position(x, y, z) and intersection point.
OnirixEmbedSDK.Events.ON_TOUCH_END Will be triggered immediately after the finger is lifted, receiving its oid as argument and the element's center position(x, y, z) and intersection point.
OnirixEmbedSDK.Events.ON_POSE Will be triggered every time the camera is updated and receives a param object with the fields 'position', 'quaternion', and 'euler'.
OnirixEmbedSDK.Events.ON_SCENE_TOUCH_START Will be triggered immediately after the finger touches the scene. Returns an object with the scene coordinates where the user has touched. If an element has been touched, it returns the exact point where it was touched and the information of the touched element
OnirixEmbedSDK.Events.ON_SCENE_TOUCH_END Will be triggered immediately after the finger is lifted. Returns an object with the scene coordinates where the user has touched. If an element has been touched, it returns the exact point where it was touched and the information of the touched element
OnirixEmbedSDK.Events.SESSION_ENDED It will be activated on WebXR's exit.
OnirixEmbedSDK.Events.LAZY_LOAD_END It will be called when an element is loaded lazily or created dynamically

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
stop(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
rotateTo(oid, x, y, z, time, loop) oid: element oid / name, x: Euler angles (in radians) on x axis, y: Euler angles (in radians) on y axis, z: Euler angles (in radians) on z axis, time: duration
rotateToQuaternion(oid, x, y, z, w, time, loop) oid: element oid / name, x: x quaternion's component, y: y quaternion's component, z: z quaternion's component, w: w quaternion's component, time: duration
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, autoStop, time) oid: element oid / name, name: animation name, loop: whether you want the animation loop or not (boolean), autoStop: If this parameter is true, the model will return to its original pose after finishing the animation (default false), time: This parameter allows you to specify the duration (in seconds) of the animation. If this parameter is not set, the original duration of the animation will be maintained.
stopAnimation(oid) oid: element oid / name
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
translateToElement(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
resetScenes() This action takes no parameters and its function is to return the web AR player to its initial state
setCameraRigTransform(matrix) Sets the camera transform matrix to the specified matrix.
setCameraRigPosition(x, y, z) Sets the camera position to the specified position.
setCameraRigRotation(x, y, z) Sets the camera rotation to the specified Euler angle.
setCameraRigQuaternion(x, y, z, w) Sets the camera rotation to the specified quaternion.
disableCameraControls() Disables the default camera controls (when using the 3D viewer).
loadElement(oid, params) oid: element oid / params: an object with any of the following keys: position, euler, scale, transition, time, and sound. For a more detailed description see the appropriate section of the lazy loading tutorial.
createElement(oid, params) oid: oid assigned to the element to create / params: an object with the following keys: assetOid, name, position, euler, scale, parentOid, transition, time, and sound. For a more detailed description see the appropriate section of the lazy loading tutorial.
setVariant(oid, variant) oid: oid or name of the element to modify / variant: name of the element's variant to apply
getAssetImage(oid, thumb) oid: Oid of the asset whose image we want to recover / thumb: true (default value) if we want to retrieve the asset thumbnail. False if we want to get the original image. For 3D elements it is only possible to retrieve the thumbnail.
loadSurfacePlaceholder(url) Url of the image we want to use as placeholder in the surface type experiences. More info here
setTransformControlsAllowlist(oids) Allows you to specify the elements that accept the transformation controls. Only the elements whose oid is passed as a parameter can be modified by the user with the usual transformation gestures (move, rotate and scale). More info here
setTransformControlsBlocklist(oids) Allows to specify the elements that do NOT accept the transformation controls. Only the elements whose oid is NOT passed as a parameter can be modified by the user with the usual transformation gestures (move, rotate and scale). More info here

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');

The EmbedSDK is a fundamental building block for many of our modules. Take a look at them to discover the full potential of Onirix experiences.

Results