NOW LOADING

Widget SDK

Overview

This document describes the Signagelive Widget SDK methods available and their purpose. Currently the SDK has not been rolled out on all devices so some features are limited to: Samsung, LG, Chrome OS or Brightsign players only.

The SDK is available here.

Include the Javascript File

Copy the javascript file into your project and include it in your HTML page as shown in the example below:

<script src="js/signagelive.js"></script>

Methods

Signagelive.sendReadyToDisplay()

   
Description To be used to signal when the player has downloaded the data and assets within the widget and is ready for the content to be shown on screen.
By default the media player will automatically show the widget after 2 seconds as this method will not allow it to be delayed further.
Parameters n/a
Github Repository
Example  
Signagelive.sendReadyToDisplay().then(function() {
    console.log('Widget is displayed...');
});

Signagelive.setData(key, value, shared)

   
Description A localStorage alternative; where data can be stored on the player and can persist between reloading the widget.
Parameters key (string) - The name/reference for the data being stored.
value (string) - The data that is going to be stored.
shared (boolean) - If set to true then data will be accessible to all widgets published to the player.
Github Repository
Example  
Signagelive.setData('status', data, true).then(function () {
    console.log("Data stored as 'status'");
});

Signagelive.listStoredDataKeys(shared)

   
Description Get a list of all keys that have been stored using Signagelive.setData()
Parameters shared (boolean) - Whether or not to include keys stored in the shared storage space.
Returns A promise that resolves an array of stored keys. Example response: [“items”, “names”, “places”]
Github Repository
Example  
Signagelive.listStoredDataKeys(false).then(function(data) {
    console.log(data);
}).catch(function(error) {
    console.error(error.message);
});

Signagelive.getData(key, shared)

   
Description A localStorage alternative; where data stored with Signagelive.setData(key, value, shared) can be retrieved.
Parameters key (string) - The name/reference for the previously stored data.
shared (boolean) - If set to true, it will search for this key in the global storage of the player.
Github Repository
Example  
Signagelive.getData('status', true).then(function (data) {
    self.dataResponse = JSON.parse(data);
});

