Dashboard SDK

enplug.account

All methods take a success and an error callback as the final two parameters. For methods which load data, the success callback will be passed the data as the first and only parameter. The error callback is given the reason (string) an SDK method failed.

.getUser(onSuccess, onError)

Loads all information for the current user.

Callback receives:

{
  id: 'string',             // User id in the system
  accountId: 'string'       // Current user's account ID
  type: 'string',           // User access type
  data: {
      email: 'string',      // User email
      firstName: 'string',  // User name
      accountName: 'string',// User account name
  },
  has: {
      rootAccess: true,     // boolean true/false
      limitedAccess: true,  // boolean true/false
  }
}

.getDisplays(onSuccess, onError)

Loads information for the currently selected display group(s). In the account context it will return all Display Groups in the account, in the Display Group context will return only this groups information.

Callback receives:

{
  language: 'string', // e.g. English, Russian, French
  orientation: 'string', // Landscape or Portrait
  timezone: 'string',
}

.getSelectedDisplayId(onSuccess, onError)

Returns the currently selected display group Id or null if in the Account view.

.getAssets(onSuccess, onError)

Loads an array of assets for the current app instance.

Callback receives:

[{
  Created: 'string',    // WCF date
  Id: 'string',         // Asset ID
  Value: {},            // Value object provided when created
  VenueIds: [],         // Array of Ids of Display Groups this asset is currently deployed to
  ThemeId: 'string'     // Optional Theme Id if set
}]

.saveAsset(asset, dialogOptions, onSuccess, onError)

Creates or updates an asset. If asset.Id is null it will create a new asset, otherwise it will update the existing one.

  • asset: object to update the asset’s value 
  • dialogOptions: DeployDialog options, object specifying one or more options below such as showing scheduling and duration options.

