AR Player Configuration
Player Introduction
The Player is an HTML presentation method we designed to allow you to embed your spinnable and animated AR mockups into your web pages. It is essentially a javascript engine that displays the rendered views of AR mockups or your own custom images in one three preconfigured modes:
- Interactive: users can drag their mouse around to spin the mockups and view it from all angles
- Auto Spin: the mockup will continuously spin on an axis
- Slideshow: include custom images and links to your playlist
How much does it cost?
As long as the Player JS [ 1 ] source code itself is not modified, you are free to deploy the player as you see fit. Furthermore, there are no restrictions in sharing your HTML pages with our embedded Player. For example, emailing a client your AR Mockup with an HTML attachment which has the Player within it is allowed.
Where can I get the Player?
Everything you need to install and run the Player on your web page can be found below. The latest Player JS [ 1 ] source can be copied at any time by scrolling down to the section [ 1 ] Player JS and clicking the provided [ Copy to clipboard ] link.
How do I get started?
Although the Player is easy to install and configure, it does require some working knowledge of HTML and CSS – if you can create web pages with HTML and style them with CSS, then you are capable of embedding our Player.
You do not need to know javascript as you are not required to edit any code found in Player JS [ 1 ]. However, you will need to modify a few variables within the Player.init [ 2 ] for your embedded player to behave as expected. These variables are simply paths to your images, file names and player dimensions.
Additionally, if you’re embedding the Player into your portal, you will require write access to the portal’s source HTML files. If you’re working on a simple single page html file, a basic text editor will be sufficient.
In the next section, we will provide an overview of the 4 components required to embed the Player on your web page. Throughout this document you will find code examples and downloadable contextual HTML demos to fast track your understanding of the Player configuration.
How to embed the Player
The Player is composed of four parts working together to make your mockup spinnable: the Player JS [ 1 ] source, Player.init() [ 2 ] configuration parameters, CSS style [ 3 ] and HTML element [ 4 ].
The Player JS [ 1 ] code is responsible for loading and managing the rendered mockup images that are displayed in an HTML element [ 4 ] on your web page. You may place this element anywhere within the HTML body of your web page and define its size and layout characteristics via your page CSS style [ 3 ].
Finally, what the player displays in your HTML element [ 4 ], and how it works, is dictated by the parameters passed to it from Player.init() [ 2 ].
<!DOCTYPE html>
<html>
<head>
<title>Title of your web page</title>
[1] Player JS
[2] Player.init()
[3] CSS Style
</head>
<body>
[4] HTML Element
</body>
</html>
[ 1 ] Player JS ( javascript )
The Player JS code must be included once on a page, either via a script tag or through a linked js source file. The Player JS is minified javascript code which plays your AR mockup within an HTML element [ 4 ] using the parameters passed to it through the Player.init(‘JSON object…’).
The Player JS always announces the Player.version=”1.x.x” at the beginning of the script. The information on the page you are currently reading will always be specific to the accounced version.
To implement, or upgrade, to the latest Player JS version, simply cut and paste the following Player JS source into your page. For the latest Player features and updates, please revisit this page periodically.
This source code is meant to be used as is and should not be modified.
<script type="text/javascript"> Player={};Player.version="1.0.5";Player.defaults={id:"player",width:520,height:392,rho:[],theta:[]};Player.clear=function(a){if(Player[a].o==undefined){return}Player[a].o.onmousemove=undefined;Player[a].o.onmouseup=undefined;Player[a].o.onmouseout=undefined};Player.applyMask=function(b,a){return b.mask==undefined||b.mask==""?a:b.mask.replace("{id}",a)};Player.initimg=function(e,c,b,d){var a=e.theta[b]+"_"+e.rho[c];return Player._initimg(e,Player.applyMask(e,a),d)};Player._initimg=function(e,b,d){var c=e.base==undefined||e.base==""?"./":e.base+"/";console.log("img.src: "+c+b);var a=new Image();a.src=c+b;if(d!=undefined){a.onload=d}var f=document.createElement("div");f.style.backgroundImage=undefined;f.classList.add("hidden");f.appendChild(a);return a};Player.init=function(m){console.log("Player.js by HaptUX Inc., version "+Player.version);console.log("start: "+m.id);var c=m.id;if(c==undefined){console.log("id: undefined...");return}try{if(Player[c]==undefined){Player[c]={}}var d=Player[c];var p=Player.clone(Player._css);for(var j in Player.defaults){if(d[j]==undefined){d[j]=Player.defaults[j]}}if(m!=undefined){for(var q in m){d[q]=m[q]}}d.o=document.getElementById(d.id);d.start=function(a){d.o.classList.remove("pointer");d.o.onmousedown=undefined;delete d.click_to_start;Player.init({id:d.id})};d.img=[];if(d.slide_show!=undefined||d.auto!=undefined){d.idx=-1;var g;if(d.slide_show){for(var f in d.slide_show){var h=Player._initimg(d,(d.slide_show[f]["id"]?Player.applyMask(d,d.slide_show[f]["id"]):d.slide_show[f]["src"]),function(){this.parentElement.style.backgroundImage="url('"+this.src+"')"});d.o.appendChild(h.parentElement);d.img.push(h)}}if(d.auto){for(var f in d.auto){var h=Player._initimg(d,Player.applyMask(d,d.auto[f]),function(){this.parentElement.style.backgroundImage="url('"+this.src+"')"});d.o.appendChild(h.parentElement);d.img.push(h);if(f==0){h.parentElement.classList.remove("hidden")}}}if(d.click_to_start){d.o.classList.add("pointer");d.o.onmousedown=function(a){delete d.slide_show;delete d.auto;d.start.call(null)}}d.rotate=function(){if(!d.slide_show&&!d.auto){return}var e=d.idx;if(++d.idx>d.img.length-1){d.idx=0}var a=Number(d.delay)?Number(d.delay)*1000:2000;if(d.img[d.idx]&&d.img[d.idx].parentElement.style.backgroundImage!=undefined){if(d.img[e]){d.img[e].parentElement.classList.add("hidden")}d.img[d.idx].parentElement.classList.remove("hidden");if(d.slide_show){if(Number(d.slide_show[d.idx]["d"])){a=Number(d.slide_show[d.idx]["d"])*1000}if(!d.click_to_start){if(d.slide_show[d.idx]["a"]){d.o.onclick=function(i){document.location=d.slide_show[d.idx]["a"]};d.o.classList.add("pointer")}else{d.o.onclick=undefined;d.o.classList.remove("pointer")}}}}window.setTimeout(d.rotate,a)};if(d.transition){p["#%id% div.hidden"]=p["#%id% div.hidden"].concat(Player.browsers("transition","opacity "+d.transition))}d.rotate()}else{if(d.click_to_start){d.o.classList.add("pointer");if(d.theta!=undefined||d.rho!=undefined){d.o.onmousedown=d.start}}else{try{while(d.o.firstChild){d.o.removeChild(d.o.firstChild)}}catch(l){}d.spin=d.rho[0]=="0"&&Number(d.rho[d.rho.length-1])==360*(1-1/d.rho.length);console.log("BEFORE o.it: "+d.it+", o.ir: "+d.ir);if(d.ir==undefined){d.ir=d.spin?0:Math.round((d.rho.length-1)/2)}else{for(var j in d.rho){if(Number(d.rho[j])==Number(d.ir)){d.ir=Number(j)}}}if(d.it==undefined){d.it=Math.round((d.theta.length-1)/2)}else{for(var j in d.theta){if(Number(d.theta[j])==Number(d.it)){d.it=Number(j)}}}console.log("AFTER o.it: "+d.it+", o.ir: "+d.ir);var h=Player.initimg(d,d.ir,d.it);d.o.appendChild(h);d.o.style.backgroundImage="url('"+h.src+"')";h.parentElement.classList.remove("hidden");d.dragtospin=document.getElementById(d.id+"_dragtospin");if(d.dragtospin==undefined){d.dragtospin=document.createElement("div");d.dragtospin.setAttribute("id",d.id+"_dragtospin");d.dragtospin.classList.add("dragtospin")}else{if(d.dragtospin.classList.contains("hidden")){d.dragtospin.classList.remove("hidden")}try{d.dragtospin.parentElement.removeChild(d.dragtospin)}catch(l){}}d.count=0;d.total=d.rho.length*d.theta.length;for(var s in d.theta){d.img.push([]);for(var b in d.rho){var h=Player.initimg(d,b,s,function(){if(d.dragtospin!=undefined){d.dragtospin.innerHTML="<span><strong>"+(++d.count<d.total?d.count+" / "+d.total:(d.drag_to_spin?d.drag_to_spin:"Drag to spin"))+"</strong></span>"}});if(d.ir!=b||d.it!=s){d.o.appendChild(h)}d.img[s].push(h)}}d.o.appendChild(d.dragtospin);d.o.onmousedown=function(a){var i=Player[this.id];if(i.count!=i.total){return}i.scaleX=i.o.offsetWidth/40;i.scaleY=i.o.offsetHeight/30;i.x=a.screenX;i.y=a.screenY;if(i.dragtospin!=undefined){i.dragtospin.classList.add("hidden")}if(!i.o.classList.contains("move")){i.o.classList.add("move")}i.o.onmousemove=function(o){var n=i.ir+(o.screenX>i.x?Math.floor((o.screenX-i.x)/i.scaleX):-Math.floor((i.x-o.screenX)/i.scaleX));var r=i.it-(o.screenY>i.y?Math.floor((o.screenY-i.y)/i.scaleY):-Math.floor((i.y-o.screenY)/i.scaleY));if(r>=i.theta.length){r=i.theta.length-1;i.y=o.screenY}else{if(r<0){r=0;i.y=o.screenY}}if(n>=i.rho.length){n=i.spin?0:i.rho.length-1;i.x=o.screenX}else{if(n<0){n=i.spin?i.rho.length-1:0;i.x=o.screenX}}if((r!=i.it)||(n!=i.ir)){i.x=o.screenX;i.y=o.screenY;i.o.style.backgroundImage="url('"+i.img[r][n].src+"')";i.it=r;i.ir=n}};i.o.onmouseup=function(n){Player.clear(c)};i.o.onmouseout=function(n){Player.clear(c)}}}}p["#%id%"]=p["#%id%"].concat(d.fit_parent?[{height:"100%"},{"background-size":"auto 100%"}]:[{width:d.width+"px"},{height:d.height+"px"}]);Player.css(d,p)}catch(k){console.log(k)}};Player._css={"#%id%":[{"background-repeat":"no-repeat"},{"background-color":"transparent"},{"background-position":"center center"},{"-webkit-user-select":"none"},{"-khtml-user-select":""},{"-moz-user-select":""},{"-o-user-select":""},{"-ms-user-select":""},{"user-select":""},{position:"relative"}],"#%id% div":[{position:"absolute"},{height:"100%"},{width:"100%"},{"background-size":"auto 100%"},{opacity:"1"},{"pointer-events":"none"},{"background-position":"center"},{"z-index":"10"}],"#%id% div.hidden":[{opacity:"0"},{"z-index":"11"}],"#%id% img":[{display:"none"}],"#%id%.pointer":[{cursor:"pointer"}],"#%id%.move":[{cursor:"move"}]};Player.css=function(f,b){function d(p){var m="",e,n="";for(var l in p){m+=l.replace("%id%",f.id)+" {\n";for(var h in p[l]){e=Object.keys(p[l][h])[0];m+=e+": "+(p[l][h][e]==""?n:p[l][h][e])+";\n";if(p[l][h][e]!=""){n=p[l][h][e]}}m+="}\n"}return m}var g=document.getElementById(f.id+"_css");try{if(g!=undefined){document.getElementsByTagName("head")[0].removeChild(g)}}catch(c){}var a=document.createElement("style");a.type="text/css";a.setAttribute("id",f.id+"_css");if(a.styleSheet){a.styleSheet.cssText=d(b)}else{a.appendChild(document.createTextNode(d(b)))}document.getElementsByTagName("head")[0].appendChild(a)};Player.browser_styles=function(b,a){return"\"'-webkit-"+b+"': '"+a+"'\", \"'-moz-"+b+"': '"+a+"'\", \"'-o-"+b+"': '"+a+"'\", \"'-ms-"+b+"': '"+a+"'\", \"'"+b+"': '"+a+"'\""};Player.browsers=function(k,v){return eval("[{'-webkit-"+k+"': v}, {'-moz-"+k+"': v}, {'-o-"+k+"': v}, {'-ms-"+k+"': v}, {'"+k+"': v}]")};Player.clone=function(b){var d=[];for(var c in b){d[c]=b[c].slice(0)}return d}; </script>
[ 2 ] Player.init()
The Player.init() component is the JSON object containing the configuration parameters required by Player JS [ 1 ] to display your AR mockup. The Player.init() [ 2 ] is used to assign the Player to a specific HTML element [ 4 ] such as a div located somewhere in your web page.
The Player.init() may be included in a <script> tag in your web page and called via <body onload=”Player.init()…”> or it may be attached to any other user event which occurs on your page. Please note that until Player.init() is called, the HTML element [ 4 ] will maintain its original appearance, as defined by your CSS style [ 3 ].
The most common configuration parameters will be described in the next section;
| PARAMETER | DESCRIPTION |
|---|---|
| DEFAULT is ‘player’… The id is a unique name that you assign within the Player.init() as well as to the html element id (see HTML below). Both id’s must match for the Player.init() to find the html element on your web page. If you plan to have multiple AR players per web page then the id’s must be unique for each instance. | |
| Player width. This value represents the width of the player container. If your rendered AR mockup has too much white-space on either side of the product you can simply enter a smaller width to crop the image. | |
| Player height. This value represents the height of the player container. If your rendered AR mockup does not have enough white-space above or below the product you can simply enter a larger height to increase the player size. | |
| When fit_parent is set to 1 your AR mockup will be size dynamically to fit the parent element. If fit_parent is not defined or is not set to 1 then the Player will default to using the width and height values. | |
| DEFAULT is ‘./img’… The base is the path to your images. Generally the path is set to ‘./img’ because the panel exports your AR Mockup to your local computer. However, if you want to host the images on your server and only send your client the HTML player then you can set the base to a URL such as: ‘https://www.my-site.com/mockups/can001/img’ |
[ 3 ] CSS Style
The CSS styles defined below represents the default appearance of the Player. Attributes such as player width, height, background-color and or background-image of the .player_wrapper {} class will be displayed when the page is initially loaded.
When the Player.init({id: ‘’player’, …}) [ 2 ] is called, the HTML element [ 4 ] with id ‘player’ will either fill or center itself on the wrapper element, as per the configuration parameters in Player.init() [ 2 ].
[ 4 ] HTML Element
In the HTML sample below, you will notice two <div> elements. The inner <div id=”player”> is managed by the Player JS [ 1 ] and the outer <div class=”player_wrapper”> defines the appearance and placement for your player.
The id parameter you supply in the Player.init() [ 2 ] configuration must exactly match the id of the inner DIV element. The class for “dragtospin” will allow you to customize the span element which appears over the HTML element once it has become active. The Player [ 1 ] will create a <span> element automatically when the Player.init() [ 2 ] component is called.
Player Configuration
Interactive
When applying the Interactive configuration in Player.init() [ 2 ], the Player pre-fetches all the images in the AR mockup sequence. The Interactive player is then instantly available to the person viewing your web page and is ready to be spun and rotated.
Click Show Player below to see the required parameters to initiate interactive player mode as well as a live sample.
| PARAMETER | DESCRIPTION |
|---|---|
| DEFAULT is “Drag to Spin”… Each AR player displays an overlay with a simple instructional text message. This message can be changed here or translated to a language which suits your target audience. | |
| When fit_parent is set to 1 your AR mockup will be size dynamically to fit the parent element. If fit_parent is not defined or is not set to 1 then the Player will default to using the width and height values. | |
| Passing a value of 1 to click_to_start informs the player that it should wait until a mouse click or tap gesture is detected before loading the entire image sequence. To function as expected you will be required to define an image to load as the poster frame in your css when using this option. We have provided a practical example further down the page in the section titled “Interactive with Click-to-Start“. Click here to scroll to it. | |
| DEFAULT is ’75’… The “initial theta” value represents the angle you wish to start the player with. There are 7 available theta positions. These are: 0 (top), 15, 30, 45, 60, 75, 90 (front) | |
| DEFAULT is ‘0’… The “initial rho” value represents the rotation you wish to start the player with. There are 24 available rho positions. These are: 0 (front), 15, 30, 45, 60, 75, 90 (right), 105, 120, 135, 150, 165, 180 (back),195, 210, 225, 240, 255, 270 (left), 285, 300, 315, 330, 345 | |
| AR Mockups can be viewed from 7 angles starting from the top (0°) to the front (90°). The angles to export are selected by you within the Photoshop AR Mockups panel. The array of values you see here represents your choices made in the panel itself therefore you should have no need to modify these values. | |
| AR Mockups can be rotated (spun) around a full 360°, however, we only provide views every 15 degrees for a total of 24 views per 360° rotation. The array you see here represents the range of spin you selected for the AR Mockup within the Photoshop panel. You should have no need to modify these values. | |
| DEFAULT is ‘{id}.jpg’… The image filename structure. If your image sequence all start with ‘container’ then your mask would be defined as ‘mask_{id}.jpg’. |
Auto Spin
The Auto Spin mode offers an easy way to simulate video without audio. In effect, applying the Auto Spin configuration parameters into Player.init() [ 2 ] your mockup will give visitors the impression they are watching a 360° video of your AR mockup.
To view this in practice, click the Show Player sample below.
| PARAMETER | DESCRIPTION |
|---|---|
| Begins cycling through an array of images, can be combined with transition and delay per image to simulate a true slideshow. Setting the delay speed to .1 for each slide will look more like an animation (that is, you can make your AR mockup appear to be spinning). |
Slideshow
Visually similar to Auto Spin, the Slideshow mode also cycles through your frames at various speeds via the delay: parameter. For example, increasing the delay between frames from 1s to a larger value like 5s or greater, is a great way to simulate a photo gallery slideshow. Note that Slideshow mode does not support frame delays less than 1s.
You can take things a step further and add transition effects between frames.
Lastly, each individual frame can have its own hyperlink (or a shared url) that will take your visitor to that url when they click on the player.
Slideshow mode is not limited to playing an AR mockup, you are free to use any image sequence you like and are also not bound by the limit of 24 frames which applies only to AR mockups.
| PARAMETER | DESCRIPTION |
|---|---|
| Adds a time delay between frames when set, when combined with transitions can simulate a smooth photo gallery slideshow. | |
| Allows you to set a transition effect between frames. Format is defined as [transition-duration] [transition-timing-function], EXAMPLE: ‘1s ease-in-out’ where 1s = 1 second (the time in which you want the effect to complete) and ease-in-ease out is the effect itself. | |
| Allows you to add a hyrperlink to each individual frame in your slideshow. |
Chaining Modes
Auto > Interactive
Another feature of the Player is its ability to chain modes together. In the sample below the Player starts off in Auto Spin mode but switches into the Interactive mode once a mouse clip or tap gesture is detected.
When a delay of 1 second or longer is applied to the Auto Spin mode it starts to resemble a Slideshow. However, note that Auto Spin mode does not support hyperlinks and will simply switch to Interactive mode.
Additional Player & Slideshow Samples
Interactive with Click-to-Start
When the Interactive’s click-to-start mode is passed the boolean value 1 the Player will wait for a mouse click or tap gesture before loading the entire AR mockup image sequence.
When using the click_to_start parameter it is important to note that the poster frame must be defined in your CSS style [ 3 ]. An example of how this is done is provided in the contextual sample which you can download below.
Click Show Player to view the example.