PROVISIO DevBlog

Compatibility Issue with SiteKiosk and IE10 on Windows 7

We are currently investigating a SiteKiosk startup issue that occurs when SiteKiosk is used on a Windows 7 system with Internet Explorer 10. Under the restricted SiteKiosk user the SiteKiosk browser may not be able to start properly because of problems with the new Webcache folder introduced by IE10.

 

It is recommended to not upgrade to Internet Explorer 10 on Windows 7 systems. Microsoft provides a toolkit to prevent systems from automatically receiving the IE10: http://www.microsoft.com/en-us/download/details.aspx?id=36512.

 

We are working on this issue and try to resolve it as soon as possible.

People who are already affected and experience a loop during SiteKiosk startup can use the instructions from this FAQ to reset the system: http://www.provisio.com/en-US/CustomerSupportCenter/ArticleDetails.aspx?ArticleID=364.

 

Please note that Windows 8 with IE10 is not affected.

Changing the User Agent of the SiteKiosk Browser

The user agent string is used to identify the browser with which a client contacts a server. This information can be utilized to decide what kind of content is delivered to the client in return, to make sure the browser receives data that is optimized for exactly that type of browser. 

SiteKiosk uses the public WebBrowser control of the Microsoft Internet Explorer installed on the system. This means that SiteKiosk identifies itself with the same user agent string as the IE. When a standard configuration is used SiteKiosk will add SiteKiosk Version Number at the end of the user agent string, e.g. SiteKiosk 8.6.1251. A full user agent string under SiteKiosk will look like this:

Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0; SiteKiosk 8.6 Build 1251)

Adding SiteKiosk to the user agent can be used for example to let a server deliver SiteKiosk Object Model code to a client. You can deactivate this behaviour in the SiteKiosk configuration and you can also add your own identifiers. You can find more information on this topic here: http://www.provisio.com/helpconsole/SiteKiosk%20Help/en-US/default.htm?advanced_settings.htm#three.

Ideally the above means that your client browser receives the content it is supposed to display in the most suitable form. If a kiosk project is created from scratch, the content can be optimized to fit the kiosk. Even in projects where content has already been created, it will usually run without modifications on the kiosk, because the content has already been designed for usage in a standard browser like IE.

In some cases though, it might come in handy if your browser could pose as something completely different, for example in a kiosk project where touchscreens should be used. The web pages that should be displayed are already existing in a version for normal browsers and in a version for mobile phones. The mobile phone version would fit perfectly but the server dynamically delivers its content based on the user agent. This means on a normal Windows system you would get the version for standard desktop browsers and not the version for mobile phones. The solution is to completely change the user agent string to one of a mobile phone.

Microsoft already provides this option by means of editing the Windows registry using the registry editor (regedit.exe). Note that changing the registry is always done at your own risk. Making the browser pose as another may also cause script errors or corrupted page layouts. You should carefully experiment with the values described next before applying it to live systems.

The registry key we will have a look at is for the Internet Explorer, but as SiteKiosk is based on the Internet Explorer it also uses it. That means changing the key will change the behaviour for IE and SiteKiosk. A detailed article on the topic of the user agent string on Windows systems can be found here: http://msdn.microsoft.com/en-us/library/ms537503%28v=vs.85%29.aspx. The registry key can be found at two different locations in the Windows registry.

One location is under

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\5.0\User Agent

Note: on a 64-Bit system the location is slightly different

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\5.0\User Agent

Editing that key changes the behaviour for all users on the system.

The other location is under

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\5.0\User Agent

Editing that key only changes the behaviour for the current user. This means to edit this key you must be logged in with the user you want to change the behaviour for.

On most systems the above key only contains the default value HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\5.0\User Agent\Default). For the desired effect we need to add two additional string values (unless they are already there). One is called Platform and the other Version. As an example we will add the following data to Platform (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\5.0\User Agent\Platform)

Linux; U; Android 4.0.4;