Signagelive.removeData(key, shared)

   
Description Remove a key-value pair stored using Signagelive.setData()
Parameters key (string) - The key of the key-value pair to remove.
shared (boolean) - Whether or not the key is a shared key or not.
Returns A promise that resolves when the requested key has been removed.
Github Repository
Example  
Signagelive.removeData('items', false)
    .then(function() {
        console.log('items key-value pair removed');
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.clearStorage()

   
Description Remove all key-value pairs stored using Signagelive.setData()
Parameters n/a
Github Repository
Example  
Signagelive.clearStorage()

Signagelive.log(logLevel, message)

   
Description Ability to log universally across all media players
Parameters logLevel (string) - The options are [DEBUG, INFO, WARNING, ERROR, FATAL] (Optional - default is INFO).
message (string) - The message to log.
Returns Returns a promise that resolves once the message has been logged.
Github Repository
Example  
Signagelive.log('ERROR', 'Unable to load items from data storage.')
    .then(function() {
        // Logged
    });

Signagelive.playVideo()

   
Description Used to play video natively on Samsung SSP Tizen displays. Native playback can offer a better visual experience over standard HTML5 video when used in a playlist with other videos and when wanted to render 2 videos with video concurrently.
Parameters fileURI(s) - a relative URI or array of relative URIs pointing to video files to play (relative to index.html).
x - the x coordinate of the video relative to the zone. If you want the video to cover the entire widget zone then this should be 0.
y - the y coordinate of the video relative to the zone. If you want the video to cover the entire widget zone then this should be 0.
width - the width of the video. If this is larger than the width of the widget zone, this will be scaled down to fit the zone.
height - the height of the video. If this is larger than the height of the widget zone this will be scaled down to fit the zone.
loop - whether or not to loop the video(s) - This will be true by default.
play4K - if playing a 4k video this must be true.
callbacks - pass in functions to be called when specific events fire.

The exact events you can add listeners for are:
onTimeUpdate - use this to receive the current play time of the video.
onComplete - fired when a video completes.
onError - fired when there is a playback error.
Limitations Your widget must have a transparent background in order for video to be visible. Only 1 video can be played per widget at any one time.
You can play up to 2 widget zones each with 1 video concurrently @ FHD resolution If playing 4K only 1 video can be played at a time (across all widgets).
Videos should not be larger than the widget zone they are scheduled to. Videos that are larger than the widget zone will be scaled down to fit the zone.
Github Repository
Example  
style.css
 
html {
    background-color: transparent !important;
}
 
main.js
 
    // Use the new playVideo() SDK API to play a single video
    Signagelive.playVideo(
        'content/1.mp4',        // File to play (relative to index.html)
        0,                      // x pos
        0,                      // y pos
        1920,                   // width
        1080,                   // height
        true,                   // loop video
        false,                  // 4k video (supported screens only)
        // Video events
        { 
            onTimeUpdate: onVideoTimeUpdate,
            onComplete: onVideoComplete,
            onError: onVideoError
        }
    ).then(function(success) {
        // Was playback successful?
        success
            ? console.log('Video playback started successfully.')
            : console.error('Video playback failed.');
    });
 
    function onVideoTimeUpdate(video, currentTime) {
        var message = 'Video Time Update: ' + currentTime;
    }
 
    function onVideoComplete(video) {
        var message = 'Video Complete';
        console.log(message);
    }
 
    function onVideoError(video, errorMessage) {
        var message = 'Video Error: ' + errorMessage;
        console.error(message);
    }
 
var videoPlaylist = [
        'content/1.mp4',
        'content/2.mp4',
        'content/3.mp4',
    ];
    // Use the new playVideo() SDK API to play a playlist of videos
    Signagelive.playVideo(
        videoPlaylist,          // Array of video files to play (relative to index.html)
        0,                      // x pos
        0,                      // y pos
        1920,                   // width
        1080,                   // height
        true,                   // loop video
        false,                  // 4k video (supported screens only)
        // Video events
        { 
            onTimeUpdate: onVideoTimeUpdate,
            onComplete: onVideoComplete,
            onError: onVideoError
        }
    ).then(function(success) {
        // Was playback successful?
        success
            ? console.log('Video playback started successfully.')
            : console.error('Video playback failed.');
    });
 
    function onVideoTimeUpdate(video, currentTime) {
        var message = 'Video Time Update: ' + currentTime;
        document.getElementById('eventText').textContent = message;
    }
 
    function onVideoComplete(video) {
        var message = 'Video Complete';
        console.log(message);
        document.getElementById('eventText').textContent = message;
    }
 
    function onVideoError(video, errorMessage) {
        var message = 'Video Error: ' + errorMessage;
        console.error(message);
        document.getElementById('eventText').textContent = message;
    }

Signagelive.stopVideo()

   
Description Used to stop a video that is currently playing as a result of a call to Signagelive.playVideo()
Parameters None
Limitations None
Github Repository
Example  
Signagelive.stopVideo().then(function(success) {
    success
        ? console.log('Video stopped.')
        : console.error('An error occurred stopping the video.');
}); 

Signagelive.getPlayerDetails()

   
Description Get details about the player the widget is playing on including Signagelive serial number, site details, model details, and firmware and client information.
Parameters None
Returns A promise that resolves to a JSON object containing all of the player details. Example:
{
    "serial_number": 12345,
    "client_id": "4A:38:95:01:23:54",
    "site_description": "Player 1",
    "address_1": "123 Bond Street",
    "address_2": "",
    "city": "London",
    "state": "London",
    "zip_code": "E17 8BB",
    "reference_code_1": "Ref 1",
    "reference_code_2": "Ref 2",
    "reference_code_3": "Ref 3",
    "time_zone": "Europe/London",
    "utc_offset": 0,
    "player_type": "Tizen",
    "manufacturer": "Samsung",
    "model": "PMF",
    "client_version": "1.15",
    "firmware_version": "T-HKMLAC-2100.2"
}
Github Repository
Example  
Signagelive.getPlayerDetails()
    .then(function(playerDetails) {
        console.log(JSON.stringify(playerDetails, undefined, 2));
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.getDisplayProperties()

   
  Signagelive.getDisplayProperties()
Description Get player display properties such as display width and height, rotation and whether or not video rotation is supported.
Parameters None
Returns A promise that resolves to a JSON object containing all of the display properties. Example:
{
    "width": 1920,
    "height": 1080,
    "rotation": 270,
    "is_native_portrait_app": false,
    "video_rotation_supported": true,
}
Github Repository
Example  
Signagelive.getDisplayProperties()
    .then(function(displayProperties) {
        console.log(JSON.stringify(displayProperties, undefined, 2));
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.getMaxSupportedTLSVersion()

   
Description Get detailed information about the TLS (SSL) support of the player.
Parameters None
Returns A promise that resolves to a JSON object with TLS support details. The following example shows how the response should look if we are able to get detailed data from the howsmyssl.com API.
Note that if the detailed data is available, the detailed_tls_settings_included property will be true and detailed_tls_settings will be populated.
{
    "tls_version_string": "TLS 1.3",
    "tls_version": 1.3,
    "detailed_tls_settings_included": true,
    "detailed_tls_settings": {
        "given_cipher_suites": [
            "TLS_AES_128_GCM_SHA256",
            "TLS_AES_256_GCM_SHA384",
            "TLS_CHACHA20_POLY1305_SHA256",
            "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
            "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
            "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
            "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
            "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
            "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
            "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
            "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
            "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
            "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
            "TLS_RSA_WITH_AES_128_GCM_SHA256",
            "TLS_RSA_WITH_AES_256_GCM_SHA384",
            "TLS_RSA_WITH_AES_128_CBC_SHA",
            "TLS_RSA_WITH_AES_256_CBC_SHA",
            "TLS_RSA_WITH_3DES_EDE_CBC_SHA"
        ],
        "ephemeral_keys_supported": true,
        "session_ticket_supported": true,
        "tls_compression_supported": false,
        "unknown_cipher_suite_supported": false,
        "beast_vuln": false,
        "able_to_detect_n_minus_one_splitting": false,
        "insecure_cipher_suites": {}
    }
}

If howsmyssl is unavailable and the media player has to return the default tls settings only then the detailed_tls_settings_included property will be false and detailed_tls_settings object will be null.

{
    "tls_version_string": "TLS 1.2",
    "tls_version": 1.2,
    "detailed_tls_settings_included": false,
    "detailed_tls_settings": null
}
Github Repository
Example  
Signagelive.getMaxSupportedTLSVersion()
    .then(function(maxSupportedTLSVersion) {
        console.log(JSON.stringify(maxSupportedTLSVersion, undefined, 2));
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.getOnlineStatus()

   
Description Find out if the player has a network connection and is connected to the internet.
Parameters None
Returns A promise that resolves to a JSON object with network and internet connectivity status.
The response object contains two boolean values that can be used to determine if the player is connected to a LAN and whether or not it has internet access. Example:
{
    "network_connected": true,
    "internet_access": true
}
Github Repository
Example  
Signagelive.getOnlineStatus()
    .then(function(status) {
        console.log(JSON.stringify(status, undefined, 2));
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.onWidgetClosing(callback, options)

   
Description Register a callback that will get called when the widget is to be closed because the media player is moving to the next asset.Note that if the widget does not register a callback using this function then the media player will forcibly close the widget and move next as normal.
Parameters function callback(Promise resolve, timeInfo) - A reference to a function or anonymous function that will be executed when the Signagelive media player notifies the widget that the widget is about to close.
The callback function will have 2 parameters.
The first is a reference to resolve the promise and notify the media player that the cleanup code has finished executing.

The widget developer should always call resolve() after their cleanup code has executed.
The second parameter timeInfo provides details about the timing until the widget will be closed, which is dependent on the configuration options provided to the initial call.
The timeInfo parameter object has the following properties: millisecondsNotifiedInAdvance millisecondsUntilClosed millisecondsUntilForciblyClosed options - (optional) An optional options object.
Configurable options include:
millisecondsToNotifyInAdvance - This is the time in milliseconds that the callback is called in advance of the Widget being closed. Default: 500ms, Max: 2000ms.
millisecondsToWaitForCallbackResolution - This is the time in milliseconds that the media player will wait for the callback method to call resolve() before forcibly closing the widget and moving to the next asset. Default: 500ms, Max: 2000ms.
Returns N/A
Github Repository
Example  
Signagelive.onWidgetClosing(function(resolve, timeInfo) {
    console.log('Widget closing in ' + timeInfo.millisecondsUntilForciblyClosed + 'ms. Getting current state...');
    getCurrentState()
        .then(function(state) {
            console.log('Storing state...');
            return storeCurrentState(state);
        })
        .then(function() {
            console.log('Stopping video player...');
            return stopVideoPlayer();   
        })
        .then(function() {
            console.log('Hiding background...');
            return hideBackground();
        })
        .then(function() {
            console.log('Clean up code completed. Notifying media player.');
            resolve(); // Always call resolve()
        })
        .catch(function(err) {
            console.error('An unexpected error occurred.');
            resolve(); // Always call resolve()
        })
}, {
    millisecondsToNotifyInAdvance: 500,
    millisecondsToWaitForCallbackResolution: 500
});

Signagelive.checkSupportedHTML5Features(featuresToCheck)

   
Description Check HTML5 feature support on the player using Modernizr.
Parameters featuresToCheck - (Array of strings) representing the features to check.
The full list of available features to check are defined in the Modernizr documentation.
Returns A promise that resolves to a JSON object that contains results for the features that were requested to be tested. Each feature that was tested will be returned as a boolean property of the results object with the feature name and “_supported” appended to it (see example below). Example response:
{
    "cssanimations_supported": true,
    "flexbox_supported": false,
    "es6collections_supported": false,
    "arrow_supported": false
}
Github Repository
Example  
Signagelive.checkSupportedHTML5Features(['cssanimations', 'flexbox', 'es6collections', 'arrow'])
    .then(function(results) {
        console.log(JSON.stringify(results, undefined, 2));
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.requestMediaPlayerMoveToNextAsset()

   
Description Request the player to move to the next media asset available in the playlist.
Parameters n/a
Github Repository
Example  
Signagelive.requestMediaPlayerMoveToNextAsset()

Signagelive.downloadFile(fileUrl, localFileName, location)

     
Description This method allows the developer to specify a file URL (https) so the media player can download the contents to the filesystem. Before downloading any file a check will be done to ensure there is sufficient space to download the file.  
Parameters fileUrl - the URL to the remote file to download (Required).
localFileName - the name of the file when saved locally (Optional - if not specified will use the remote file name).
location - the location to download the file.

Supported options are: private|shared|any (Optional - if not specified the default location is private).
 
Returns The promise resolves when this has been completed. On Success the promise will resolve and include the playURL of the downloaded file On Error the promise will reject and include the error object with an error reason  
Example    
Signagelive.downloadFile('https://mycontent.signagelive.com/18e23fa6-287a-4a13-9579-4bf8e0babdce.mp4', 'video-1.mp4', Signagelive.FileStorageLocation.SHARED)
    .then(function(filePath) {
        console.log(`File successfully downloaded and stored to the filesystem. To play this this use this: ${filePath}`);
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.getDownloadedFile(filename, location)

     
Description This method allows a filesystem URL to be returned based on the filename that was originally downloaded and stored.  
Parameters filename - the local file name of the file that is trying to be retrieved from the filesystem (Required).
location - the location to look for the downloaded file.

Supported options are: private|shared|any (Optional - default if not specified is private).
 
Returns The promise resolves when this has been completed with the appropriate filesystem URL. Or an error object with an error message on failure (for example file not found).  
Example    
Signagelive.getDownloadedFile('video-1.mp4', Signagelive.FileStorageLocation.SHARED)
    .then(function(filePath) {
        console.log(`File successfully retrieved and is available at: ${filePath}`);
        // e.g. continue with success callback and do something with the retrieved file
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.listDownloadedFiles(location)

     
Description This method lists all the downloaded files available in the local filesystem.  
Parameters location - the location to look for the downloaded files.

Supported options are: private|shared|any (Optional - default if not specified is private).
 
Returns The promise resolves when this has been completed with the appropriate list of filesystem URLs.  
Example    
Signagelive.listDownloadedFiles(Signagelive.FileStorageLocation.SHARED)
    .then(function(downloadedFiles) {
        console.log(downloadedFiles);
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.removeDownloadedFile(filename, location)

     
Description This method will remove the specified file from the local filesystem.  
Parameters filename - the local file name of the file to be removed from the filesystem (Required).
location - the storage location of the file.

Supported options are: private|shared|any (Optional - default if not specified is private).
 
Returns The promise resolves on success or is rejected with an error on failure.  
Example    
Signagelive.removeDownloadedFile('video-1.mp4', Signagelive.FileStorageLocation.SHARED)
    .then(function() {
        console.log('File successfully deleted');
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.clearDownloadedFiles(location)

     
Description This method removes all the downloaded files from the local filesystem. Only files downloaded by this widget will be removed from the shared location.  
Parameters location - the storage location of the file.

Supported options are: private|shared|any
 
Returns The promise resolves on success with an array of removed files. On error it is rejected with an error object and error message.  
Example    
Signagelive.clearDownloadedFiles(Signagelive.FileStorageLocation.PRIVATE)
    .then(function(removedFiles) {
       console.log(`Successfully deleted: ${removedFiles.length}`);
    })
    .catch(function(error) {
        console.error(error.message);
    });

Signagelive.getExternalData(dataSource, integrationId, objectId, callback)

   
Description Gets data (or files) from an external data source.
Parameters dataSource - The source of the data. Currently “DSS” will be the only option here.
integrationId - The public Id of the integration, such as com.signagelive.datasyncservices.authenticatedwebsites
objectId - the id of the integration object as defined in the Widget preferences.
onDataUpdate - a reference to a callback function that will be fired when new data for this data source is available.
Returns A promise that resolves to a JSON object containing the requested data.
The actual fields and data returned will be very different for each integration.

Developers will need to read the documentation specific to the integration they are using to understand what they can expect to be returned.
The example below shows data that might be returned for a corporate dashboard web page made available by the authenticated websites integration.

Example: { “webpage”: { “id”: { “id”: “85c91571-a47d-471c-a845-7f9748301dd9” }, “name”: “Corporate Dashboard 1”, “latestSuccessfulCaptureTimestamp”: “2021-03-19T10:00:00”, “latestSuccessfulCapture”: { “name”: “file1”, “src”: “/com.signagelive.datasyncservices.authenticatedwebites/Corporate_Dashboard_1.jpg” } } }
Example  
function onDashboardUpdated(data) {
    console.log('Dashboard Updated: ' + JSON.stringify(data, undefined, 2));
    $("#dashboard-img").attr('src', data.webpage.latestSuccessfulCapture.url);
    $("#last-updated-time").html(data.webpage.latestSuccessfulCaptureTimestamp);
}

window.addEventListener('widget-init', function (e) {
    // Load dashboard values from Widget preferences
    var cytheDashboardId = Widget.preferences.getItem("Cythe");
    // Get Data and Render
    Signagelive.getExternalData("DSS", "com.signagelive.datasyncservices.authenticatedwebsites", cytheDashboardId, onDashboardUpdated).then(function(data) {
        onDashboardUpdated(data);
    }).catch(function(error) {
        console.error('Error getting data: ' + error);
    });
});

Supported Devices

  Brightsign
(Series 3, 4 & 5)
LG webOS
(1.0, 2.0, 3.0, 3.2, 4.0, 4.1 & 6.0)
Samsung SSSP
(D & E)
Samsung Tizen
(2.4, 3.0, 4.0 & 6.0)
Sony Android
(All Models)
Philips Android
(All Models)
Amazon Fire TV Windows Chrome OS IAdea SMIL
(All)
Browser/Broadcast Player Legacy PC Client
Main Widget SDK Support                        
Signagelive.setData(key, val, shared)
Signagelive.listStoredDataKeys(shared)
Signagelive.getData(key, shared)
Signagelive.removeData(key, shared)
Signagelive.clearStorage()
Signagelive.log(message)
Signagelive.sendReadyToDisplay()
Signagelive.playVideo() Coming soon Coming soon
Signagelive.stopVideo() Coming soon Coming soon
Signagelive.getPlayerDetails()
Signagelive.getDisplayProperties()
Signagelive.getTLSSupportInfo()
Signagelive.getOnlineStatus()
Signagelive.onWidgetClosing(callback)
Signagelive.checkSupportedHTML5Features(featuresToCheck)
Signagelive.requestMediaPlayerMoveToNextAsset()
Signagelive.downloadFile()
Signagelive.getDownloadedFile()
Signagelive.listDownloadedFiles()
Signagelive.removeDownloadedFile()
Signagelive.clearDownloadedFiles()
Data Sync Services Support                        
Signagelive.getExternalData(dataSource, integrationId, objectId, callback)