Gallery configuration

Gallery library has a set of parameters that allow you to customize the user experience.

This configuration can be set with Global configuration, which will affect all the previews on your website, or Single Item configuration that will affect only those elements where the configuration attributes are added.

Global configuration parameters

Global configuration is done via attributes on the Gallery script tag and affects all the previews placed by the Gallery on your website.

For example: for a redirect experience with custom redirect text, your script file would look like this:

 <script src="//static.vilynx.com/gallery/vpg.{{galleryVersion}}.min.js"
        data-publickey="youruserhash"
        data-redirect="true"
        data-redirecttext="Personalized redirect text"></script>

Gallery plugin can be customized in different ways depending on the user experience wanted on your website.

Redirect options

One of the most valued features of the Gallery library is the ability to redirect (with a 3, 2, 1 countdown) to your video content after one loop of the preview. Redirect is only available for Desktop browsers; if you want a similar experience for mobile devices take a look at Mobile options.

To enable this, add data-redirect attribute as global configuration. There are a set of parameters to customize the redirect experience:

Name Type Default Item config Description
redirect Boolean false Yes Shows a countdown while user is hovering over the video. Once the countdown is finished, the user gets redirected to the parent link.
redirecttext String Video Will Begin In... Yes Message shown along with the redirect countdown.
redirectwithclick Boolean true Yes When redirect countdown finishes, does a .click() on the element with external id. Needed if the parent is not an <a> tag. (example: inline video player)
redirectwithclicktarget String Query Selector No Does .click() action on the element recieved at applying the Query Selector on the element with external id.
redirectafter Number Video duration Yes Time in ms to wait before starting the countdown.
redirectautoplay Boolean false Yes Only with autoplay. If a user hovers over the autoplaying preview, redirect text is shown after one video loop. (This time can be modified with redirectafter attribute).
audiopolicycta Boolean false Yes Shows CTA (call-to-action) text instead of the redirect countdown when user has audio policy active for this browser. Read Audio policies section if you need more information.

Autoplay options

Gallery provides the option to play the preview automatically when it appears in the screen.

To do this, add the data-autoplay attribute as a global configuration. There are a set of parameters to customize the autoplay experience:

Name Type Default Item config Description
autoplay Boolean false Yes Shows the preview when it enters the viewport.
redirectautoplay Boolean false Yes Only with redirect. If a user hovers over the autoplaying preview, redirect text is shown after one video loop. (This time can be modified with redirectafter).
redirectafter Number Video duration Yes Only with redirect. Time in ms to wait before starting the countdown.
autoplayonce Boolean false Yes Preview will autoplay and loop once when it enters the viewport.
fadeinadvance Number 700 Yes Combined with autoplayonce, time in ms that the image will be faded in before video first loop ends. Default value is added to hide the video own fading.
pauseonhover Boolean false Yes Pauses the autoplaying preview when the user hovers over it.
audioonce* Boolean false Yes First loop of the preview is played with audio.
audiohover* Boolean false Yes Preview is played with audio when the user hovers over on it.
stopnoimage Boolean false Yes When a video is stopped by adding Item configuration vilynx_stop, paused video frame is showed instead of original image.

* Webkit Browsers have strict policies while trying to play media content with audio. Check the Audio Polices section to know what Gallery library does when a preview with audio is played on a user which has audio policy active.

Mobile options

The default user experience on mobile is one preview playing at a time, which starts when the preview appears in user's screen. There are a set of parameters to customize this mobile experience:

Name Type Default Item config Description
taptoplay Boolean false Yes Previews will be activated with a tap and swipe action on mobile devices, instead of autoplaying when entering the viewport.
mobilepreload Boolean true No Previews are preloaded before entering the viewport for a quicker start.
maxpreloadedvideos Boolean 5 No Only with mobilepreload. Maximum number of previews that can be preloaded at the same time.
mobilecta Boolean false Yes Shows a CTA (call-to-action) message after the first preview loop.
mobilectatext String See The Full Clip Yes Only with mobilecta. Text displayed when CTA message appears.
mobilectaloopcount Number 1 Yes Only with mobilecta. Loop after which the CTA message appears.
hidectaicon Boolean false Yes Only with mobilecta. Hides play icon when CTA message appears.
allautoplay Boolean false No All previews within the viewport are played simultanously. On iOs devices this can't be done with video elements and gifs are placed instead of videos.
followscroll Boolean false No Previews follow user scrolling movement to play next preview.
topviewportoffset Number 0 No Offset (in pixels) from the top of device's screen to consider as the top of viewport. Useful when the page has a header bar on the top.
bottomviewportoffset Number 0 No Offset (in pixels) from the bottom of device's screen to consider as the bottom of viewport. Useful when the page has a footer bar on the bottom.
previewdelay Number 0 No Time in ms to wait before preview starts playing once it enters the viewport.
horizontalThreshold Number 80 No % of element's width in viewport needed to play the preview.

