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
Example configuration rotated by 30 degrees from default angle
The same product with different params and no rotation
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 of params
https://webview.intiaro.com/360/product/IntiaroWLShowcase/8763/custom_config_id/50fb9c591bdaf8ff6afe370b7185678b/resolution_x/1024/resolution_y/1024/angle/0/
High resolution picture example
https://webview.intiaro.com/360/product/IntiaroWLShowcase/8763/custom_config_id/50fb9c591bdaf8ff6afe370b7185678b/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.3.4/css/player.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.3.4/css/widgets.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.3.4/css/controller.css" rel="stylesheet"/>
...
</head>
<body>
<div class="intiaro360player" id="html-player-id" data-customer-id="IntiaroWLShowcase" data-product-id="8763">Content before 360 loader</div>
And at the bottom of the page:
<script src="https://libs.intiaro.com/360/configurator/1.9.3.4/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.3.4/css/player.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.3.4/css/widgets.css" rel="stylesheet"/>
<link href="https://libs.intiaro.com/360/configurator/1.9.3.4/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.
getFrameUrl(angle)¶
player.getFrameUrl(angle);
Returns url leading to the product image with a given angle. Only angles from 0 - 360 degrees are supported. Angle parameter must also be divisible by 10.
IMPORTANT: Please be aware that ange parameter defines degree from starting angle and not actual product rotation angle. This means if by default product is not facing the camera, angle = 0 will not represent a product facing the camera either. Please take a look at the example in the lower area of this page.
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"}
getChangedParams()¶
player.getChangedParams();
Returns a dictionary of product atributes together with their current values.
IMPORTANT: Dictionary contains only attributes that were manually changed by the user or direct setParam() function call and are available ( not restricted by current configuration for example: Function will not return welt fabric value if current product configuration has “no welts” option selected.).
Example of configuration object:
{"fabric":"gray", "size":"large", "finish": "oak"}
getChangedParamsObjects()¶
player.getChangedParamsObjects();
This function is similar to getChangedParams() however it returns a list of objects containing changed attributes and their current choices data.
IMPORTANT: List contains only objects with attributes and choices that were manually changed by the user or direct setParam() function call and are available ( not restricted by current configuration for example: Function will not return welt fabric value if current product configuration has “no welts” option selected.).
Example of configuration object:
[
{attribute: {…}, choice: {…}},
{attribute: {…}, choice: {…}}
]
Attribute and choice details:
attribue : {
name: "attribute label / name",
slug: "attribute slug",
// other optional keys may bepresent
}
choice: {
name: "attribute label / name",
slug: "attribute slug",
// other optional keys may bepresent
}
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. Function works in both “viewer” and “configurator” modes.
Example of use: (also please check “Saving nad using saved configuration” section for more details)
player.getConfigurationId( (customConfigurationId) => {
console.log(customConfigurationId);
});
getProductSummaryUrl()¶
player.getProductSummaryUrl( anglesArray, successCallback, failCallback) ;
Asynchronous function that returns string with url to product summary pdf containing product configuration and optional images.
angles - one dimentional array of integers defining angles from which prodocut pictures are going to be taken.
successCallback - function that is going to be called when url is ready.
failCallback - function called upon failure
Example of use:
configurator.getProductSummaryUrl([0, 30, 90], (url)=>{ console.log(url); }, ()=>{ console.log('error'); });
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="8763" 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>
Use cases live examples¶
Displaying configuration changes¶
Sometimes it is required to perform certain action when product configuration chages. In this particular example we’re going to manually create a configurator and then listen to configuration changes. Our callback function will then use getChangedParamsObjects() function to display list of attributes that were changed by the user together with their current choices. Here is how it’s done:
<!-- Configurator placeholder -->
<div id="DynamicListenerExample" data-customer-id="IntiaroWLShowcase" data-product-id="8763"> Configurator placeholder </div>
<!-- Configuration display placeholder -->
<h4>Changed configuration:</h4>
<div id="configDiv" style="min-height: 10px; background-color: #f0fafa; padding: 10px;"></div>
<script>
// 1) Create Intiaro configurator and store it's reference in variable.
var intiaroConfigurator = new IntiaroConfigurator("DynamicListenerExample");
// 2) Register "configurationChanged" listener callback.
intiaroConfigurator.registerListener("configurationChanged", (newConfiguration) => {
// 3) Use callback function to display changed product params.
let params = intiaroConfigurator.getChangedParamsObjects();
displayChangedParams(params);
});
// Supporting function to display changed product params.
function displayChangedParams(params) {
const configDiv = $("#configDiv");
configDiv.html("");
params.forEach(object => {
configDiv.append( `<p>${object.attribute.name}: ${object.choice.name}</em></p>` );
});
}
</script>
Saving nad using saved configuration¶
It is possible to use previously saved configuration id to initialize Intiaro player with custom configuration.
This functionality may be usefull in implementing features like “add to cart” or “add to favourites”.
To demonstrate that, we will do couple of things:
We will use first configurator to change product configuration.
We will then save product configuration with a button click.
And finally we will use saved configuration id to initialize another configurator instance with saved product configuration.
// First we create a configurator that is going to be used to change product configuration that wi will save later.
// This div has got "intiaroConfigurator" class attached to it so configurator is going to be created automatically.
<div class="intiaroConfigurator" id="first-configurator" data-customer-id="Lexington" data-product-id="8763">Content before 360 loader</div>
// We will also use below placeholder div to initialize our confogurator with save configuration id.
// We do not attach "intiaroConfigurator" to is. We will have to launch configurator manually with "new IntiaroConfigurator("second-configurator");".
<div id="second-configurator" data-customer-id="Lexington" data-product-id="8763">Second configurator will appear here.</div>
// We create simple button that will trigger save configuration script
<button id="save-current-configuration">SAVE CURRENT CONFIGURATION AND LAUNCH ANOTHER CONFIGURATOR</button>
// Finally we write our script
<script>
// Attach button click listener
document.getElementById("save-current-configuration").onclick = function(){
// get refference to first configurator
var firstConfigurator = getIntiaroPlayer("first-configurator");
// use getConfigurationId() function to save current configuration
firstConfigurator.getConfigurationId( (configId) => {
// store saved configuration id in a variable
var savedConfigurationId = configId;
// attach save configuration id to "data-configuration-id" of second configurator
// this will initialize second configurator with save configuration
var secondConfigurator = document.getElementById("second-configurator");
secondConfigurator.setAttribute("data-configuration-id", savedConfigurationId);
// launch second configurator
new IntiaroConfigurator("second-configurator");
});
}
</script>
Live example¶
Below you’ll find simple implementation of above code with some changes applied only to better visualize each step of the process.
The core of the algorithm remains the same.
First, please use below configurator to change product properties and then use SAVE CURRENT CONFIGURATION button underneath to get current configuration id.
Getting product picture¶
In this example we are going to display product picture based on currently selected product configuration.
<!-- Product configurator placehorder that will run automatically. -->
<div class="intiaroConfigurator" id="product-picture-demo" data-customer-id="Lexington" data-product-id="8763">Content before 360 loader</div>
<!-- Button that will trigger our getFrameUrl() function -->
<button id="get-picture">GET PRODUCT PICTURE</button>
<!-- Reulting picture placeholder -->
<h4>Product picture:</h4>
<img id="picture" style="min-height: 10px; background-color: #f0fafa; padding: 10px;"></div>
<script>
// Add button click listener
document.getElementById("get-picture").onclick = function(){
// get refference to configurator
var pictureConfigurator = getIntiaroPlayer("product-picture-demo");
// get picture url.
// We're calling getFrameUrl with angle parameter equal 30. This will produce url to picture of a product facing 30 degrees from default product rotation.
let ulr = pictureConfigurator.getFrameUrl(30);
// update image src with our url
let image = document.getElementById("picture");
image.src = ulr;
};
</script>
Product picture:
Generating product summary PDF¶
In this example we are going to request product summary pdf url and supply it to <a> tag to allow downloading by users.
<!-- Intiaro configurator placeholder. It contains "intiaroConfigurator" class which will make it launch atomatically -->
<div id="pdf-configurator"
class="intiaroConfigurator"
data-customer-id="IntiaroWLShowcase"
data-product-id="8763"
> Loading...</div>
<!-- Simple button to trigger pdf creation script -->
<button id="create-pdf" style="margin-top: 20px;">CREATE PDF</button>
<!-- PDF creation status and download div -->
<div id="pdf" style="margin-top: 20px;"></div>
<script>
// Helper function that will supply our pdf download div with correct pdf url.
// We are going to use it as success callback function
function displayURL(url) {
document.getElementById("pdf").innerHTML = `<a href=${url}> Download PDF </a>`;
}
// Helper function that will supply our pdf download div with a message in case pdf creation fails.
// We are going to use it as fail callback function
function displayError() {
document.getElementById("pdf").innerHTML = `Failed`;
}
// Attach click listener to create pdf button
document.getElementById("create-pdf").onclick = function(){
// Display information that pdf generation has started
document.getElementById("pdf").innerHTML = `Generating PDF...`;
// Get reference to Intiaro configurator
var configurator = getIntiaroPlayer("pdf-configurator");
// Define array with pdf images angles
const angles = [0,30,90];
// Use "getProductSummaryUrl" function supplied with agles array and callback functions.
configurator.getProductSummaryUrl(angles, displayURL, displayError);
};
</script>