@telemetrytv/sdk

TelemetryTV SDK API

The official TelemetryTV application API package. Use it to build applications that run on the TelemetryTV platform.

Get Started

Using A Package Manager

First, install the package using your preferred package manager:

# With NPM
npm install @telemetrytv/sdk

# With Yarn
yarn add @telemetrytv/sdk

# With PNPM
pnpm add @telemetrytv/sdk

Then, import the methods you need from the package in your codes:

import { nextPage, getDeviceProperties } from '@telemetrytv/sdk'

// Go to next page
nextPage()

// Get device properties
getDeviceProperties().then((device) => {
  console.log(device)
  // -> Do something with the device properties data
}).catch((error) => {
  // -> Add your error handler here
})

Using From CDN

With the help of unpkg, you can use the SDK directly from the CDN.

Import ESM From CDN

<!-- ESM format -->
<script type="module">
  import { nextPage, getDeviceProperties } from 'unpkg.com/@telemetrytv/sdk/index.js'

  // Go to next page
  nextPage()

  // Get device properties
  getDeviceProperties().then((device) => {
    console.log(device)
    // -> Do something with the device properties data
  }).catch((error) => {
    // -> Add your error handler here
  })
</script>

Use UMD Format from CDN

<!-- UMD format -->
<script src="unpkg.com/@telemetrytv/sdk/index.umd.cjs"></script>

In UMD format, the SDK methods are exposed under the TelemetryTvSdk global variable:

// Go to next page
TelemetryTvSdk.nextPage()

// Get device properties
TelemetryTvSdk.getDeviceProperties().then((device) => {
  console.log(device)
  // -> Do something with the device properties data
}).catch((error) => {
  // -> Add your error handler here
})

Migration Guide

Please check MIGRATION.md for the guideline for migration from the previous auto-injected SDK.

You can skip the migration part if you are new to the TelemetryTV SDK.

Get Device Properties

• Method Name: getDeviceProperties (Promise)
• Return Data: Object

import { getDeviceProperties } from '@telemetrytv/sdk'

getDeviceProperties().then((device) => {
  console.log(device)
  // -> Do something with the device properties data
}).catch((error) => {
  console.error(error)
  // -> Add your error handler here
})

Device properties included:

Property	Type	Description
id	String	The unique device id in TelemetryTV system
name	String	Name of the device defined in TelemetryTV
serialNumber	String	Serial Number of the device
model	String	Model Type of the device
location	String	Device's "Location" field defined in TelemetryTV
geo	Object	Device's Geographic Coordinates pair 1
os	String	Name of the Operating System on the device
osVersion	String	Version of the Operating System on the device
browserName	String	Name of the browser rendering engine
browserVersion	String	Version of the browser rendering engine
tags	Array	Device's "Tags" value defined in TelemetryTV
deviceLanguage	String	Device-level language defined in TelemetryTV (Device → Detail)
accountLanguage	String	Account-level language defined in TelemetryTV (Settings → Localization)
language	String	The final language locale settings on this device (deviceLanguage > accountLanguage)
contentPlayback	String	Content playback mode of the device (playlists or webapp)
uptime	Number	Uptime of the device in seconds
environmentVars	Array	Device's "Environment Variables" defined in TelemetryTV
rotation	Number	Rotation of the device's screen in degrees
orientation	String	Orientation of the device's screen (landscape or portrait)
serialPorts	Array	The serial ports of the device (if any)

Get Player Properties

• Method Name: getPlayerProperties (Promise)
• Return Data: Object

import { getPlayerProperties } from '@telemetrytv/sdk'

getPlayerProperties().then((player) => {
  console.log(player)
  // -> Do something with the player properties data
}).catch((error) => {
  // -> Add your error handler here
})

Player properties included:

Property	Type	Description
apiStatus	String	The status of the TelemetryTV API WebSocket Connection
stage	String	The current stage of the player (production, qa, etc)
isPreviewing	Boolean	Whether is running in preview mode (viewing within the administration app)
isElectron	Boolean	Whether the player is running in the Electron app 2
isDesktop	Boolean	Whether the player is running in the TelemetryTV Desktop app
isAndroid	Boolean	Whether the player is running on Android
isIos	Boolean	Whether the player is running on iOS
isChromeOS	Boolean	Whether the player is running on ChromeOS
isWindows	Boolean	Whether the player is running on Windows
isMacOS	Boolean	Whether the player is running on macOS
isBrowser	Boolean	Whether the player is running in the browser PWA mode

Get Playlist Data

NOTE: Not available when device is under the Webapp-only content playback mode.

Playlist data included:

Property	Type	Description
id	String	The unique playlist id in TelemetryTV system
name	String	Name of the playlist

Get Current Playlist

• Method Name: getCurrentPlaylist (Promise)
• Return Data: Object

import { getCurrentPlaylist } from '@telemetrytv/sdk'

getCurrentPlaylist().then((playlist) => {
  console.log(playlist)
  // -> Do something with the playlist data
}).catch((error) => {
  // -> Add your error handler here
})

Get Playlist By Id

• Method Name: getPlaylist (Promise)
• Parameter: playlistId (String)
• Usage: getPlaylist(playlistId)
• Return Data: Object

import { getPlaylist } from '@telemetrytv/sdk'

getPlaylist('sample-playlist-id-1234').then((playlist) => {
  console.log(playlist)
  // -> Do something with the playlist data
}).catch((error) => {
  // -> Add your error handler here
})

Get All Playlists

• Method Name: getAllPlaylists (Promise)
• Return Data: Array of Playlist data Objects

import { getAllPlaylists } from '@telemetrytv/sdk'

getAllPlaylists().then((playlistsArray) => {
  console.log(playlistsArray)
  // -> Do something with the playlists array
}).catch((error) => {
  // -> Add your error handler here
})

Get Playlist Pages

NOTE: Not available when device is under the Webapp-only content playback mode.

Page data included:

Property	Type	Description
id	String	The unique page id in TelemetryTV system
name	String	Name of the page
duration	Number	Duration of the page in seconds

Get Current Page

• Method Name: getCurrentPage (Promise)
• Return Data: Object

import { getCurrentPage } from '@telemetrytv/sdk'

getCurrentPage().then((page) => {
  console.log(page)
  // -> Do something with the page data
}).catch((error) => {
  // -> Add your error handler here
})

Get All Pages

Get all pages from the all playlists assigned to the device.

• Method Name: getAllPages (Promise)
• Return Data: Array of Page data Objects

import { getAllPages } from '@telemetrytv/sdk'

getAllPages().then((pagesArray) => {
  console.log(pagesArray)
  // -> Do something with the pages array
}).catch((error) => {
  // -> Add your error handler here
})

Get Pages By Playlist Id

Get pages from the target playlist.

• Method Name: getPlaylistPages (Promise)
• Parameter: playlistId (String)
• Usage: getPlaylistPages(playlistId)
• Return Data: Array of Page data Objects

import { getPlaylistPages } from '@telemetrytv/sdk'

getPlaylistPages('sample-playlist-id-4321').then((pagesArray) => {
  console.log(pagesArray)
  // -> Do something with the pages array
}).catch((error) => {
  // -> Add your error handler here
})

Get Playback State

NOTE: Not available when device is under the Webapp-only content playback mode.

• Method Name: getPlaybackState (Promise)
• Return Data: String
• Possible Values: "playing" | "paused".

import { getPlaybackState } from '@telemetrytv/sdk'

getPlaybackState().then((state) => {
  console.log(state)
  // -> Do something with the playback state
}).catch((error) => {
  // -> Add your error handler here
})

Get Media URLs

Get playable URLs of the image and video files you uploaded to TelemetryTV "Media" section.

Get Media By Id

• Method Name: getMediaById (Promise)
• Parameter: mediaId (String)
• Usage: getMediaById(mediaId)
• Return Data: String format of the media URL

import { getMediaById } from '@telemetrytv/sdk'

getMediaById('sample-media-id-1234').then((mediaUrl) => {
  console.log(mediaUrl)
  // -> Do something with the media URL
}).catch((error) => {
  // -> Add your error handler here
})

