Articles in this section

API - Properties

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

accountID
  • Type: integer
  • Default: null
  • The account ID that should be used to retrieve content for the 360 HD Viewer. This is a required parameter for constructing the 360 HD Viewer instance and cannot be modified after instantiation.
alternateContent RP
  • Type: array of objects
  • Default: null
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • The alternateContent property allows you to add extra content such as images and videos to be shown in the 360 HD Viewer viewport. The alternate content requires that the thumbs be enabled as it will not be possible to select an image or video otherwise. The only exception to that is when used without Cylindo content and when there is only one alternate element. The alternate content will be displayed in the order they are defined in the array.
  • As functionality differs between alternate images and alternate videos then so do some parameters for the alternateContent objects. Please see below for the data structure and values required to embed either for an alternate image or video.

Images

An alternate image object consists of the following properties:

  • image
    • Type: string
    • The url for the image which should be shown when the image thumbnail is clicked. This is the only required field in the object as the other fields will use this image if they are not defined. We do however recommend a smaller thumb image is provided and a larger resolution image for the zoom image to improve performance. The image does not need to have the same size as the 360 HD viewport, but for optimal performance we recommend that it does. The Image can be larger or smaller than the 360 HD viewport.
  • [description]
    • Type: string
    • optional
    • A description of the image that will be inserted as the alt text for the element. The same description will be used for the thumb image with the postfix - “thumb”.
  • [thumb]
    • Type: string
    • optional
    • The url for a thumb sized image to show in the thumb bar. It will use a browser scaled down version of the normal image if it is not provided.
  • [zoom]
    • Type: string
    • optional
    • The zoom image to be used if zooming is enabled on environment images. If no image is defined it will use the image defined in the “image” property. When zooming on alternate images it will never zoom closer than the zoomed images' natural size.

Example

{
        'image': 'some url',
        'description': 'description',
        'thumb': 'some url',
        'zoom': 'some url'
        }

 

Videos

You can embed a YouTube, Vimeo or self-hosted video into the 360 HD Viewer. For self hosted videos then please note that not all video formats are supported by all browsers and devices. For an more detailed description of supported file formats please see MDN.
You can implement videos by using the following properties:

  • provider
    • Type: string
    • The url for the image which should be shown when the image thumbnail is clicked. This is the only required field in the object as the other fields will use this image if they are not defined. We do however recommend a smaller thumb image is provided and a larger resolution image for the zoom image to improve performance. The image does not need to have the same size as the 360 HD viewport, but for optimal performance we recommend that it does. The Image can be larger or smaller than the 360 HD viewport.

 

DIRECT VIDEOS OBJECT CONFIGURATION

  • sources
    • Type: array of objects
    • Sources is an array of objects used to create a group of sources for the self-hosted videos in order to provide fallback options in case the browser is unable to process one or more sources. Each source object represents a video format to be recognized and validated by the browser. For each video you can set more than 1 source and the browser will check if it is possible to reproduce the source type. If it is possible, that video source will be played, if not - it will check the next source until one succeeds or all fail. Each source object needs the 'src'(source) property that is the URL of the self-hosted video, and the 'type'property to set the type of the video.
  • src
    • Type: string
    • The video source property is a string with the self-hosted video url - e.g. 'www.example.com/path/to/video.mp4'.
  • type
    • Type: string
    • The type property is a string with the self-hosted video type - e.g. 'video/mp4'.
  • [description]
    • Type: string
    • optional
    • Text with video description.
  • [thumb]
    • Type: string
    • optional
    • Thumb image url is used in case thumbs are enabled. By default we display the fallback video image because some browsers don't download frames from videos until they are played by the user. We are unable to get frames to create a thumb in those cases.
    • Although this parameter is optional it is highly recommended to specify a value for it, in order to show a frame from the video or a custom image as a thumb.
  • [poster]
    • Type: string
    • optional
    • This is a placeholder image set on the video before it is played for the first time. We suggest you set this property because some mobile devices only display a blank square instead of frames of the video before it is played. Also windows browsers use that image in case of any errors, instead of triggering the 'onerror' event from the sources.
  • [options]
    • Type: object
    • optional
    • This is a map object used to set the video options available for self-hosted videos. This type of video supports the 'autoplay' and 'currentTime' options.'autoplay' must be 1 or 0. By default it is set to 1, which will autoplay the video once it is displayed in the viewport. 'currentTime' sets the time where the video should start. It is specified in seconds.
{
        'provider' : 'direct',
        'description': 'Some description here',
        'thumb': 'some url',
        'poster': 'some url',
        'sources': [{
           'src': 'some src',
            'type': 'some type',
        }],
        'options': {
            'autoplay': 1 | 0, // By default 1
            'currentTime': 5
        }
    }

 

