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

[^1]: Only available in the Android Player with corresponding permissions toggled on.

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 |

[^2]: It includes the TelemetryTV Electron Player and the TelemetryTV Desktop app for administration. Both of them are available on Mac, Windows, and Linux.

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 |

[^3]: 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.

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