and the following data to Version (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\5.0\User Agent\Version)

AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30

These are values an Android smartphone uses. When the changes are done, we can see the effect by opening the SiteKiosk browser (or IE, as both are using that registry key) and going to www.nytimes.com. With the changes we will be directly transferred to the mobile version of the page. The SiteKiosk user string now looks like this:

Mozilla/5.0 (compatible; AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30; Linux; U; Android 4.0.4;; Trident/5.0; SiteKiosk 8.6 Build 1251)

If the above workaround is suitable for your project and you want to spare yourself the hassle of manually editing the registry on all your kiosk systems, you can use the SiteKiosk ProgramPatcher tool to automatically apply the registry changes.

Starting the SiteKiosk File Manager from a Link

The SiteKiosk file manager is usually started from the Start button in the task manager or the programs page. But it can be handy to start the file manager from a link or button link, especially when using the SiteKiosk Portal Startpage.

The file manager is built using HTML, but because of its capabilities it is hosted in a special dialog window. As a consequence just starting the selector.html, which is the base file for the file manager, is not an option. You can of course edit the code of the Portal Startpage, but there is a much simpler approach to it. We will just create a simple html page that will take care of opening the file manager. You can either put the file on the local machine (recommended location: ..\SiteKiosk\html\) or a web server and then create a new link in the settings of the Portal Startpage that uses this page.

Our example page will consist of two methods. The first one is not really required to start the file manager, but it will make the process more complete. It basically checks if SiteKiosk payment options are used and if they apply to starting the file manager. If that should be the case the process of opening the file manager will be aborted and the SiteKiosk payment information dialog shown. More information about this part of the code is available here. Now this is what the first method looks like:

function OpenMediaWindow()
{
	try
	{
		var lk_SiteCash = SiteKiosk.Plugins("SiteCash");
		if (lk_SiteCash == null || lk_SiteCash == undefined || lk_SiteCash.Enabled && !lk_SiteCash.PayApplications || lk_SiteCash.Enabled && lk_SiteCash.AccessStatus || lk_SiteCash.Enabled && lk_SiteCash.CurrentBalance > 0.0 || lk_SiteCash.Enabled && lk_SiteCash.ApplicationPrice == 0.0 || lk_SiteCash.Enabled && lk_SiteCash.AccessStatus || !lk_SiteCash.Enabled)
		{
			OpenIntWindow();
		}
		else
		{
			SiteKiosk.Plugins("SiteCash").ShowPaymentInfoDialog(0, "", false);
		}
	}
	catch (e)
	{
		OpenIntWindow();
	}
}

As you can see in the above code, it tries to open another method named OpenIntWindow once the prerequisites are met (or in case of an error, when it goes to the catch part). The OpenIntWindow method deals with opening the actual file manager window. It looks like this:

function OpenIntWindow()
{
	var WS_OVERLAPPED = 0x00000000;
	var WS_MAXIMIZEBOX = 0x00010000;
	var WS_MINIMIZEBOX = 0x00020000;
	var WS_THICKFRAME = 0x00040000;
	var WS_SYSMENU = 0x00080000;
	var WS_BORDER = 0x00800000;
	var WS_CAPTION = 0x00C00000;     // WS_BORDER | WS_DLGFRAME
	var WS_MAXIMIZE = 0x01000000;
	var WS_MINIMIZE = 0x20000000;
	var WS_POPUP = 0x80000000;
	var WS_OVERLAPPEDWINDOW = WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | WS_MINIMIZEBOX | WS_MAXIMIZEBOX;
	var WS_EX_TOOLWINDOW = 0x00000080;

	var mediabox = SiteKiosk.SiteKioskUI.CreateHTMLDialog();
	mediabox.URL = SiteKiosk.SiteKioskDirectory + "skins\\public\\Media\\FileManager\\Selector.html";
	mediabox.Styles = 13565952;
	mediabox.Icon = SiteKiosk.SiteKioskDirectory + "skins\\public\\Media\\FileManager\\Img\\Icons\\fms_ico.ico";
	mediabox.Width = screen.width > 800 ? 1024 : 800;
	mediabox.Height = screen.height > 600 ? 700 : 550;
	mediabox.ExStyles = 0;
	mediabox.Border = true;
	mediabox.Type = "FileManagerDlg";
	mediabox.TopMostWindow = false;
	mediabox.CloseOnInput = false;
	mediabox.Parent = SiteKiosk.WindowList.MainWindow.SiteKioskWindow.Window;
	mediabox.ShowDialog();

	window.close();
}