Get Media By Tags

• Method Name: getMediaByTags (Promise)
• Parameters:
  • tags (Array of String), required
  • folderId (String), optional
• Usage: getMediaByTags(tags, folderId)
• Return Data: Array of the media URLs in String format

import { getMediaByTags } from '@telemetrytv/sdk'

getMediaByTags(['tag1', 'tag2'], 'sample-folder-id-1234').then((mediaUrls) => {
  console.log(mediaUrls)
  // -> Do something with the media URLs array
}).catch((error) => {
  // -> Add your error handler here
})

Get Media In Folder

• Method Name: getMediaInFolder (Promise)
• Parameter: folderId (String)
• Usage: getMediaInFolder(folderId)
• Return Data: Array of the media URLs in String format

import { getMediaInFolder } from '@telemetrytv/sdk'

getMediaInFolder('sample-folder-id-1234').then((mediaUrls) => {
  console.log(mediaUrls)
  // -> Do something with the media URLs array
}).catch((error) => {
  // -> Add your error handler here
})

Control Playlist Playback

NOTE: Not available when device is under the Webapp-only content playback mode.

Go To The Next Page

• Method Name: nextPage

import { nextPage } from '@telemetrytv/sdk'

nextPage()

Go To The Previous Page

• Method Name: previousPage

import { previousPage } from '@telemetrytv/sdk'

previousPage()

Go To A Specific Page By Page Id

• Method Name: goToPageById
• Parameter: pageId (String)
• Usage: goToPageById(pageId)

import { goToPageById } from '@telemetrytv/sdk'

goToPageById('sample-page-id-1234')

Go To A Specific Page By Page Name

• Method Name: goToPageByName
• Parameter: pageName (String)
• Usage: goToPageByName(pageName)

import { goToPageByName } from '@telemetrytv/sdk'

goToPageByName('Your Target Page Name')

If multiple pages have the same name, the first page found will be returned.

Pause Playlist Playback

• Method Name: pause

import { pause } from '@telemetrytv/sdk'

pause()

Resume Playlist Playback

• Method Name: play

import { play } from '@telemetrytv/sdk'

play()

Player Controls

Restart Player

• Method Name: restart

import { restart } from '@telemetrytv/sdk'

restart()

Start An Override

• Method Name: startOverride
• Parameter: overrideName (String)
• Usage: startOverride(overrideName)

import { startOverride } from '@telemetrytv/sdk'

startOverride('Target Override Name')

Stop An Override

• Method Name: endOverride
• Parameter: overrideName (String)
• Usage: endOverride(overrideName)

import { endOverride } from '@telemetrytv/sdk'

endOverride('Target Override Name')

Serial Port Controls

Send Serial Connection

Sends serial connection information to the device.

• Method Name: serialConnection
• Parameter: options (Object)
• Usage: serialConnection(options)

import { serialConnection } from '@telemetrytv/sdk'

serialConnection({
  port: 'PORT_NAME',
  bufferSize: 4096,
  bitrate: 9600,
  dataBits: 'eight',
  stopBits: 'one',
  //...
})

Please refer to the Chrome Serial Connection Options Documentation for more information about the options object.

Send Serial Commands

Sends serial commands to the device.

• Method Name: serialCommands
• Parameter: commands (Array of String)
• Usage: serialCommands(commands)

import { serialCommands } from '@telemetrytv/sdk'

serialCommands([
  '12 34 56 78 90',
  //...
])

Helper Methods

Console Log

Helps to send the message to the device’s debug log so it can be viewed in debug mode or in the device logs if the device's log level is set to "Debug".

• Method Name: log
• Parameter: message (String)
• Usage: log(message)

import { log } from '@telemetrytv/sdk'

log('SDK successfully loaded')
log('Current time is ' + new Date().toLocaleString())

Message Banner

Display a message banner on top of the screen for a couple seconds.

• Method Name: message
• Parameters
  • message (String), required
  • level (String), optional. Accepted values: "debug" (default) | "log" | "info" | "warn" | "error"
• Usage: message(message, level)

