Video Kiosk Overlay and Hotspot Reference Guide

Video Kiosk supports an overlay file with transparency (.png format with a file name that end in .overlay.png), which is displayed in front of the currently displayed media, with or without hotspots.

An Overlay without the addition of hotspots is often used to overlay a graphic over part of the display – often a company logo in the corner of the screen.

(Click to enlarge)

An Overlay with the addition of hotspots is used to turn your device into an interactive kiosk

How to use an Overlay File

Overlays are used to overlay a graphic over part of the display, often a company logo in the corner of the screen.

To use an Overlay, follow these steps:

Create an overlay file
Create a PNG file with the same frame size as your display. For example, if you are using a 720p display, you would create a PNG file that is 1280×720 in size. Somewhere in the PNG file put your logo, or whatever content you want to use to overlay the video.
Move the overlay file onto the device or synchronize it using a cloud service.
Video Kiosk assumes you’ve put the Overlay file in the Content Loop folder. If you’ve put it somewhere else, configure Video Kiosk with the location of the overlay file. Go to  Video Kiosk Settings > Overlay > Path to Overlay folder  and set the path to the overlay folder.
Go to  Video Kiosk Settings > Overlay > Overlay file  and select the overlay to use.
Optionally, if the overlay image is a different size than the screen dimensions you may want to adjust the scale type using Video Kiosk Settings > Overlay > Overlay image scale type

Video Kiosk will overlay your screen with the content of the overlay file.

Resources:

Using Overlays with Interactive Hotspots

Video Kiosk supports using a hotspot xml file, with hotspots and/or key codes defined, to allow the user to interact with the device. Interactions can also be tracked.

Using Hotspots to control interaction behavior

A hotspot is a rectangle somewhere on the screen and its associated URL | App. When the hotspot is touched, the URL will be displayed using the integrated kiosk web view or the App will be launched as a new activity on top of Video Kiosk. (The URL can point to a file on the device or a file on the Internet).

If you are using Video Kiosk in digital signage mode, you can specify the URL | App for each App Widget. Video Kiosk will first look at App Widgets configuration, and use any values found there while falling back to the XML file configuration if nothing was specified for the App Widget.

Note: If you plan to use a hotspot associated with an App package name, there is no automatic mechanism that ensures a device abandoned by a user will return to the loop and the user must take specific action to return to Video Kiosk so that the loop continues to play.

Using Key Codes to control interaction behavior

A key code is the Android key code that corresponds with an individual key on an input device. When the key on the device that corresponds to the Android key code is touched, the URL will be displayed using the integrated kiosk web view or the App will be launched as a new activity on top of Video Kiosk.

Interaction Tracking

Video kiosk can track interactions with hotspots. If you want Video Kiosk to track interactions, specify an interaction key. To report on interactions, enable interaction reporting on the Video Kiosk management interface.

If you are using Video Kiosk in digital signage mode, you can specify the interaction key for each App Widget. Video Kiosk will first look at App Widgets configuration, and use any values found there while falling back to the XML file configuration if nothing was specified for the App Widget.

How to use an overlay xml Hotspot file

To use hotspots, follow these steps:

If you haven’t already done so, create an .overlay.png file
In a Text Editor or XML Editor, create an XML Hotspot file to control interaction behavior. When you have finished editing the file, change the file name to the same name as your overlay file and change the extension to “.xml” so Video Kiosk will recognize it as the hotspot file that goes with the overlay file. For example, if your overlay file is called “videokiosk.overlay.png”, name your XML hotspot overlay file,  “videokiosk.overlay.png.xml”.
- To learn how to create an XML file, refer to How to create an XML file.
- For file content requirements, refer to the Video Kiosk XML Hotspot file Syntax Guide, below.
Move the XML hotspot file onto the device or synchronize it using a cloud service. Put the XML hotspot file in the same folder as the Overlay file so that Video Kiosk will find it automatically.
Optionally, configure the timeout for the WebView in Video Kiosk (The default is 30 seconds). For more information on optional settings, refer to the Video Kiosk Users Manual.
If you are using Video Kiosk in Digital Signage mode and have configured the XML file to use the <widgetarea></widgetarea> tag, then configure the URL | App and interaction key for each App Widget that you add to each Widget Area. If you don’t configure those items in the Widget Area configuration, Video Kiosk will use the configuration from the XML file.Note: If you are using Widget Areas to define the URL | App, you should align the hotspots so that they appear over the widget areas. This is not required, but it probably makes the most sense to do it this way.

Hotspot .xml file Syntax Guide

<hotspots> </hotspots>				A list of hotspots
	<hotspot> </hotspot>			A single hotspot. To be active, each hotspot requires a destination url or app is specified and that an activating rectangle and/or key code is specified.
		<url> </url>		Destination web URL used for a single hotspot
		<app> </app>		Destination App name used for a single hotspot
		<widgetarea> </widgetarea>		Look at the specified Widget Area (B \| C \| D) for the url, app, and interaction key. The values will be selected based on the current widget being displayed in the Widget Area. If values are found in the Widget configuration use them otherwise use the ones specified in this file.
		<keycode> </keycode>		The Android key code, used to activate a hotspot using a keyboard
		<rect> </rect>		The screen rectangle for the hotspot defined using numbers between 0 and 1 as a fraction of the screen
			<top> </top>	Rectangle top
			<left> </left>	Rectangle left
			<bottom> </bottom>	Rectangle bottom
			<right> </right>	Rectangle right
		<intereactionkey> </intereactionkey>		(Optional) A string that identifies the hotspot. If this tag is set, the interactions for the hotspot will be counted and reported. If this tag is not set, the interactions for the hotspot will not be counted.
		password> </password>		(Optional) A SHA 512 encoding of the password that must be entered to access this APP or URL
		<pinned> </pinned>		(Optional) A boolean that determines if Video Kiosk tries to keep the launched App pinned. The default value is false. On Android 9 setting the value to true has no effect because Android v9 requires a new task which will result in the display unpinning.

Hotspot .xml file example

Here is an example of what a file that contains 2 hotspots could look like.

The first hotspot’s destination is the URL “https://burningthumb.com”. It can be triggered by touching the hotspot rectangle or by pressing the key corresponding to key code 51. The interactions to this hotspot are counted and reported in the Management Report with the Identifying string of “burningthumb”.
The second hotspot’s destination is the App “Calculator2”. It can be triggered by touching the hotspot rectangle or by pressing the key corresponding to key code 29. The interactions to this hotspot are neither counted nor reported in the Management Report.

Video Kiosk Android - Hotspot XML Example

Hotspot .xml file Verification help

To help test and debug your .xml file, Video Kiosk has an optional setting you can use to highlight your hotspots on your screen so that you can ensure they are in the correct place and functioning as expected. Remember to turn this feature off before releasing the device to users.

To turn verification mode on