Tutorial: Video Kiosk Remote Management Reference Guide


Because Video Kiosk was designed to be remotely managed, it supports both sending status tracking reports to a URL and receiving responses so you can integrate Video Kiosk remote devices into a management system. Video Kiosk Android examines the response to the HTTP/HTTPS POST for key value pairs that it will use to update the management interface settings. 

This provides the ability for

  • Your Management System can receive status tracking reports from each device and
  • Your Management System can send instructions to your devices.

A management status POST can be sent:

  • based on a time interval
  • based on a specific time of day
  • any time using the Send Management Report button on the button bar

HTTP vs HTTPS considerations

If you plan to send the Video Kiosk Device password as a means of authenticating the post, you should use HTTPS posts instead of HTTP because it is not a good idea to send password data in the clear. To use HTTPS, you must get an SSL certificate from a certificate authority that the Android OS recognizes. Video Kiosk does not support HTTPS POST to sites using self-signed certificates.


How to enable device status tracking

To set up device status tracking, follow these steps:

  1. If you plan to send HTTPS posts instead of HTTP posts, get an SSL certificate. For more information, see [HTTP vs HTTPS considerations] below
  2. In the Video Kiosk settings, Video Kiosk Settings Screen>Management configure the following:
    • readable Device ID and Zone (optional settings for your convenience)
    • When to report status
    • URL to report status to
    • Content of the Post

Video Kiosk devices will now send posts to the specified URL.


Status Report Post Content: Supported POST Key Value Pairs Sent

The following keys will always be included in the POST:

androidid

The unique id of the device assigned by the Android OS.

uid

The unique id of the device as assigned by you.  By default this is the unique id assigned by the Android OS but you can change it to be any string that you like.

version

The Video Kiosk version name like 4.1.0.150529.

osversion

The version of Android OS on the device.

date

The UTC date on the device at the time the POST was sent in the form YYYY-MM-DD HH:MM:SS +HH:MM. An example is 2016-08-07 16:59:49 +00:00.

The following keys can be included in the POST by selecting them in the Management Settings (Video Kiosk Settings > Management > Management Post Content)

isplaying

A flag that will be true if a video is playing or false otherwise. Be careful interpreting the value since it can be false if an image file is being displayed or if one video has ended and its last frame is being displayed while the next video is preparing to play but has not yet rendered its first frame.

currentmedia

The name of the currently playing video or displayed image file. By default this key value pair is enabled.

folderpath

The path to the currently selected media folder. Please note that if you enable this key, then the names of the media items in the foldercontent array will be relative to this path and if you do not specify this key then the names will be the full path.

foldercontent

The names of all the media items in the currently selected media folder.

password

The password assigned to the Video Kiosk using the someword.password file. You can use this to authenticate the Video Kiosk POST. If you are sending this data, you should use HTTPS instead of HTTP, since it’s not a good idea to send the password in the clear.

zone

The zone of the device as assigned by you to create any grouping of devices that you would like.

isroot

A flag that will be true if the device has been granted root access or false otherwise.

uptime

The time, in seconds, since the last device reboot

filesize

An array of file sizes that matches the array of file names. [comma-separated list of values]

emptyfiles

An array that lists any files that are empty (probably due to a network error during file synchronization with your cloud service). [comma-separated list of values]

widgetsenabled

A flag that will be true if widget areas are enabled or false otherwise.

areabwidgets

An array that lists the widgets configured in widget area B [comma-separated list of values]

areacwidgets

An array that lists the widgets configured in widget area C [comma-separated list of values]

areadwidgets

An array that lists the widgets configured in widget area D [comma-separated list of values]

onetouchplay

An array that lists first a flag that is set to true if the onetouchplay feature is enabled and then the Onetouchplay interval from the settings [comma-separated list of values]

sendstandby

A flag that will be true if the sendstandby feature is enabled

interactions

An array of key value pairs that lists the identifying string and interaction count for each hotspot for which the interaction count has been set in the Hotspot Overlay .XML. For hotspots without an identifying string, interactions will not be counted or reported. {comma-separated list of key value pairs where key=value}

location

The location of the device as provided by a GPS latitude and longitude pair OR the postal address of the device entered as a human readable string


Sending Instructions to your Devices

In the Video Kiosk Management settings you can:

  • Change the unique device id
  • Change the device zone
  • Set the  interval time, in minutes, at which Video Kiosk will send the  POST
  • Enable or disable sending the POST using the interval time
  • Set the time of day, in hours and minutes, at which Video Kiosk will send a POST
  • Enable or disable sending the POST using the time of day
  • Configure the URL to which the  POST will be sent
  • Enable or disable the optional key value pairs that can be sent in the  POST

Whenever you change the settings, Video Kiosk will restart the interval time. If you have enabled the time of day status POST, Video Kiosk will synchronize the interval time with the time of day when that POST is sent.


Responses: Supported POST Key Value Pairs in Response

The management interface supports responses by the management system to management status POST, such that the management settings on the device can be changed by the management system.

The management system may respond with a list of key value pairs as follows:

key=value\n
key=value\n

key=value\n

\n means newline as defined in the PHP scripting language.

The values are encoded using the Android URLEncoder and the UTF-8 character set.  PHP programmers that use $_POST variables should decode these values using the urldecode() method.  PHP programmers that use $_REQUEST variables should not decode the values since they have already been decoded.

The supported key value pairs are:

uid=some id
zone=some zone
reporttime=HH:MM (where 0 >= HH <= 23 and 0 >= MM <= 59)
reporttimeenabled=true|false
intervaltime=NNNN (where NNNN > 0)
intervaltimeenabled=true|false
postkey_isplaying=true|false
postkey_currentmedia=true|false
postkey_foldercontent=true|false
postkey_password=true|false
postkey_zone=true|false
postkey_isrooted=true|false
postkey_folderpath=true|false
postkey_widgets=true|false
postkey_hdmicec=true|false
postkey_interactions=true|false
postkey_location=true|false
setdate=YYYY:MM:DD:HH:MM:SS

It’s important to note that if both intervaltimeenabled and  reporttimeenabled are set to false you will stop that device from reporting status.  If you do that via a management POST response then management posts can only be restarted manually from the device.

If the \n characters are omitted, Video Kiosk will ignore the key value pairs.  You MUST include the newline character for every key value pair.


Example of Use: Sending an email containing POST Data – PHP Script

The following PHP script can be used to send an email containing status tracking POST data to whatever email account you would like. You just need to change the values of $to_email, and $from_email and then put the script on your web site in a file named something.php. If you need more information contact us and we can help you.

<?php
    $to_email = 'you@yourdomain.com';
    $from_email = 'do-not-reply@yourdomain.com';
    $subject = 'VidoeKiosk Status';

    foreach ($_POST as $key => $value)
    $message .= htmlspecialchars($key)." = /".htmlspecialchars(urldecode($value))."/\n";

    $headers = 'From: ' . $from_email . "\r\n" .
            'X-Mailer: PHP/' . phpversion();

            mail($to_email, $subject, $message, $headers);
?>

Resources

Take the Next Step