Intiaro 360 Configurator API documentation¶
Introduction¶
There are two main ways that the Intiaro WebView interface can be used.
Image API - this API will retrieve a single static image based on the provided parameters.
WebView Player - this API allows you to use JavaScript to set player configuration.
Image API¶
Image API equips you to use Intiaro API to generate images with a simple GET request. URLs to the image can be used as main product images, thumbnails in other platforms as social media, e-commerce, landing pages, emails, etc.
Usage:¶
https://webview.intiaro.com/api/v09/360/<product_id>/?<list_of_query_parameters>
Required arguments:
product_id - is a unique ID of a product. All variations with the same product_id are considered a single product
Supported query parameters:
params - list of attribute_id:value_id pairs, defining product features, see examples below:
params=size:small,fabric:gray,finish:oak
means:
attribute_id is size and value_id is small
attribute_id is fabric and value_id is gray
attribute_id is finish and value_id is oak
Each attribute_id may be used in a URL only once, but a value_id may be shared between attributes. For instance, seat_cushion attribute might have “gray” as a value, and back_cushion attribute might have the same value.
angle - number of degrees (0-360) product will be rotated horizontally. 0 will result in a front-view product image.
width [optional] - width of the image in pixels. Height is calculated automatically with the preserved aspect ratio.
silent_fail [optional] - silent_fail is set to true. When the unsupported configuration is requested, API will return a fallback image (ie. “Visualisation is not supported”) or will raise a 404 HTTP response.
dummy - used for debugging purposes. If set to true, the player will generate an image with the requested product ID and parameters. No actual data is needed.
See examples below:¶
Dummy mode example
https://webview.intiaro.com/api/v09/360/3504/?params=size:small,fabric:gray,finish:oak&angle=30&width=1024&height=auto&sku=123&quality=100&silent_fail=false&dummy=true
Example configuration rotated by 30 degrees from default angle
https://webview.intiaro.com/api/v09/360/3504/?params=black-glides_s8fa4:glides-black_lq3fm,prevueuk_pres_body_fabric:prevueuk_body_fabric_a181,prevueuk_pres_pillow_fabric:prevueuk_pillow_fabric_c453&angle=30&width=1024&height=auto
The same product with different params and no rotation
https://webview.intiaro.com/api/v09/360/3504/?params=black-glides_s8fa4:glides-black_lq3fm,prevueuk_pres_body_fabric:prevueuk_body_fabric_l846,prevueuk_pres_pillow_fabric:prevueuk_pillow_fabric_c451&angle=0&width=1024&height=auto
Image API and advanced product configuration¶
Sometimes product configuration is just too complex to pass all params through the url. It is however possible to overcome this limitation by using it’s custom configuration id instead of complete list of parameters. In order to get current configuration id, you will first need to get player instance using getIntiaroPlayer() function. Then you will be able to get current configuration id using getConfigurationId().
Please visit WebView Player API section of this page to learn more about how to get configuration id.
Usage:¶
If you already know configuration id you can use blow url to produce product image.
https://webview.intiaro.com/360/product/<customer_id>/<product_id>/custom_config_id/<custom_configuration_id>/resolution_x/<width>/resolution_y/<height>/angle/<rotation>/
Required arguments:
customer_id - is your unique ID obtained from Intiaro
product_id - is a unique ID of a product. All variations with the same product_id are considered a single product
custom_configuration_id - configuration id retrived by getConfigurationId() function.
width / height - resulting pircure width and height
rotation - product rotation in degrees (supported angles 0-360, step = 10)
Supported query parameters:
attachment - if set to true, forces browser to download image as a file instead of displaying it in browser window.
See examples below:¶
Example configuration with configuration id instead of list o params
https://webview.intiaro.com/360/product/IntiaroWLShowcase/3504/custom_config_id/f54a1c3a80d86bd138103a51e5e86b50/resolution_x/1024/resolution_y/1024/angle/0/
High resolution picture example
https://webview.intiaro.com/360/product/IntiaroWLShowcase/3504/custom_config_id/f54a1c3a80d86bd138103a51e5e86b50/resolution_x/3072/resolution_y/3072/angle/0/
WebView Player API¶
WebView Player API is a JavaScript interface that allows you to control the player. Similar to image JavaScript slider libraries.
Intiaro 360 Player requires CSS in the head section and a JavaScript file placed at the end of the body tag in an HTML document. The JavaScript file will search for div with class “intiaro360player” and replace each of them with the player instance. For best user experience on mobile devices, it is also recommended that you add a viewport meta tag with particular size and scale settings. Please find example of player placeholder below:
<head>
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1">
<link href="https://libs.intiaro.com/360/configurator/1.9.0.10/css/player.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.0.10/css/widgets.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.0.10/css/controller.css" rel="stylesheet"/>
...
</head>
<body>
<div class="intiaro360player" id="html-player-id" data-customer-id="IntiaroWLShowcase" data-product-id="3504">Content before 360 loader</div>
And at the bottom of the page:
<script src="https://libs.intiaro.com/360/configurator/1.9.0.10/js/360.min.js" type="text/javascript"></script>
The player will take the available width and automatically adjust its height. To set its dimensions, it should be placed inside a div with proper size styles. Please note that minimum player width should not be lower than 300px. Take a look at the example below:
<style>
.widthLimit{
width: 95vw;
min-width: 300px;
max-width: 800px;
margin-left: auto;
margin-right: auto;
}
</style>
<div class = "widthLimit">
<div class="intiaro360player"
id="html-player-id"
data-customer-id="example"
data-product-id="1234"
data-params="arg1:val1,arg2:val2,arg3:val3"
data-max-width="800"
data-max-height="800"
>Content before 360 loaded</div>
</div>
Div with “intiaro360player” will be replaced by player instance. The arguments state as follows:
data-customer-id - your ID obtained from Intiaro.
data-product-id - product ID obtained from Intiaro.
data-params [depending on product] - comma-separated key: value strings of product features.
data-configuration-id - custom configuration id to be displayed (obtained with getConfigurationId() function explained later )
data-resolution-x [depending on product] - width of a zoomed image. Note that currently only square resolutions of 3072 or 4096 are supported.
data-resolution-y [depending on product] - height of zoomed image.
data-max-width [optional] - max-width that player will obtain in fullscreen 360 view mode. In normal window mode, this will be 100% responsive. Note that different proportions of the player might be limited. By default, only squares are supported.
data-max-height [optional] - max height that player will obtain in fullscreen 360 view mode. In normal mode, the image will be 100% responsive.
data-menu-url [optional] - a link to menu definition in JSON format. If provided, the player will enter configurator mode and will be displayed with an additional user interface allowing you to change the defined choices. In this mode, the player requires that additional style sheets be provided. It is responsible for the styling player menu.
data-menu-fixed [optional] - a flag indicating that the configuration menu should be fixed. In this mode, all menu sections are opened and cannot be collapsed.
<head>
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1">
<link href="https://libs.intiaro.com/360/configurator/1.9.0.10/css/player.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.0.10/css/widgets.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.0.10/css/controller.css" rel="stylesheet"/>
...
</head>
Menu JSON file format:
The example above creates a window presented below:
For products that support the built-in menu, it is possible to create an Intiaro configurator instance instead of a regular Intiaro player. To do that, simply change the div class name from “intiaro360player” to “intiaroConfigurator.” The Intiaro player will be instantiated in configurator mode with an additional user interface attached to it.
getIntiaroPlayer()¶
Player instances can be retrieved by the getIntiaroPlayer method. See example below:
var player = getIntiaroPlayer("html-player-id");
getIntiaroController()¶
Similarly, it is possible to retrieve the controller component with the getIntiaroController method. See example below:
var controller = getIntiaroController("html-player-id");
With the player instance, you can use the methods below:
setAngle()¶
player.setAngle(angle, callback);
If it returns null, set the angle of the player - Euler angles - clockwise. Due to the cache mechanism, only multiples of ten are available. A callback is optional.
getAngle()¶
player.getAngle();
Returns an integer with the current angle of the player (Euler angles) rotated clockwise.
setParams()¶
player.setParams(attributes, silentFail, callback);
Set attribute values and display the resulting render in the player. Attributes object is a dictionary with attribute_id as a key and choice_id as a value. If the second (optional, true by default) argument is false, method setAttributes will raise an exception if given attributes are not supported (i.e. visualization is not available). The optional callback method will be called once the first frame of the new product configuration is loaded.
Example of attribute object:
{"fabric":"gray", "size":"large", "finish": "oak"}
getParams()¶
player.getParams();
Returns current configuration of the player instance.
Example of configuration object:
{"fabric":"gray", "size":"large", "finish": "oak"}
getConfigurationId()¶
player.getConfigurationId( callback );
Asynchronous function that returns string with id of current configuration. It can be used to initialize configurator with particular product configuration or to feed pricing or add to cart api for example.
Example of use: (also please check “Using saved configuration” section for more details)
player.getConfigurationId( (customConfigurationId) => {
console.log(customConfigurationId);
});
registerListener()¶
player.registerListener(eventName, callback);
controller.registerListener(eventName, callback);
Allows registering a listener on a particular event of the player or controller instance. Currently, only the “configurationChanged” event is supported. The current configuration is saved and passed as a parameter when the callback function is initiated.
Example of use:
var customCallback = function(config){ console.log(JSON.stringify(config)); };
getIntiaroPlayer("p1").registerListener("configurationChanged", customCallback );
Result:
{"fabric":"gray", "size":"large", "finish": "oak"}
Dynamic content¶
Intiaro Player can also be instantiated dynamically by calling new IntiaroPlayer(“<id>”) or new IntiaroPlayer(“#<id>”) where <id> stands for the ID of the element where the player should be instantiated.
Please take a look at the example below:
<div id="htmlplayer3" data-customer-id="IntiaroWLShowcase" data-product-id="3504" data-max-width="1024" data-max-height="1024">Press the add button to create a player</div>
<button id="addPlayer">Create the player instance</button>
<script>
document.getElementById("addPlayer").onclick = function(){
var newIntiaroPlayer = new IntiaroPlayer("htmlplayer3"); // or new IntiaroPlayer("#htmlplayer3");
}
</script>
Using saved configuration¶
It is possible to use previously saved configuration id to initialize Intiaro player with custom configuration. To do that, you’ll need to assign it adequate data attribute.
<div id="Intiaro-configurator" class="intiaroConfigurator"
data-customer-id="IntiaroWLShowcase"
data-product-id="3504"
data-configuration-id="savedConfigurationID"
> Loading... </div>
</div>
Live example¶
First, please use below configurator to change product properties and then use SAVE CURRENT CONFIGURATION button underneath to get current configuration id.