The first part of the method sets the different window styles used for the file manager dialog. The second part creates an HTML dialog object (SiteKiosk.SiteKioskUI.CreateHTMLDialog();) and assigns window styles, height, width etc. to it. You can learn more about this part here in the SiteKiosk Object Model help. The last line of the method tries to close the window or html page is using now that it has done its purpose of opening the file manager. This will of course only work if the link opened in a new window, which is the default behaviour for the SiteKiosk Portal Startpage.

Now we just put the two methods together and place it in some simple HTML. This is what we get:

<html>
	<script type='text/JScript'>
		window.external.InitScriptInterface();

		function OpenMediaWindow()
		{
			try
			{
				var lk_SiteCash = SiteKiosk.Plugins("SiteCash");
				if (lk_SiteCash == null || lk_SiteCash == undefined || lk_SiteCash.Enabled && !lk_SiteCash.PayApplications || lk_SiteCash.Enabled && lk_SiteCash.AccessStatus || lk_SiteCash.Enabled && lk_SiteCash.CurrentBalance > 0.0 || lk_SiteCash.Enabled && lk_SiteCash.ApplicationPrice == 0.0 || lk_SiteCash.Enabled && lk_SiteCash.AccessStatus || !lk_SiteCash.Enabled)
				{
					OpenIntWindow();
				}
				else
				{
					SiteKiosk.Plugins("SiteCash").ShowPaymentInfoDialog(0, "", false);
				}
			}
			catch (e)
			{
				OpenIntWindow();
			}
		}

		function OpenIntWindow()
		{
			var WS_OVERLAPPED = 0x00000000;
			var WS_MAXIMIZEBOX = 0x00010000;
			var WS_MINIMIZEBOX = 0x00020000;
			var WS_THICKFRAME = 0x00040000;
			var WS_SYSMENU = 0x00080000;
			var WS_BORDER = 0x00800000;
			var WS_CAPTION = 0x00C00000;     // WS_BORDER | WS_DLGFRAME
			var WS_MAXIMIZE = 0x01000000;
			var WS_MINIMIZE = 0x20000000;
			var WS_POPUP = 0x80000000;
			var WS_OVERLAPPEDWINDOW = WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | WS_MINIMIZEBOX | WS_MAXIMIZEBOX;
			var WS_EX_TOOLWINDOW = 0x00000080;

			var mediabox = SiteKiosk.SiteKioskUI.CreateHTMLDialog();
			mediabox.URL = SiteKiosk.SiteKioskDirectory + "skins\\public\\Media\\FileManager\\Selector.html";
			mediabox.Styles = 13565952;
			mediabox.Icon = SiteKiosk.SiteKioskDirectory + "skins\\public\\Media\\FileManager\\Img\\Icons\\fms_ico.ico";
			mediabox.Width = screen.width > 800 ? 1024 : 800;
			mediabox.Height = screen.height > 600 ? 700 : 550;
			mediabox.ExStyles = 0;
			mediabox.Border = true;
			mediabox.Type = "FileManagerDlg";
			mediabox.TopMostWindow = false;
			mediabox.CloseOnInput = false;
			mediabox.Parent = SiteKiosk.WindowList.MainWindow.SiteKioskWindow.Window;
			mediabox.ShowDialog();

			window.close();
		}
	</script>
	<body onload="OpenMediaWindow();">
	</body>