Audio options

If you want your previews to play with sound data-audio is needed on the script tag.

Note that some browsers are moving forward on preventing media playback with sound if the user has not previously interacted with the website. You can find more informarion in the Audio policies section. If the preview can't be played with sound due to audio policy it will be played without sound.

Audio previews have a list of configuration options:

Name Type Default Item config Description
audio Boolean false Yes Plays preview with audio.
audioonce Boolean false Yes Only with autoplay. First loop of the preview is played with audio.
audiohover Boolean false Yes Only with autoplay. Preview plays with audio when the user hovers over on it.

General options

Apart from specific UX configurations, there are some general integration parameters.

Name Type Default Item config Description
publickey String No Unique id to identify your Vilynx account.
idattribute String No A custom attribute of yours that will contain the id to link video teases to previews in your account. Will be used in the same way as data-vilynx-id attriute.
disableall Boolean false No Disables all elements for previews except those with the vilynx_enabled class specified.
nomobile Boolean false No Deactivates the Gallery on mobile devices.
notablet Boolean false No Deactivates the Gallery on tablet devices.
bgimageselector String Query Selector div, button No Query selector used to find elements with background inside the element with external id. You can find more information in Background images section.
directurl Boolean false No Only if using guids as external ID. Gets previews with a redirection instead of using get_hashes API call. Contact us if you want more information.
imgignore String Query Selector No Ignores a specific image (via Query Selector) from being selected as the preview main image (the preview size and positioning is based on the main image). You can find more information in Working with multiple images section
divignore String Query Selector No Elements to ignore so as not to disrupt preview playback on hover. Very usefull when, for example, a play icon is on top of the preview and is capturing the mousover event, making the preview stop when the mouse passes through this icon.
divignorelevels Number 0 No Number of parent nodes of the element with the external id to apply divignore Query Selector. For example, if the element to ignore is on the same div as the preview element, a value of 1 will be needed.
noimage Boolean false Yes Removes the original thumbnail (displays the preview right away).
ignorehref Boolean false No Ignores href attributes for <a> tags, looking only for data-vilynx-id attribute.
proactiveload Boolean false No Looks for new videos in viewport every 300 ms instead of on scroll. Necessary when working with carousels.
urlregexp String Regular Expression No Regular expression to remove parts of the url before being compared to the external ids stored in your Vilynx account. Useful to remove query parameters on href values for your preview candidates.
ignorecurrenturl Boolean false No Ignores current path to be a preview candidate.
disablestorage Boolean false No If set to true, prevents the Gallery from storing any cookies on your site. Check the Cookie storage policies section for more information.
reduceresolution Boolean false No If enabled, the preview resolution will be lowered one level.

Third party integration options

Gallery library allows third-party integration for analytics or A/B testing. The library will register and track events with Optimizely or your own tools. You can find more information on third-party integration section.

Here are the configuration parameters to integrate with third parties:

Name Type Default Description
ongalleryload Boolean false Function name to execute when the gallery loads. Check the Other analytics tools integration section
optimizely Boolean false Sends optimizely events to optimizely (Note: will use the account registered in your domain). Check the Optimizely integration section.
optimizelyoff Boolean false Disables Vilynx previews but keeps tracking clicks for Optimizely. Check the Optimizely integration section.
previewplaytimeout Number 500 Time in ms since the preview starts playing and the Sumary Play event is tracked..

Single item configuration parameters

Some of the Global Configuration options can also be set as Item Configuration on single elements using configuration classes. This is useful for customizing your Gallery experience on specific elements or sections of your site. Note that these options will override Global Configuration if setted.

Check the Item config column on Global configuration tables to know if a specific parameter can be set as Item configuration.

This configuration can be set as an attribute inside the element which contains the external id. For example:

<a href="external_video_id" data-redirect="true" data-redirectafter="3000">
   <img src="img/bg01.jpg">
</a>

If the value is a Boolean type, it can also be set as a class inside the element by adding vilynx_ before parameter's name. The example above could be written as:

<a href="external_video_id" clas="vilynx_redirect" data-redirectafter="3000">  
    <img src="img/bg01.jpg">
</a>

There are a few other configuration classes which can be used:

Class Description
vilynx_disabled Before the gallery loads prevents an element from having a preview.
After the gallery loads disables an element that already has a preview.
vilynx_enabled If disableall parameter is active, allows this element to be tracked by the Gallery libray. If the element doesn't have an image or a data-vilynx-id attribute, makes the library observe it until having one.
vilynx_stop If an element's preview is playing this class will pause/unpause the video by adding or removing it.