API: Display HTML & Documents on External Screen

Trigger and control full-screen viewing of several document formats, including .html pages and .pdf, on an external screen or projector.

Requirements

Kiosk Pro Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • Screensaver > External Monitor Mode = Interactive or Standard Mirroring
  • Physical Hardware
    • External screen or projector connected via HDMI to the iPad through a Digital AV Adapter or hub or to a connected Apple TV for wireless Airplay.


Triggers via API Functions

Check Current Background Color

This function checks the current background color or image shown prior to a file being opened or if a file is not proportioned to fit the screen dimensions.

Format
kp_ExternalScreen_getBrowserBgColor(callback);
		
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format
callback(backgroundColor);
		
Callback return values
  • backgroundColor - [string] the background color or image to be shown on the external display prior to a file being opened or if a file does not fill the screen. Can be returned as:
    • R,G,B - the background color set in R,G,B format
    • image file - the file path to the desired background image. If local, this path will be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this will be the full URL

Set New Background Color

This function sets a new background color or image shown prior to a file being opened or if a file is not proportioned to fit the screen dimensions.

Format
kp_ExternalScreen_setBrowserBgColor(backgroundColor, callback);
		
Parameters
  • backgroundColor - [string] the background color or image to be shown on the external display prior to a file being opened or if a file does not fill the screen. Can be set as:
    • R,G,B - [string] the background color set in R,G,B format
    • image file - [string] the file path to the desired background image. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format
callback(success);
		
Callback return values
  • success - [integer] indicating whether the background was successfully updated. Possible values are:
    • 0 - the background was unable to update
    • 1 - the background successfully updated


Open HTML File or PDF

This function opens the HTML file or PDF specified by the 'filePath' parameter on the external display.

If referencing a locally stored file, the file path is relative to the Kiosk Pro documents folder. If referencing a remotely stored file, use the full URL. If the app cannot find the file at the specified path, then the method will fail.

Format
kp_ExternalScreen_openDocument(filePath, сallback);
		
Parameters
  • filePath - [string] the file path to the desired file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format
callback(jobWasAccepted);
		
Callback return values
  • jobWasAccepted - [integer] indicating whether the external display is linked and returned no errors. Possible values are:
    • 0 = indicates an external display is not linked
    • 1 = indicates external display is linked and returned no errors. Note that, even if this returns 1, it is not guaranteed that the external display showed content properly (if, for instance, path to the content was set incorrectly or content does not exist)

Video Within a HTML Player

Although there is nothing to prevent you from using this call to display an HTML file with an embedded video player, we strongly recommended against this as it can lead to inconsistent results. Instead, we recommend using kp_ExternalScreen_playVideo to trigger video playback on the external display directly.


Open Image File

This function displays the specified image on the external screen.

Format
kp_ExternalScreen_showImage(filepath, contentMode, callback);
		
Parameters
  • filepath - [string] file path of the image to be shown. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL
  • contentMode - [integer] indicating how the image should be displayed. Possible values are:
    • 0 = Scale to fill - image will fill the screen. If the image does not match the screen resolution, it will be scaled to fill the screen, and the image may be distorted
    • 1 = Aspect fit - image will fit the screen while maintaining the aspect ratio. If the image does not match the screen resolution, some areas of the screen will be empty
    • 2 = Aspect fill - image will fill the screen. If the image does not match the screen resolution, it will be scaled until the screen is filled while maintaining the aspect ratio
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format
callback(success);
		
Callback return values
  • success - [integer] indicating whether the image was successfully displayed. Possible values are:
    • 0 - specified image failed to be displayed
    • 1 - specified image displayed successfully


Trigger JavaScript

This function triggers another JavaScript call on the HTML page currently displayed on the external screen, which can be used to update content or trigger an action.

Format
kp_ExternalScreen_doJScript(script);
		
Parameters script - [string] the JavaScript function to be called on the page being displayed


Check Number of Pages in PDF

This function triggers a callback returning the number of pages in the PDF document currently being displayed on the external screen.

Format
kp_ExternalScreen_requestNumberOfPdfPages(callback);
		
Parameters callback - [string] the name of the callback to be triggered with the result
Callback format
callback(numberOfPages);
		
Callback return values numberOfPages - [integer] indicating the total number of pages in current PDF document. For other types of documents, this method always returns 0


Check Current Page Number in PDF

This function triggers a callback returning the current page number of the PDF document currently being displayed on the external screen.

Format
kp_ExternalScreen_requestNumberOfCurrentPdfPage(callback);
		
Parameters callback - [string] the name of the callback to be triggered with the result
Callback format
callback(pageNumber);
		
Callback return values pageNumber - [integer] indicating the page number of page being displayed in the current PDF document. For other types of documents, this method always returns 0


Go to Specific Page in PDF

This function triggers navigation to the specified page of the PDF document currently being displayed on the external screen. For other types of documents, this method does nothing.

Format
kp_ExternalScreen_showPdfPage(pageNumber, callback);
		
Parameters
  • pageNumber - [integer] indicating the number of the page which should be shown. Should belong to the set [1..N] where N = max page number (which can be queried using kp_ExternalScreen_requestNumberOfPdfPages
  • callback - [string] the name of the callback to be triggered with the result
Callback format
callback(success);
		
Callback return values
  • success - [integer] indicating whether the navigation was successfully. Possible values are:
    • 0 - specified page was not shown
    • 1 - navigated to the specified page successfully


Notifications via API Callbacks

When File is Opened Successfully

This callback is triggered when a request to open a document on the external screen is called and the document opens successfully.

Format
kp_ExternalScreen_didOpenFileSuccessfully(sourceDocumentPath, usedDocumentPath);
		
Return Values
  • sourceDocumentPath - [string] the filepath passed to Kiosk Pro to open
  • usedDocumentPath - [string] the filepath Kiosk Pro used to access the file. For example, if a user sets a path to a local PDF that doesn't exist Kiosk Pro will transform it to a remote URL by adding 'http://'


When File Fails to Open

This callback is triggered when a request to open a file on the external screen is called and the document fails to load.

Format
kp_ExternalScreen_didOpenFileWithError(sourceDocumentPath, usedDocumentPath, error);
		
Return Values
  • sourceDocumentPath - [string] the filepath passed to Kiosk Pro to open
  • usedDocumentPath - [string] the filepath Kiosk Pro used to access the file. For example, if a user sets a path to a local PDF that doesn't exist Kiosk Pro will transform it to a remote URL by adding 'http://'
  • error - returned as an associative array: {‘domain’:value, ‘code’:value, ‘description’:value, 'failureReason':value, 'recoverySuggestion':value, 'debugDescription':value}
    • domain - [string] representing where the error occurred
    • code - [string] the identifier for the error
    • description - [string] a brief description of the error
    • failureReason - [string, optional, may return as empty] the reason for the error
    • recoverySuggestion - [string, optional, may return as empty] the suggested solution
    • debugDescription - [string, optional, may return as empty] a detailed description of the error


Sample Code

  • This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
  • To run sample code, set the app's homepage to kioskgroup.com/external-screen-api
  • To download a .zip of sample code, click here.

Change Log

  • Added in initial version of Enterprise. Major revision of underlying code base in version 7.3.

Still stuck? How can we help? How can we help?