import { message } from '@telemetrytv/sdk'

message('This is a test debug message')
message('This is an info message', 'info')

Get Argument Value

NOTE: Currently only available in Webapp's "Simple Editor" type.

Get argument value by its unique key defined in TelemetryTV.

• Method Name: getValue (Promise)
• Parameter: argumentKey (String)
• Usage: getValue(argumentKey)

import { getValue } from '@telemetrytv/sdk'

getValue('sample-argument-key-1234').then((value) => {
  console.log(value)
  // -> Do something with the argument value
}).catch((error) => {
  // -> Add your error handler here
})

Events

The TelemetryTV SDK has events that trigger whenever values change. By attaching event listeners to these events, you can be notified whenever there is a change in value. This helps you keep track of updates and stay informed with the latest information.

Available events:

Event Name	Description	Return Data
onReady	Called when the SDK is ready to use	null
onApiStatusChange	Called when the API WebSocket Connection status changes	The current status String
onPlaybackChange	Called when the playback state changes	"paused" or "playing"
onPageChange	Called when the current page changes, or the Playlist transitions to a new page	The current page Object
onPageDuration	Called when when page start or page duration changes. 3	The duration in Number of seconds
onPlaylistChange	Called when the current playlist changes, or the Player transitions to another playlist	The current playlist Object
onDeviceChange	Called when the device properties changes	The current device Object
onGeoChange	Called when the device's geographic coordinates changes 1	The current coordinates Object
onOverrideStart	Called when an override starts	The starting override Object
onOverrideEnd	Called when an override ends	The ending override Object
onSerialConnection	Called when a serial connection is established	The serial connection Object
onSerialCommands	Called when a commaned message is received from the configured serial port	The serial command String

Bind An Event Listener

• Method Name: bindEvent
• Parameters
  • eventName (String), required
  • eventHandler (Function), required
• Usage: bindEvent(eventName, eventHandler)

import { bindEvent } from '@telemetrytv/sdk'

function pageChangeHandler (page) {
  console.log('Page changed to ' + page.name)
  // -> Do something with the page data
}

bindEvent('onPageChange', pageChangeHandler)

Unbind An Event Listener

• Method Name: unbindEvent
• Parameters
  • eventName (String), required
  • eventHandler (Function), required
• Usage: unbindEvent(eventName, eventHandler)

import { unbindEvent } from '@telemetrytv/sdk'

function pageChangeHandler (page) {
  // ...
}

unbindEvent('onPageChange', pageChangeHandler)

Bind Multiple Event Listeners

We also provide a helper method to bind multiple event listeners at once.

• Method Name: bindEvents
• Parameters
  • eventName (String), required
  • eventHandler (Function), required
• Usage: bindEvents({ eventName1: eventHandler1, ...})

import { bindEvents } from '@telemetrytv/sdk'

function pageChangeHandler (page) {
  // ...
}

function playlistChangeHandler (playlist) {
  // ...
}

bindEvents({
  'onPageChange': pageChangeHandler,
  'onPlaylistChange': playlistChangeHandler
})

Unbind Multiple Event Listeners

Similarly, here's the helper method to unbind multiple event listeners simultaneously.

• Method Name: unbindEvents
• Parameters
  • eventName (String), required
  • eventHandler (Function), required
• Usage: unbindEvents({ eventName1: eventHandler1, ...})

import { unbindEvents } from '@telemetrytv/sdk'

function pageChangeHandler (page) {
  // ...
}

function playlistChangeHandler (playlist) {
  // ...
}

unbindEvents({
  'onPageChange': pageChangeHandler,
  'onPlaylistChange': playlistChangeHandler
})

Footnotes

• Only available in the Android Player with corresponding permissions toggled on. ↩ ↩²

• It includes the TelemetryTV Electron Player and the TelemetryTV Desktop app for administration. Both of them are available on Mac, Windows, and Linux. ↩

• Only works for:

  • Page with a fixed duration set
  • Page without a duration but there's a video (either uploaded video in the "Media" section, or a YouTube app, etc.,) that would cause the playlist to advance.
  ↩