Articles in this section

API - Functions

This section contains the available functions within the 360 HD Viewer.

 

destroy()
  • Destroy the 360 HD Viewer instance and remove it from the page. All resources reserved in the 360 HD Viewer instance will be released and any subsequent calls on the instance will result in undefined behaviour.

 

exitZoom()
  • Exits the zoom mode. If it is currently in zoom mode it will return true, otherwise it will return false. Exiting zoom using this function will also trigger the zoom exit event.
  • Return: boolean

 

getAccount()
  • Get the Customer account ID the 360 HD Viewer is created with.
  • Return: integer

 

getCurrentFrameIndex()
  • Get the current frame index (1 based) which is currently shown in the 360 HD Viewport.
  • Return: integer

 

getCurrentImageUrl(size [,ssl])
  • Get an url for the current frame in the given size. The ssl parameter indicates if the returned url should use the “https:” protocol. This is an asynchronous function.
  • Return: string

 

getDebugInfo(logLevel)
  • This is a method used to get all the logger information of a certain type stored for each viewer. This method takes a bitwise parameter, specified in the "loggerMap" (see loggerMap section), and prints a filtered list of the currently stored messages in the browser's console.
    There is a public property on the instance called "loggerMap" which contains the possible bitwise values for the logger messages.
    Possible values are:
    • loggerMap.LOG
    • loggerMap.INFO
    • loggerMap.WARNING
    • loggerMap.ERROR
    • loggerMap.EVENT
  • Type: bitwise value
  • Example: instance.getDebugInfo(instance.loggerMap.LOG | instance.loggerMap.WARNING); // Retrieves only log and warning messages.

 

getFeatures()
  • Get a list of the features currently displayed in the 360 HD Viewer. The returned array will always have a length that is a multiple of two and contain feature sets in the same way features are input to the 360 HD Viewer.
  • Return: array of strings

 

getProduct()
  • Get the product code of the product that is being displayed in the 360 HD Viewer. When the product code is changed at runtime the value retrieved by this function changes according with the new product displayed in the 360 HD Viewer.
  • Return: string

 

getVersion()
  • Get the current version of the 360 HD Viewer.
  • Return: string

 

goToAngle( angle )
  • This function allows the user to show the closest image to the specified angle.
  • Type: integer

 

isPanning()
  • Function that returns true/false depending on if the user is currently panning the 360 viewer in the zoom mode. This can be used to ignore hover state on e.g. swatch images while the user is rotating (which might bring the cursor outside the 360 viewport).
  • Return: boolean

 

isRotating()
  • Function that returns true/false depending on if the user is currently rotating the 360 viewer. This can be used to ignore hover state on e.g. swatch images while the user is rotating (which might bring the cursor outside the 360 viewport).
  • Return: boolean
nextSlide()
  • This function shows the next available image in a carousel type viewer.

 

off( event, callback )
  • Unsubscribe the given callback from the given event. While the event can be written as a string we highly recommend using the constant event values defined in the “instance.events” object e.g. “instance.events.ZOOM_ENTER”. For a full list of events that are available then please see section 6.5 Events.
  • Type: string, function

 

on( event, callback )
  • Subscribe to one of the available events. While the event can be written as a string we highly recommend using the constant event values defined in the “instance.events” object e.g. “instance.events.ZOOM_ENTER”.
  • Type: string, function
previousSlide()
  • This function shows the previous image in a carousel type viewer.

 

rotate( degrees, milliseconds )
  • This method allows to rotate a 360 viewer programmatically. The function receives two parameters - angle and milliseconds; the second one is optional and it will move directly to the desired angle without rotation if it is not specified.
    Events SPIN_BEGIN and SPIN_END are triggered when auto rotate starts/finishes.
    If user tries to rotate manually, zoom on the image or enter fullscreen mode when it is auto-rotating, the rotation is stopped and we trigger the spin end event on the last frame displayed by the auto rotate function.
    If user clicks a thumb image while rotating we handle two cases, the first one when the clicked thumb is a 360 frame we stop the rotation and we trigger the SPIN_END event to allow the earlier rotation to display the clicked frame.
    If a user clicks an alternate image or styleshot image, the rotation is stopped and we trigger the SPIN_END event and we display the alternate/styleshot image.
    If a user tries to execute multiple auto rotate functions at the same time, only the first rotation is executed and the rest are ignored in order to prevent the rotation from breaking.
    The degrees parameter indicates the angle that the viewer needs to move. So if the viewer is at 90 degrees and the user executes rotate(90, 150), this will move the viewer to its 180 degrees position over 150ms time. However, if the user wants to do a full rotation from 90 to 90 degrees, then they would have to execute the following - rotate(360, 150) which will perform a full rotation in 150ms starting and ending at 90 degrees.
    An IMPORTANT NOTE to take into account is the time and the distance. In the above examples, both rotations should complete in 150ms, but the first is just 1/4 of a rotation, while the second is a full rotation, which means that the first animation will be very slow, compared to the second which will be very fast.
    Finally it is worth to mention that the function accepts negative degrees values, which will make the viewer turn from right to left. For example rotate(-90, 150) starting at 90 degrees will make the viewer turn left until it gets to 0 - the initial position.
  • Type: integer, integer

 