</html>

Note the extra line at the beginning of the script part (window.external.InitScriptInterface()). It tells SiteKiosk that SiteKiosk Object Model code follows. If you allowed this page to use such code, it will be executed. Once the page is loaded it calls the first method using onload. The script checks whether payment is required and then opens the file manager (or the payment information dialog).

That's it. The above should help in all cases, where you want to start the file manger from a link/button link. This includes the SiteKiosk Portal Startpage but could even used on any html page, including pages located on the Internet.

Please be aware, that you should activate the file manager in the configuration of SiteKiosk to make full use of this code example.

Manipulating the DOM with the SiteKiosk Object Model

Web pages that are used for a kiosk project are often ones that have been created before the kiosk project started and have not necessarily been created with kiosk usage in mind. In most cases this does not matter. But sometimes the requirements of a kiosk project may ask for special handling if a page is displayed on a kiosk (e.g. change button size). Ideally the web pages are then adapted, but this may not always be possible, e.g. because direct access to edit the pages is not possible.

With the help of the SiteKiosk Object Model pages displayed within the SiteKiosk browser can be altered by directly editing the DOM of a page. For that you need to look at the source code of a page, e.g. by using the developer tools of IE or Firefox, and find the appropriate places that need to be changed.

The following example demonstrates this by changing the Google page to show SiteKiosk as the search term and to use 'Search for SiteKiosk' as the caption of the search button. Copy the code example to Notepad and save it as a .js script file with whatever name you like, e.g. manipulatedom.js. Open the SiteKiosk configuration, go to Start Page & Browser or Browser Design (depending on the SiteKiosk version you are using), click on the Advanced button and add the script as an external script file. Save the configuration, start it with SiteKiosk and go to www.google.com to see the effect.

SiteKiosk.Logfile.OnMessage = OnMessage;
function OnMessage(seq, time, utcoff, awtype, awlevel, facility, text)
{
	if(text.indexOf("Navigation: http://www.google.") !== -1)
		evtid = SiteKiosk.Scheduler.AddDelayedEvent(500, ManipulateDOM);
}

function ManipulateDOM()
{
	for (var i=1;i<=SiteKiosk.WindowList.Windows.Count;i++)
	{
		try
		{
			if(SiteKiosk.WindowList.Windows(i).SiteKioskWindow.SiteKioskWebBrowser.WebBrowser.LocationURL.indexOf("http://www.google.") !== -1)
			{
				SiteKiosk.WindowList.Windows(i).SiteKioskWindow.SiteKioskWebBrowser.WebBrowser.Document.getElementById('gbqfsa').innerHTML = "Search for SiteKiosk";
				SiteKiosk.WindowList.Windows(i).SiteKioskWindow.SiteKioskWebBrowser.WebBrowser.Document.getElementById('gbqfq').value = "SiteKiosk";
			}
		}
		catch(e)
		{
			//SiteKiosk.Logfile.Notification("Editing the DOM failed for window: " + SiteKiosk.WindowList.Windows(i).ItemText); //Debug
		}
	}
}

The for part of the above code goes through all open windows to find the one that shows the Google page and apply the code.

Note that when using the above example you should make sure to take care of local laws, ownership rights, copyright etc. Also note that the above example only works as long as Google does not change the code of their page.

Securing the SiteKiosk browser with Microsoft EMET

SiteKiosk uses the browser engine of the installed Internet Explorer to render web pages. To minimize security risks you should therefore keep the Internet Explorer updated by using the automatic Windows Update feature that comes with the operating system.

Unfortunately there is the risk of so called zero day attacks. There was one just recently that affected the Internet Explorer and was covered extensively in the media. Because SiteKiosk uses the Internet Explorer engine it is also affected. While the security features of SiteKiosk do limit the attack options to a certain degree a possible risk remains.

