">

Dashboard SDK

enplug.account

All methods take a success and an error callback as the final two parameters. For methods that 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, it will return only this group’s information.

Callback receives:

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

.setDisplaySelectorVisibility(boolean)

Shows (true) or hides (false) the display selector dropdown in the upper left corner by the app's header title on dashboard. 

The display selector dropdown can be used to filter assets currently deployed to a specific display group.  You can view all the saved assets by account for your app by selecting the 'Library' view from the dropdown on the upper left.

enplug.dashboard.setDisplaySelectorVisibility(boolean);

.getSelectedDisplayId(onSuccess, onError)

Returns the currently selected display group Id or null if in the Account view. The dropdown is shown in the upper left next to the app's header.

.setDisplaySelectorCallback(callback, onError)

This method invokes a callback when a display group or "Library" is selected from the display selector dropdown. For example, you can use the callback to reload your assets each time it is updated.

enplug.dashboard.setDisplaySelectorCallback(function(){
    // reload assets after a display group or "Library" has been selected
  reloadAssets()
});

.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.

When saving assets, you will have the ability to set additional scheduling options through the deploy dialog, which will render before saving an asset. You can render the deploy dialog and certain customizations by passing the dialogOptions as an argument outline below.

  • 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
 noDialog: false,               // hides dialog when set to true
   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 }

If showDuration is set to true on the dialogOptions, the deploy dialog will show the duration slider and allow a user to enter in a custom duration. If a fixed duration is not set, you will need to force your app to be removed offscreen by calling enplug.appStatus.hide(); in the player portion of your app. This is further discussed in the Application Status section of the player API.

.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 callback, 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.

.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 an action callback. 

button:

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

.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.

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

.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.

.pageNotFound()

Puts the page into 404 state.

.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.

.successIndicator(message)

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

.errorIndicator(message)

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

.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'
}

.confirmUnsavedChanges(onSuccess, onError)

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

.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
}]

Player 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 be 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 the handler should be bound to.

  • handler: The function to handle incoming events of type “eventName”.

enplug.once( eventName, handler ) : undefined

The once function is a convenience 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 your 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
});

enplug.appStatus.getTrigger(): Promise<Object>

Returns the reason why an app was rendered on-screen. It is used for Social CMS apps. The response will contain a reason and data property. Check the value of the reason property to determine if this is a new item (reason: "event").

For example, a response to getTrigger() from a social app will contain the following:

{
  reason:("schedule"|"event"),
  data: {
    Id, 
    SocialNetwork,
    SocialItemId,
    FeedId,
    CreatedTime,
    LastSavedTime,
    CreatedTime,
    ProfanityCount,
    ProfaneWords,
    IsApproved,
    IsAllowed,
    SecondaryText,
    ImageLocalPath,
    UserImageLocalPath
    }
}

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.all {Promise<Object>}

This Promise will resolve to an Object with all of the app's settings. Additional information about these settings are outlined further below.

enplug.settings.all.then(function( settings ) {
  // returns all the app's setting in one API method call
});

{
 is4k,
 transitionType,
 whitelabel,
 locale,
 zoningInfo,
 orientation,
 isMuted
};

  • is4K: A boolean if the Enplug Player is connected to a 4K display (true) or (false).

  • transitionType: The current display group's saved animation used by the Enplug Player to transition between applications.

  • whitelabel: The value of the white label set for a given Enplug Player.

  • locale: The saved language for the current display group playing the app.

  • zoningInfo: An object containing the app's width, height , size, and zone, available for both zoning widgets ( ticker or banner ) as well as the main app. 

    For the main app, it will return a zone value of "main" and  the app's dimensions (width and height ).

    {
      width: 480,
      height: 1080,
      size: 4,
      zone: 'banner'
    }
    • width: Width of the current app.

    • height: Height of the current app.

    • size: Returns a value for the zone widget size. Possible banner values include 1,2,3,4 with 1 representing the smallest size (1/4 of the possible banner size) and 4 as the largest.

    • zone: Returns the current zone widget or main app. Possible values include  "banner", "ticker" or "main".

  • orientation: The display group's set orientation (portrait or landscape ).

  • isMuted: A boolean if the Enplug Player is connected to a display which is muted (true) or (false) if it is not.

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

Note: This method is now obsolete. Please use enplug.settings.all instead.

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<boolean>}

Note: This method is now obsolete. Please use enplug.settings.all instead.

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>}

Note: This method is now obsolete. Please use enplug.settings.all instead.

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
});

.enplug.settings.hideWhiteLabel {Promise<boolean>}

Hides the white label overlay at the bottom of the display. 

enplug.settings.hideWhitelabel().then(function( isHidden ) {
  // returns a boolean if the white label has been successfully hidden
});

.enplug.settings.locale {Promise<string>}

Note: This method is now obsolete. Please use enplug.settings.all instead.

Resolves to a string of the saved locale for the device. This can be used  to set regional or languages settings on the player app. The default language can be modified on the display group settings page in dashboard by selecting a language from the dropdown and saving. This will apply to all devices within the display group: https://dashboard.enplug.com/display-group/{{display-group-id}}

enplug.settings.locale.then(function( value ) {
  // the device locale will be returned here 
});

.enplug.settings.zoning {Promise<Object>}

Note: This method is now obsolete. Please use enplug.settings.all instead.

Resolves to an object with zoning configurations including the app's dimensions, size, and zone. This can be used to get specific properties for a zoning widget (banner or ticker).

  • size: Returns a value for the  zone widget size. Possible banner values include 1,2,3,4 with 1 representing the smallest size (1/4 of the possible banner size) and 4 as the largest.

  • zone: Returns the current zone widget or main app. Possible values include  "banner", "ticker" or "main".

enplug.settings.zoning.then(function( info ) {
  // the zoning info will be returned here 
});
{
  width: 480,
  height: 1080,
  size: 4,
  zone: 'banner'
}

.enplug.settings.deviceId {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 need the id of the device that is currently playing the app.

enplug.settings.deviceId.then(function( value ) {
  // the device id will be returned here 
});

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.