setFeatures( array_of_features )
  • Change the features shown in the 360 HD Viewer. The array of features should follow the format: [“feature type”, “feature value”,.....] and always have a length that is a multiple of two. Changing features will take effect immediately and while the new image feature set is being downloaded the 360 HD Viewer will ignore rotation and zoom input.
  • Type: string

 

setProduct( productCode )
  • Change the product shown in the 360 HD Viewer. The supplied parameter must be the product code of the new product to be displayed. Changing productCode will take effect immediately and while the new set of images is being downloaded the 360 HD Viewer will ignore rotation and zoom input. When the new set of images have been downloaded the same events of the change of features behavior are triggered for this method.
  • Type: string

 

showStyleShot( styleshotID )
  • This method allows to show a styleshot image by passing either its index or the styleshot code.
  • Type: string

 

update( property_name, value )
  • Update the value of a property. Please see section 6.6 Properties for a list of properties that can be modified after the initialization of the 360 HD Viewer instance.
  • Type: string, any

 

zoom( x, y [, index ] )
  • This function allow users to open zoom programmatically. The function receives x and y coordinates in fractions which represent the point of the image which will be displayed in the center of the viewport.
  • Programatic zoom shows the current active image, the only exception is when presentation is set to stacked and fullscreen is not enabled, for that case the index parameter should be set to indicate which image should be opened on zoom mode.
  • If zoom is already opened when zoom function is called, zoom panel will be moved to show the desired coordinates. For stacked presentation if requested index is not the same than the current index zoom will be restarted to show the new index.
  • Type: integer, integer[, string ]

 

Deprecated functions

The following functions will be deprecated in the next major Cylindo 360 HD Viewer release. If you use any of the following functions, we encourage you to update your implementation when you upgrade to Viewer version 4.x.

addToCart( price, currency, quantity, callback )
  • Instruct the 360 HD Viewer built-in tracking component that the current selected variation has been added to the cart with the given price, currency and quantity. While the currency does not require a specific format we highly recommend using the three letter ISO 4217 currency acronym for consistency and for easier comparison. This can be called at any time while the instance is valid.
    You can add a callback parameter to be notified of the server's response. The callback takes one parameter ("result") which will be "true" if all went well and we got a 200 response, or "false" if the request failed with a 4XX or a 5XX error.
  • Type: float, string, integer, function
  • There is no method replacing this function. We recommend customers to utlize the Google Analytics integration.
checkout( items, totalPrice, currency, callback )
  • Instruct the 360 HD Viewer built-in tracking component that the currently selected items in the cart have been checked out with the number of items, total price and currency. While the currency does not require a specific format we highly recommend using the three letter ISO 4217 currency acronym for consistency and for easier comparison. This can be called at any time while the instance is valid.
    You can add a callback parameter to be notified of the server's response. The callback takes one parameter ("result") which will be "true" if all went well and we got a 200 response, or "false" if the request failed with a 4XX or a 5XX error.
  • Type: integer, float, string, function
  • There is no method replacing this function. We recommend customers to utlize the Google Analytics integration.
getArQuickLookUrl( callback )
  • Retrieves the URL of the USDZ file to the provided callback. This function works only if ARQuickLook property is enabled and the 3D model file exists for the requested SKU. On iOS it will look for the USDZ file while Android will look for the GLB file.
  • This functionality is replaced by Cylindos Content API, where you can request AR files with same parameters you use for specifing specific product configurations.

 