It is also notable that one aspect of zero day attacks is, that even antivirus software does not help as a required signature update takes its time to become available.

This is where Microsoft EMET or Enhanced Mitigation Experience Toolkit comes in. The toolkit can be used to harden an application so that flaws cannot be used as easily and zero day attacks have no or a more limited effect. It is free to use and easy to configure.

When you install EMET make sure to select to install it for all users. After the installation is finished you can just add the SiteKiosk.exe and other applications you want to protect using EMET in the EMET configuration. That's it. You can keep on using SiteKiosk as you did berfore, but now with the extra protection that EMET provides.

How to Build a Script Watchdog for External Applications

The secure SiteKiosk browser offers an easy way to run external applications from within the restricted SiteKiosk context. You can just add the desired applications with the help of the SiteKiosk configuration. SiteKiosk will then provide means to start the applications through the SiteKiosk browser interface, it will also close these applications when the screensaver starts or a user logs out. The configuration of SiteKiosk even allows you to automatically start an application when SiteKiosk starts, the screensaver ends or after a user logout happend.

There can be situations where you may want to have even more control of the external application you want to run with SiteKiosk. For example you don't want to use the browser features of SiteKiosk but just want to use SiteKiosk to protect the operating system from being tampered with and your main goal is to permanently run a specific application.
The culprit is that this may be an existing application that for example allows to user to close it. This is where the SiteKiosk Object Model comes in. It is a proprietary Javascript extension that enables you to control nearly all aspects of SiteKiosk but also comes in very handy to create helpful custom scripts.

Let's summarize what we want to achieve with the script we are about to create. SiteKiosk should run in fullscreen mode in the background and on top of that an external application should always be visible.

The first step would be to create a blank page for SiteKiosk running in the background, alternatively you may of course as well use a page with a nice design. Here is the code for the blank page:

<html>
    <head>
    </head>
    <body>
    </body>
</html>

Save it as background.html (or whatever name you prefer) and make sure to put that file into the ..\SiteKiosk\html\ folder.

Next is the Javascript that we use to control the application. The first step is to start the application. For that we are using the Run method of the ExternalApps collection. Because we do need that code later on again, we will put it in a function:

function StartMyApp(){
    SiteKiosk.ExternalApps.Run("c:\\pathtomyapplication\\myapplication.exe", true);
}

The Run method basically expects the path to the application plus a boolean value that specifies if SiteKiosk is to check first if this application is already running. If it is already running, it will be maximized and focused. For the purposes of this script the boolean value should be true to ensure that no additional instances of the application are started.

SiteKiosk or the SiteKiosk Object Model cannot prevent the user from closing an application that provides the user with options to close it. Therefore we now need the code that monitors the application.

We will use the OnRemove event of the WindowList object. The OnRemove event fires whenever an application window (this means every Window that produces a tab in the Windows task bar) is removed. We assign a function to the OnRemove event, in this case also named OnRemove.

That function receives a parameter that is a WindowInfo object and includes information about the window that has just been closed. We use the ItemText property of that object to check if the window title of the window that has just been closed is from the monitored application. If that is the case our application has just been closed and we need to start it again, for that we call the function we already created that start our application. The code for all this looks as follows:

SiteKiosk.WindowList.OnRemove = OnRemove;

function OnRemove(skwin){
    if(skwin.ItemText === "WindowTitleOfApplicationToWatch"){
        StartMyApp();
    }
}

Depending on the speed of the process to start SiteKiosk and the application at the same time or the time the application needs to fully close, the application may not have the focus or start at all. To prevent this from happening we can add a slight delay to starting the application, you may need to test what the best timing is for your individual application. We add the AddDelayedEvent method of the Scheduler object to our controlapp.js script at all the places we want to start the application:

SiteKiosk.Scheduler.AddDelayedEvent(5000, StartMyApp);

We are done. When we put the parts together the complete code of our script looks like this:

SiteKiosk.WindowList.OnRemove = OnRemove; //fires if a window has been closed
SiteKiosk.Scheduler.AddDelayedEvent(5000, StartMyApp); //starts the desired application the first time after 5000 ms

function StartMyApp(){
    SiteKiosk.ExternalApps.Run("c:\\windows\\notepad.exe", true);
}

function OnRemove(skwin){
    //checks if the application that should run has been closed
    if(skwin.ItemText === "Untitled - Editor"){
        //the application has been closed, restart it again
        SiteKiosk.Scheduler.AddDelayedEvent(500, StartMyApp); //starts the desired application the next time after 500 ms
    }
}

Save the code as controlapp.js (or whatever name you prefer) and make sure to put that file into the ..\SiteKiosk\html\ folder.

Now open the SiteKiosk configuration tool and create a new configuration. Set a password, set the background.html file as your start page and then go to Browser Designs, click on Fullscreen and set SiteKiosk to use the permanent fullscreen mode. Still under Browser Designs click the Advanced button and add the conrolapp.js file as an external script (optional: on the same configuration page tick the option to 'Keep the SiteKiosk main window in the background').

Save the configuraion and test the script.

 

Another possibility is creating an external script that checks if the application EXE process is running in regular intervals.

For this you basically need the following methods:
- AddPeriodicEvent Method: http://www.provisio.com/helpconsole/SiteKiosk%20Object%20Model%20Help/en-US/default.htm?scheduler_addperiodicevent_mth.htm
- IsProcessRunning Method: http://www.provisio.com/helpconsole/SiteKiosk%20Object%20Model%20Help/en-US/default.htm?externalapps_isprocessrunning_mth.htm
- Run Method: http://www.provisio.com/helpconsole/SiteKiosk%20Object%20Model%20Help/en-US/default.htm?externalapps_run_mth.htm

The following example script will check if the “notepad.exe” process is running every 30 seconds (30000 ms).
If it is not running it starts notepad.exe again.

evtid = SiteKiosk.Scheduler.AddPeriodicEvent(30000, checkExecution);

function checkExecution(eventID){
   if (SiteKiosk.ExternalApps.IsProcessRunning("notepad.exe") == false){
    SiteKiosk.ExternalApps.Run("C:/Windows/notepad.exe", true);
    SiteKiosk.Logfile.Notification('Application started');
    }
}

Customizing the Portal Startpage

Of all designs/start pages that come equipped with SiteKiosk, the start page called "Portal Startpage" is one of the most popular ones. The major reason for that certainly is, that it covers a very common use case: the user can choose from a list of topics to proceed to a detail page that shows the relevant information. SiteKiosk users can already configure which links are to be shown, in which order and the corresponding icons as well as a suitable color scheme, background image  and several other options in the configuration program. For many cases this is already all that is needed, but sometimes you might need more control over the layout or visual appearance of the page.

All you need to know to get more control is how to open a file in an editor (for example Notepad), edit some text in it and save it.