VENDOR VIDEOS OBJECT CONFIGURATION

  • url
    • Type: string
    • Video URL from vimeo or youtube. The URL must have the video id (in case of vimeo it is a number, for youtube it can be an alphanumeric value) to be recognized by the viewer. In case of an error with the provided URL, youtube will display the video player with the error message “An error occurred please try again later.” Vimeo displays an image with the error message that has occurred - e.g. ‘Sorry, ’ + error message. For youtube URLs we don't support video lists, so the URL should contain the video id only.
  • [thumb]
    • Type: string
    • optional
    • Thumb image URL, used in case of thumbs enabled. By default we try to get the thumb image from the provider's API.
      NOTE: Vimeo API has a rate limiting access, so we suggest our clients to set the thumbnail property to increase the performance of their applications and avoid possible issues.
  • [options]
    • Type: object
    • optional
    • This is a configuration object where you can set options such as controls, color, etc. These options are different for each provider, please check the following URLs for more details. These options are commonly used to change the appearance or behavior of the video player.
    • For youtube you can set the video player options shown on this page -Youtube developer page
    • For vimeo you can set the video player options shown on this page -Vimeo embedding guide
Example
{
        'provider': 'vimeo' | 'youtube',
        'url': 'some url',
        'thumb': 'some thumb url',
        'options': {
        autoplay: 1 | 0, // By default 1}
        }
alternateContentZoom
  • Type: boolean
  • Default: true
  • Enables or disables zoom for alternate images.
ARQuickLook
  • Type: boolean
  • Default: true
  • This property determines if viewer contains AR button or if it is omitted.
  • For Apple devices AR button will be displayed in Safari if iOS version is equal or greater than 12. On devices with Android, AR button will be displayed in Google Chrome if Android version is equal or greater than 7. In case ARCore 1.9 or greater is not found an error tooltip will be displayed and AR button will be hidden. On Android viewer instance should be served over the HTTPS protocol, otherwise AR button will not be displayed.
ARDesktop
  • Type: boolean
  • Default: false
  • This property controls the visibility of the modal with a QR code in desktop devices. When it is set to true the modal is shown.
ARBtnTxt
  • Type: string
  • Default: View in your space
  • This property controls the text used for the View in your space button.
ARBackToViewTxt
  • Type: string
  • Default: Back to 360 view
  • This property controls the text used for the Back to 360 view button shown when the QR modal is displayed.
ARNotAvailableTxt
  • Type: string
  • Default: Unfortunately, your mobile<br/> device does not support<br/> this feature.
  • This property controls the text used for the fallback modal shown when the AR experience could not be executed.
ARLoadingTxt
  • Type: string
  • Default: Loading
  • This property controls the text used for the loading modal shown when the AR experience is being triggered.
ARBanner
  • Type: string
  • Default: none
  • This property controls the visibility of the AR banner on mobile devices and platforms.
  • Possible values: none, ios-android, ios, android.
ARBannerConfig RP
  • Type: object
  • Default: null
  • AR banners can be displayed for the AR view of both platforms, iOS and Android. However the information displayed on each platform differs, so this property allows users to choose the information displayed for the banner along with the texts displayed in the action buttons.
  • On Safari/iOS the user is able to configure the title, subtitle.
  • On Android devices the user is able to configure the title.
  • For both cases the redirect url is set through the getArRedirectUrl property.
  • This property allows to modify the default values used for the ar banner, the available options to modify the banner are: 
    • qrAction
      • Default: Visit
      • This property controls the text displayed in the action button displayed on the banner when the AR view is open through the QR code.
      • Displayed only in iOS Safari
    • action
      • Default: Visit
      • This property controls the text displayed in the action button displayed on the banner when the AR view is open through the “View in your space” button of the viewer instance
      • Displayed only in iOS Safari
    • title
      • Default: Product code value
      • This property controls the text displayed in the title of the banner
      • Displayed on iOS and Android devices for all browsers
    • subtitle
      • Default: Product code  value
      • This property controls the text displayed in the description of the banner
      • Displayed only in  iOS Safari
    • price
      • Default: Empty string
      • This property controls the text displayed for the price section on the banner of the iOS devices
      • Displayed only in iOS Safari
backgroundColor RP
  • Type: string
  • Default: FFFFFF
  • This backgroundColor parameter is used to set the background color of the frame images. The supported values are HEX colors for the frame. e.g. backgroundColor: 'FFFFFF' white color in hexadecimal.
carouselSlideSpeed
  • Type: number
  • Default: 32
  • Determines the speed at which the carousel images move to the next.
containerID
  • Type: string
  • Default: null
  • The id property of the container the 360 HD Viewer should be embedded into. This will typically be a div element like this: This is a required parameter when instantiating the 360 HD Viewer.
customZoomContainer
  • Type: string
  • Default: null
  • Sets an external zoom container by specifying the ID of the element that should be used. This method can be used to display zoom images in a popup or fancybox. When enabled, activating zoom will show the external zoom container instead of the standard zoom. If implementing a custom zoom container we recommend that it is placed on top of the 360 HD Viewport and a then extended beyond the viewport for an increased zoom area.
    NB! Please note, the external zoom container has no default styling. In order for the container to display it is required to specify height and width attributes.
cylindoContent
  • Type: boolean
  • Default: true
  • Property indicating if the 360 HD Viewer is being used with Cylindo content or as a simple viewport for customer hosted images. You can use this property to give a uniform appearance of styling and functionality across products despite the products not being Cylindo 360 products. If you disable Cylindo content then you can instantiate a 360 HD Viewer using alternate images.
debug RP
  • Type: boolean
  • Default: false
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Allows for the 360 HD Viewer to print out debug messages to the console.
fallbackImage RP
  • Type: url
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This property is a url for an image that will be used as a fallback image if the Cylindo 360 HD Viewer fails to initialize correctly when instantiating an instance.
fallbackVideoImage RP
  • Type: url
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Custom fallback image used for videos.
features RP
  • Type: array of strings
  • Default: null
  • An array of features needed to specify the desired variation of the product. While it also can be updated post instantiation using the update function then we highly recommend you use the specific function setFeatures to change features.
  • If features and configurationAlias properties are not set when initializing the HD 360 Viewer the default configuration set for the product is displayed.
  • This property can not work together with the configurationAlias property.
fileName RP
  • Type: string
  • Default: null
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • The file name property allows you to set the name used for images when will be downloaded.
focusOnFeatureChange
  • Type: boolean
  • Default: false
  • Property enabling/disabling auto focus on feature change. When enabled this will allow the 360 HD Viewer to scroll the top of the 360 HD viewport when a valid feature set has been requested (not on invalid requests). This property can only be enabled on mobile devices e.g. desktop browsers will ignore this property completely.
format
  • Type: string
  • Default: jpg
  • Possible values: jpg, png
  • This controls the images format used for the frames displayed in the viewer. This property doesn’t work for zoom images where the default format is JPG.
frames
  • Type: array
  • Default: null
  • This property is used in combination with the presentation property for "carousel"and "stacked" viewers. By default this property is set to null which will show all the available frames for the requested product. If an array with values is provided for this property, then only the frames specified in the array will be shown in the viewer in the same order as in the array.
fullscreen
  • Type: boolean
  • Default: true
  • Property enabling/disabling the ability to go into fullscreen mode. For browsers where fullscreen events are not supported, this functionality is disabled by default. For this reason it is not possible to go into fullscreen mode on IOS, some android devices and IE9 and IE10.
gaEvents
  • Type: boolean
  • Default: true
  • This property enables or disables the Google Analytics events.
getArRedirectUrl
  • Type: function
  • Default: null
  • This property receives a callback function, which should return a redirection URL to be used when generating the QR code for the AR flow on desktop.
imageTimeout
  • Type: integer
  • Default: 0
  • This property indicates how long the 360 HD Viewer should wait for an image to be downloaded. If the image takes longer to process than the specified value in milliseconds, then the viewer will cancel the download and display the fallback image instead. The default value is 0 which means it will wait for the http request to timeout.
loggerLimit
  • Type: integer
  • Default: 100
  • This property is the number used to set the max number of messages stored in the logger.
maxZoom RP
  • Type: string
  • Default: Mobile phones use '2k', for all the other devices default value is '4k'.
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • String flag added to select the max zoom value for zoom module, the supported values are '2k' and '4k' by default mobile phones will take 2k and all the other devices tablets, desktops will take 4k.
missingCombinationErrorText RP
  • Type: string
  • Default: Sorry, we do not have images for the requested feature set.
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This property holds the text that will be displayed if a sequence does not exists. You can remove the missing combination warning by setting this property to null or an empty string (“”).
presentation
  • Type: string
  • Default: "threesixty"
  • Possible values: "threesixty", "single", "carousel", "stacked"
  • This property defines the type of presentation for the viewer using cylindo content (cylindoContent = true). The viewer presentation is in "threesixty" mode by default. When this property is set to "single", it will show a single cylindo frame. By default it will show the first frame in the 360 sequence. If the property startFrame is explicitly specified, then its value will determine the frame which will be shown. For "carousel"and "stacked" viewers, the frames which will be displayed are determined by the frames property. By default all frames defined as cylindo content will be shown, unless specific frames are set in the frames array. The order in which the images will appear is also determined by the frames property.
productCode
  • Type: string
  • Default: null
  • The code of the product that should be displayed. A valid instance cannot be created without a value for this property. The productCode should match the value agreed upon between Cylindo and the Customer at content creation time..
progressBar 
  • Type: boolean
  • Default: true
  • Property determining if there should be a progress bar indicating the progress when downloading the 360 content.
QRCodeTitleTxt 
  • Type: string
  • Default: View this product<br/> in your space
  • This property controls the text of the title used for the loading modal shown when the AR experience is being triggered.
QRCodeTxt
  • Type: string
  • Default:  Point your smartphone or tablet's<br/> camera at the QR code below.
  • This property controls the text used for the loading modal shown when the AR experience is being triggered.
removeEnvironmentShadow RP
  • Type: boolean
  • Default: false
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Property used to remove the environment shadows of the products displayed through the HD 360 viewer.
rotationSpeed RP
  • Type: float
  • Default: 1
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Property determining the rotation speed when moving the mouse/finger. The higher the value the faster it will rotate in the same amount of distance.
size
  • Type: integer
  • Default: null
  • Provides the possibility to specify the size of the images to be displayed in the 360 viewer.
startFrame
  • Type: integer
  • Default: 1
  • Provides the possibility to specify a particular frame which the viewer should show first. This way the user may select a frame at an angle to be the starting point of the 360 viewer.
styleshots
  • Type: boolean
  • Default: true
  • This property allows to enable or disable styleshot images.
styleshotsZoom
  • Type: boolean
  • Default: true
  • Enables or disables zoom for styleshots.
thumbAngles RP
  • Type: array of integers
  • Default: null
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • You can use this property to override the use of the default angles generated based on the thumbCount property. It will also override the number of thumbs shown. This is an array of integer angles in degrees that should be shown (or the closest possible angle) e.g. [ 0, 90, -90 ] for a front, right and left view.
thumbCount RP
  • Type: integer
  • Default: 5
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This property states how many thumb images from the 360 content that should be displayed in the thumb bar.
thumbLocation
  • Type: string
  • Default: "bottom"
  • Possible values: "top", "bottom", "left", "right"
  • This property controls the thumbnails panel location, by default thumbnails are placed at the bottom of the viewport.
thumbPageSize RP
  • Type: integer
  • Default: 5
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This property indicates how many images the thumb scroller should move when the user clicks the arrow buttons on the thumb bar. It is used when initializing the viewer, but it can be used to update an existing viewer instance.
thumbs
  • Type: boolean
  • Default: true
  • This property determines if the 360 HD viewer contains thumbs or if they are omitted.
title RP
  • Type: string
  • Default: 360 HD product view
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This is the title for the whole viewer container and will appear as a tooltip when hovering the 360 HD Viewer container. It can be used by used by html screen readers to mention what the content is. It can be removed by setting the value to null or an empty string (""). This value can be set at any time during the lifecycle of the instance.
tooltipAltImgText RP
  • Type: string
  • Default: Click to Zoom
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Property for setting the text that is displayed once the user has selected an alternate image. A null value or empty string (“”) can be used to remove the text.
tooltipCarouselText
  • Type: string
  • Default: Click to Zoom
  • Property for setting the text that is displayed once the user can click and change the image in the Carousel viewer. A null value or empty string (“”) can be used to remove the tooltip text.
tooltipDragText RP
  • Type: string
  • Default: Drag to Rotate. Click to Zoom
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Property for setting the text that is displayed once the user can click and drag the image to rotate the 360 degree view. A null value or empty string (“”) can be used to remove the drag text.
tooltipStackedPosition
  • Type: integer
  • Default: 1
  • Possible values: 1, 2, 3
  • Property for setting the position where the tooltip is displayed in case of tooltips are enabled for the Stacked viewer. By default a tooltip is displayed for each frame displayed in the stacked viewer. The possible values are 1 to display tooltip on each frame, 2 to display the tooltip only on the first frame or 3 to display the tooltip on the last frame.
tooltipStackedText
  • Type: string
  • Default: Click to Zoom
  • Property for setting the text that is displayed once the user can click on the images in the Stacked viewer. A null value or empty string (“”) can be used to remove the tooltip text.
tooltipStyleshotText RP
  • Type: string
  • Default: Click to Zoom
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This property sets the text which will be visible when a styleshot image is displayed in the viewer.
tooltipZoomText RP
  • Type: string
  • Default: Move the Mouse to Pan
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • Property for setting the text that is displayed once the user can move the mouse to pan the zoom image. A null value or empty string (“”) can be used to remove the zoom text.
version
  • Type: integer
  • Default: null
  • The version of the product that should be displayed. By default the viewer is displayed with the version marked as “Default” in the CMS. (NB: Setting version should only be used when testing new products or product versions. Expect slower responses for request of specific versions.
zoom
  • Type: boolean
  • Default: true
  • This property indicates if it should be possible to zoom on the 360 content.
zoomBackgroundColor
  • Type: string
  • Default: FFFFFF
  • Supported values HEX colors for the zoom container. The zoom background color is automatically updated if the "backgroundColor" property is set explicitly. If the value for "zoomBackgroundColor" is set explicitly, then it takes precedence. e.g. zoomBackgroundColor: 'FFFFFF' white color in hexadecimal.
zoomButton
  • Type: boolean
  • Default: true
  • Property enabling/disabling the zoom button.
zoomMode
  • Type: string
  • Default: 'mouseMove'
  • Possible values: mouseMove, mouseDrag
  • This controls the way zoom movement works on desktop devices. One tracks the mouse movement on top of the viewport, while the latter relies on clicking and dragging the image in the viewport.

Deprecated properties

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

buildNumber RP
  • Type: string
  • Default: null
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • The build number will append the value to requests. You can use this to ensure the latest content is loaded.
  • This property has been deprecated. There is no replacement for the buildNumber property
country
  • Type: string
  • Default: null
  • The country parameter used to retrieve content from the Cylindo 360 HD Viewer backend. This is a required parameter when instantiating the 360 HD Viewer instance.
  • This property has been deprecated. There is no replacement for the country property
environmentZoom
  • Type: boolean
  • Default: false
  • This property can be updated after the 360 HD Viewer has been instantiated.
  • This property sets the value for alternateContentZoom and styleshotsZoom if it is specified in the initial configuration object and the other 2 properties are not explicitly specified.
  • This property has been deprecated. alternateContentZoom and styleshotsZoom properties can be set individually.
imageResolution
  • Type: integer
  • Default: null
  • Property for using a secondary image resolution. This can be used on e.g. mobile devices to load smaller images which are less bandwidth intensive. Please contact your account manager if you need a custom resolution for your content.
  • This property has been deprecated. Use the property size to set image size
SKU
  • Type: string
  • Default: null
  • The SKU of the product that should be displayed. A valid instance cannot be created without a value for this property. The SKU should match the value agreed upon between Cylindo and the Customer at content creation time.
  • This property has been deprecated. Use the new productCode property
viewerType
  • Type: integer
  • Default: 1
  • This temporary property can have the value 1 or 2. It is in place to allow for Cylindo to switch on content while our backend is completely transitioned to a new backend. In some cases and for new customers this will be have to set to 2, while for existing customers it can be left the default (1) value.
  • This property has been deprecated. There is no replacement for the viewerType property.
© 2023 Cylindo. All Rights Reserved.
Cookie policy Privacy policy