getCurrentFrameUrl(size, callback [, ssl ])
  • Get an url for the current frame in the given size. Do note that the 360 HD Viewer currently does not support the CAPI authorization header and as a consequence the size must be equal to or smaller than the agreed default viewport size. The callback function should take an url and an error message parameter e.g. “function urlCallback(url, errorMsg)”. The ssl parameter indicate if the returned url should use the “https:” protocol. This is an asynchronous function.
  • Return: integer,function[,boolean]
  • Replaced with new getCurrentImageUrl() but we highly recommend the usage of the new content API to get images.

 

getFrameUrl( frameNumber, size, callback [, ssl ] )
  • Get an url for a specific frame in the given size. Do note that the 360 HD Viewer currently does not support the CAPI authorization header and as a consequence the size must be equal to or smaller than the agreed default viewport size. The callback function should take an url and an error message parameter e.g. “function urlCallback(url, errorMsg)”. The ssl parameter indicate if the returned url should use the “https:” protocol. This is an asynchronous function.
  • Return: integer,integer,function[,boolean]
  • In case the requested image corresponds to the current frame displayed in the HD 360 viewer the getCurrentImageUrl() could be used but we highly recommend the usage of the new content API to get images.

 

getItem( sku, quantity, price, retail_price, array_of_features )
  • Create an item that can be used as a parameter in the checkout function.
    The difference between the price and the retail_price parameter is the retail price is not discounted while the price might be. The array_of_features parameter is an array of string using the same approach as in the initialization of the Cylindo 360 HD Viewer and setFeatures function.
  • Type: string, integer, float, float, array of strings
  • Return: object
  • There is no method replacing this function. We recommend customers to utlize the Google Analytics integration.

 

getImage( url, callback[, authorizationKey] )
  • This function downloads a BLOB image from the API, that BLOB is temporarily stored in the browser and the browser creates an image URL that is passed to the callback function.
    It works together with the getUrl function to get URL of the blob image to download.
  • Type: string, function[, float, string, boolean]
  • Return: string
  • To get images we recommend the usage of our content API.

 

getSKU()
  • Get the current SKU that is being displayed in the 360 HD Viewer.
  • Return: string
  • Replaced with new getProduct()

 

getState()
  • This function returns the state that the viewport is in at the moment of execution
  • Return: string
  • Possible values:
    • AlternateContent
    • AlternateContentZoom
    • AlternateContentFullScreen
    • AlternateContentZoomFullScreen
    • Carousel
    • CarouselZoom
    • CarouselZoom
    • CarouselFullScreen
    • CarouselZoomFullScreen
    • FallbackOverride
    • FallbackFullScreen
    • ImageOverride
    • ImageOverrideZoom
    • ImageOverrideFullScreen
    • ImageOverrideZoomFullScreen
    • Initializing
    • Single
    • SingleZoom
    • SingleFullScreen
    • SingleZoomFullScreen
    • Stacked
    • StackedZoom
    • StyleShot
    • StyleShotZoom
    • StyleShotFullScreen
    • StyleShotZoomFullscreen
    • Threesixty
    • ThreesixtyZoom
    • ThreesixtyFullScreen
    • ThreesixtyZoomFullScreen
    • Unititialized
  • There is no method that substitutes the getState() method. You can subscribe to the viewer events for all cases.

 

hideImage()
  • Hide an image that has been shown using the “showImage” function. The 360 HD Viewer will retain the state it had before the image was shown.
  • There is no method that substitutes the hideImage() method.

 

showImage( imgUrl [, largeImgUrl ] )
  • Override the 360 viewport and show a custom image. If zooming is enabled and a large image url is provided the user can zoom on that image. If no large image url is provided, but zooming is enabled the user can zoom on the initial image. The image can be removed again using the “hideImage” function.
  • Type: string[,string]
  • There is no method that substitutes the showImage() method.

 

skuExists( accountID, SKU, callback )
  • This function checks if the requested sku exists. It receives as parameters the accountID, the SKU and a callback to execute it after the server responds.
    The callback receives a boolean parameter as a response from the server.
    It is not required to initialize a viewer instance to use this function as it is available on the global "cylindo" object.
  • Type: integer, string, function
  • Example: cylindo.viewer.services.skuExists(4404, 'ARMCHAIR', function(result) {...}); // "result" parameter will be true if SKU exists and false if it doesn't exist.
  • We recommend using the content API to check if the product exist and which configurations it's avilable in.