@telemetrytv/sdk v1.0.0-alpha1

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:

^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:

^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:

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:

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:

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