The example I want to show here is how to set a solid background color instead of the default gradient background image. The file you need to change in order to accomplish this is located here C:\Program Files\SiteKiosk\Skins\Public\Startpages\Portal (depending on your system or the installation path you've chosen, it can be in a slightly different location) and it's called Start.html.

Before you proceed, as always, I recommend to first make a backup of the files you edit. To do that, select the file in the  Windows Explorer, choose "copy" from the context menu, right click on an empty area and choose "paste" (shortcut for that is CTRL + c for copy and CTRL + v paste).

Now open "Start.html" in a text editor, you can for example use Notepad ++ which is more comfortable or Notepad that comes with Windows. Search the line that starts with the following text and delete the complete line:

<img id="id_Background" ...

You can save the file now and run SiteKiosk to check the result. Notice that if you try to save the file directly under Windows Vista or Windows 7, it won't let you, because the file is located in a sub folder of your program files directory where you need more rights to write a file than the you have in the text editor. To work around this, you can copy the file to a different folder, make the changes and copy back to the original folder. Or you can start the text editor with administrator rights by right-clicking the program and choosing Run as Administrator from the context menu. 

In SiteKiosk you should see the portal startpage with a white background. This is the standard color if nothing else it specified, so if you like white, you are already done. If your page is about nature you might prefer green, then a little bit more has to be done.

Search for the line which starts with: <body, this is the tag that contains all content of this page . Inside this line, find style="..." (the style attribute) which defines the appearance of the page-body. Here you can add the color that should be used for the page-background. An example that sets the background color to green would be:

<body onselectstart="return false;" onload="Init();" style="margin: 0px;background-color: green">

Try not to change anything else from this line, just add background-color: green to the style attribute. This is because the code of this page could change in the next version of SiteKiosk.  Which values can you set for the background color? You can specify color names like above, check for example this page for a list of them: http://www.w3schools.com/html/html_colornames.asp. You can also specify color codes in RGB format, starting with a # (explained for example here http://www.w3schools.com/html/html_colors.asp). 

So now you can change the background color of the Portal Startpage. What else can be done? Everything that can be done in HTML/CSS/JavaScript and with the help of the SiteKiosk object model even more (for example accessing payment devices, browser windows, etc.). Check this blog for more examples in the future. 

Customize the SiteCaster Player in SiteKiosk

SiteKiosk (version 8.0 and higher) offers the possibilty to embed a SiteCaster player into an HTML page. You can then use this page as, for instance, a start page in SiteKiosk. If you only want to play your Digital Signage campaigns as scheduled in full screen, you can simply choose SiteCaster to play full screen in the SiteKiosk configuration tool under Start Page & Browser -> Digital Signage and you are ready to go.

If you want more control over the player, for example play certain campaigns in reaction to an event (like a button click), this is also possible, but requires a small portion of JavaScript in your page. I will describe here as an example how you can build a SiteCaster start page to play a certain campaign whenever the user clicks a button on the page.

First let's have a look at the basic HTML structure of a SiteCaster full screen start page. Please create a file named "SiteCasterCustom.html" and save it to the folder {Program Files}/SiteKiosk/Skins/public/Startpages/SiteCaster/ (the path to {Program File} depends on your installation of Windows). In the SiteKiosk configuration tool, set this file as the start page for SiteKiosk then.

<!DOCTYPE html>
<html>
<head>
</head>
<body scroll=no style="overflow:hidden; margin: 0; border: 0;">
	<object id="player" classid="clsid:719D9061-22DA-4D25-9BB9-116404372496" style="width: 100%;
		height: 100%; background: transparent;">
	</object>
</body>
</html>

This is just a standard HTML page with one object tag in the body (which has some styling to get rid of margins and border). This object tag embeds the SiteCasterPlayer into the page, so this is essential. In order to make some room for our button, we set the height of the object tag to "700px", so on a 720p screen (1280x720) we have 20 pixels left for the button. When we've added the button, the page looks like this:

<!DOCTYPE html>
<html>
<head>
</head>
<body scroll=no style="overflow:hidden; margin: 0; border: 0;">
	<object id="player" classid="clsid:719D9061-22DA-4D25-9BB9-116404372496" style="width: 100%;
		height: 700px; background: transparent;">
	</object>
	<button id=playButton>Play it!</button>
</body>
</html>

This is our markup for this example, now we add a script to achieve the event handling. First we need to load a script that exposes the SiteCaster player functionality in a convenient way. This script in turn requires one other script that should be included before with a script tag.

<!DOCTYPE html>
<html>
...
	<button id="playButton">Play it!</button>
	<script src="../../External/require.js"></script>
	<script>
		require.config({
			baseUrl: "../.."
		});
		require(['Scripts/SiteCaster'],
				function (context, siteCaster) {

					var player = siteCaster.Player();

					player.broadcastLoaded(function () {
						
					});
				});
	</script>
</body>
</html>

At first glance this might seem a bit overly complex, but it is actually quite simple. The SiteCaster script (which has the file name SiteCaster.js) is using an API called RequireJS (http://requirejs.org) to load dependent scripts, so require.js has to be loaded first (this is the first script tag). After that the RequireJS functionality can be used.

RequireJS first needs a base URL to properly resolve the script paths, so we set it by using the require.config function. This base URL must point to the directory where the two folders "Scripts" and "External" reside. Going from the folder where the standard SiteCaster start page is located, this is two levels up (../..). 

Next we can call the require function itself to load our dependent scripts (in this case it is only SiteCaster.js). It excepts as a first argument an array of script paths that should be loaded. Going from the set base URL, the path to SiteCaster.js is "Scripts/SiteCaster". The file extension ".js" must be omitted, otherwise RequireJS will interpret the name differently.

The second argument is a function that will be called when all dependent script have been loaded. The first parameter to this function is a context object which we don't need here. The second is the siteCaster object that we will use.

Now that we have the SiteCaster object, we can ask it to give us a Player object. Since there can be more than one player on the same page, the ID of a specific object tag can be provided as an argument, but in this case we have only one and we let the SiteCaster script find it automatically. One last thing is missing before we can begin to use the player functionality: we have to make sure the player has loaded the active broadcast. So we set a function that is called when this happens with broadcastLoaded.

Inside this last function we now have full control over the SiteCaster player. In this example we want to play a different campaign, whenever the user clicks a button, so we set the onClick function of the button to a new function. Inside this onClick handler function, we need to find a certain campaign of the current broadcast and call play with it. So we call getCampaignItems() to get all campaign items of the currently playing broadcast. We assume here that the broadcast contains a campaign item with the name "ClickCampaign", which we want to play now. 

 

require.config({
			baseUrl: "../.."
		});
		require(['Scripts/SiteCaster'],
				function (context, siteCaster) {

					var player = siteCaster.Player();

					player.broadcastLoaded(function () {
						playButton.onclick = function () {
							var campaignItems = player.getCampaignItems();
							var i = 0;
							for (; i < campaignItems.length; ++i) {
								if (campaignItems[i].Name == "ClickCampaign") {
									player.play(campaignItems[i]);
								}
							}
						}
					});
				});

As you can see, we just loop through all campaign items until we find the one with the correct name and play it. The item will play once and after that the normal schedule will take over again. If you want to play the Campaign multiple times in a row, you have to play it again, when it ends. The code for that would like like this (only the onclick handler):

playButton.onclick = function () {
	var campaignItems = player.getCampaignItems(),
		i = 0,
		playCount = 0,
		clickCampaignItem;

	for (; i < campaignItems.length; ++i) {
		if (campaignItems[i].Name == "ClickCampaign") {
			clickCampaignItem = campaignItems[i];

			player.campaignEnd(function (id) {
				if (id === clickCampaignItem.Id && playCount < 4) {
					player.play(clickCampaignItem);
					playCount += 1;
				}
				else
					player.setAutoSchedule(true);
			});

			player.setAutoSchedule(false);
			player.play(clickCampaignItem);
		}
	}
};

Note that we call player.setAutoSchedule(false) to switch off the scheduled playing of the broadcast. This way we get complete control and scheduled (not disabled) campaigns won't kick in in between. After our click campaign has played four times we call player.setAutoSchedule(true) and campaigns are played according to the set schedule again (the ones that are not disabled). 

The complete HTML file containing the example script is attached to this entry, so if you have SiteKiosk 8 installed and want to try it out, just save it into the folder  {Program Files}\SiteKiosk\Skins\Public\Startpages\SiteCaster and set this as a start page in the SiteKiosk configuration tool. Make sure you create at least two campaigns in your broadcast and disable one of them (the one you want to play when the button is clicked) under "Schedule" in the SiteCaster tab in SiteRemote.

 

SiteCasterCustom.html (1.36 kb)