{
  showSchedule: true,               // false by default
  scheduleOptions: {                // option to show duration slider when showDuration is set to true 
    showDuration: true,             // allow user to choose the duration of each asset shown on player 
  },  initialTab: 'displays',           // by default, other option is 'schedule'  successMessage: 'Saved config',   // Message to show when the save is successful  loadingMessage: 'Saving...',      // Message to show while the save call is in progress  showDeployDialog: true            // To force showing the DeployDialog when updating existing asset,                                    // it will be always shown when saving a new asset irrespective of this option }

.deleteAsset(id, onSuccess, onError)

Deletes one or many assets under the current app instance.

  • id: id of the asset to delete or array of ids

enplug.dashboard

All enplug.dashboard methods also accept success and error callbacks which acknowledge when a certain UI control has been triggered, but they aren’t usually needed so they’re left out of the documentation except in cases where they’re used.

.setHeaderTitle(title)

Sets the last part of the title bar breadcrumb. Set an empty title ’’ to clear the title.

Screenshot
.

.setHeaderButtons(buttons|button)

Sets the primary action buttons for a page in the titlebar. Accepts either a single button object, or an array of buttons. Each button must have a button.action callback.
button:

{
  text: 'button text',
  class: 'class-name',
  action: function () {}, // callback when clicked
  disabled: true, // boolean true/false
}

Screenshot

.pageLoading(boolean)

Controls the loading state for the entire page. Every application starts off in loading state, and must set pageLoading(false) to notify the dashboard that it has successfully loaded.

Use enplug.dashboard.isLoading() to synchronously check current loading state.

Screenshot

.isLoading()

Synchronously returns the current loading state.

Note: The loading state is updated asynchronously when this sender receives an acknowledgement of successful SDK call from the dashboard after using .pageLoading(bool);

.pageError()

Puts the page into error state.

Screenshot

.pageNotFound()

Puts the page into 404 state.

Screenshot

.loadingIndicator(message)

Turns on the progress indicator, typically used during asynchronous actions.

Note that the progress indicator will continue until a call is made to the errorIndicator or successIndicator APIs.

Screenshot

.successIndicator(message)

Shows the success indicator. Should only be used after a call has been made to .loadingIndicator().

Screenshot

.errorIndicator(message)

Shows the error indicator. Should only be used after a call has been made to .loadingIndicator().

Screenshot

.openConfirm(options, onSuccess, onError)

Opens a confirm window with Yes/No buttons and configurable messages. If the user clicks the Confirm button, the success callback is called. Otherwise the error callback is called.

Available options:

{
  title: 'string', // required
  text: 'string', // required
  confirmText: 'string', // optional, defaults to "Confirm"
  cancelText: 'string', // optional, defaults to "Cancel"
  confirmClass: 'string', // optional, defaults to primary button. Other option: 'btn-danger'
}

Screenshot

.confirmUnsavedChanges(onSuccess, onError)

Opens a confirm window asking the user to confirm their unsaved changes. If the user clicks the confirm button, the success callback is called. Otherwise the error callback is called.

Screenshot

.upload(options, onSuccess, onError)

Opens an upload interface for the user to select a file to upload. The options parameter is currently unused. The success callback receives the newly uploaded and encoded file wrapped in an array:

[{
  url: 'string', // publicly accessible URL for the encoded file
  filename: 'string', // filename of the uploaded file
  mimetype: 'string', // mimetype of the uploaded file
  size: 1000 // the size of the uploaded file in bytes, if available
}]

Screenshot

Display SDK

Events

The Event API for Player Apps has methods for adding and removing event handlers. Events include system events as well as custom app events generated via push notifications. The JavaScript Player SDK has a few events that are fired during specific moments of the application life-cycle. Below you can find the various events and what to expect to be passed to the event handler.

‘destroy’ Event

The “destroy” event is fired anytime the application is going to be disposed by the player. When developing a player application with the JavaScript SDK you should be prepared for your app to destroyed anytime it is taken off of the display. The player will fire the “destroy” event and then wait for a small amount of time to allow you to do any cleanup. To notify the player you are done with any final processes a callback is passed to the event handler. If you do not call the callback, your app will still be removed once the allotted cleanup time has passed. Every JavaScript Player application should attach a handler, if only to call the done callback.

enplug.on( 'destroy', function( done ) {
  // maybe save some state information
  localStorage.setItem( 'last-viewed', view.id );
  done(); // ok! I'm ready to be destroyed...
});

enplug.on( eventName, handler ) : undefined

The on function can be used to attach a new handler for a specific event by that event’s name. If you wish to remove this event handler at any time you will need to keep a reference to the handler function and pass it into the off function (described below).

  • eventName: The name of the event the handler should be bound to.
  • handler: The function to handle incoming events of type “eventName”.

enplug.off( eventName, handler ) : undefined

The off function is used to remove existing event handlers. It is important to note that a reference to the original event handler must be passed to off for the handler to be removed.

  • eventName: The name of the event this handler is bound to.
  • handler: The original function bound to the event.

enplug.once( eventName, handler ) : undefined

The once function is a connivence function for adding an event handler that gets automatically removed after the first time it is fired. The code below is the functional equivalent of the once function’s functionality.

function handler( eventData ) {
  enplug.off( 'my-event', handler );
}
enplug.on( 'my-event', handler );

Notifications

The notifications API is for launching alerts to the Enplug Player. You may have noticed these types of alerts created by the Enplug Social App when new posts are received by the Player. A notification consists of an icon and a message. It is important to note that if the user has disabled alerts for their display your notifications will be automatically suppressed by the Enplug Player.

enplug.notifications.post( message ) : Promise<NotificationId>

The post function will take a single argument, the message to display. The message should be as simple as possible to keep the notification short and sweet. The icon used when registering the application in the Enplug App Store will be used as the icon for the notification.

  • **message:** The message to display in the notification.

Application Status

The App Status API is for telling the player what state your application is currently in. Most of these functions relate to the application’s life-cycle.

enplug.appStatus.start() : Promise<Boolean>

When an app is first started by the Enplug Player it will not be shown on screen until it explicitly tells the player that it is ready to be rendered. Note that initially apps are loaded off screen so they can be given time to properly initialize. When you have set up your application and are ready to be shown on the Enplug Player call the start function to be entered into the current rotation of active Player Applications.
Returns a Promise that resolves to true if the operation has completed successfully.

enplug.appStatus.error() : Promise<Boolean>

It is important to notify the player if your application has reached an unresolvable error. Calling the error function will notify the Enplug Player that your application is not operating properly and should be removed from the current rotation of Player Applications. Calling error will typically end up with your application being disposed and destroyed from working memory.
Returns a Promise that resolves to true if the operation has completed successfully.

enplug.appStatus.hide() : Promise<Boolean>

If ever you want to immediately hide your application the hide function can be called to do so. Calling this function will hide your application until it comes up in the normal application rotation cycle. If you app is the only app playing on the display it will not be hidden.
A Promise that resolves to true when the app has been hidden from the screen.

enplug.appStatus.setCanInterrupt( boolean ) : Promise

Sometimes your app will be displaying a video or some other content that should not be interrupted. If you wish to stop the Enplug Player from replacing your app on screen use the canInterrupt property and setCanInterrupt function of the enplug.appStatus object. The canInterrupt property is returned as a promise resolving to a boolean value. The setCanInterrupt function takes the new boolean value and returns a Promise resolving to the new value. It is safe to assume that this value takes hold as soon as it is set. Typically you will only set the value when needed.

myVideo.addEventListener( 'play', function( playEvent ) {
  enplug.appStatus.setCanInterrupt( false ); // returns a Promise
});
myVideo.addEventListener( 'ended', function( endEvent ) {
  enplug.appStatus.setCanInterrupt( true ); // returns a Promise
});
myVideo.play();

enplug.appStatus.canInterrupt: Promise<Boolean>

Checks the current state of canInterrupt property. Returns promise resolving to true if the app had requested not to be interrupted and false otherwise.

enplug.appStatus.canInterrupt.then(function( canInterrupt ) {
  // here the value of canInterrupt will be true or false
  // depending on the previously set value
  // this value always initializes as true
});

Assets

The Asset API for Enplug Player is the way to get assets previously created by Dashboard API.

enplug.assets.getList() : Promise<Array<Object>>

The getList function can be called to return an Array of all assets configured for given player.
Returns a Promise that resolves to an Array of asset value objects.

enplug.assets.getNext() : Promise<Object>

Iterates through the list of asset values defined in the Dashboard part of your application for this display. Each time when called will get the next asset in the list of assets.
Returns a promise that resolves to the single asset value (an Object).

Settings

The Settings API can be used to retrieve various settings that were set by the user of the Enplug Player your application is currently playing on.

.enplug.settings.is4k {Promise<Boolean>}

This Promise property can be checked to know if the Enplug Player is connected to a 4K display so you can update your application accordingly, possibly with high resolution graphics or different font settings, etc.

enplug.settings.is4K.then(function( is4K ) {
  // is4K will be:
  //   true when connected to a 4K display
  //   false when connected to a non-4K display
});

.enplug.settings.transitionType {Promise<String>}

This Promise property will resolve to a String value as listed in the code sample below. This value can be referenced if you wish to match the animations used by the Enplug Player to transition between applications.

enplug.settings.transitionType.then(function( type ) {
  // type will be a string and one of the following
  //  'SLIDE_LEFT'
  //  'SLIDE_RIGHT'
  //  'SLIDE_DOWN'
  //  'SLIDE_UP'
  //  'FADE'
  //  'NONE'
});

.enplug.settings.whitelabel {Promise<String>}

Many Enplug apps show a small white label overlay at the bottom of the display. This can be customized for certain users. This property can be checked to get the value of the white label as set for given Enplug Player.

enplug.settings.whitelabel.then(function( value ) {
  // here value will be a string representing the white label for this display
});

Play Recorder

The Play Recorder API can be used to record how long a particular screen was shown on a display. An example would be recording how long an advertisement was displayed on screen to properly pay the screen provider.

.enplug.playRecorder.report( referenceId, playDuration[, additionalInfo ])

The report function can be used to record the time that an item was displayed. The reference id is used to identify the item for which you are reporting. The play duration is a Number value representing the number of seconds the item was displayed. If you wish to store some additional information, it can be passed as a string as an optional third argument to the report function.

  • referenceId: A unique identifier to track which asset we are recording a play time for.
  • playDuration: A time in seconds that represents how long this item was displayed.
  • additionalInfo: A optional string of extra information to be saved with the recorded value.