Guides

Platform Methods

Access TelemetryOS platform features including accounts, users, devices, applications, and proxy services for external content fetching.

Platform Methods

Access to accounts, users, devices, applications, and proxy services.

Overview

These methods provide access to TelemetryOS platform features and information:

  • Accounts - Current account information
  • Users - Current user information
  • Devices - Device hardware information
  • Applications - Application discovery and embedding
  • Environment - Color scheme detection and subscription

Accounts API

Access information about the current TelemetryOS account.

Import

import { accounts } from '@telemetryos/sdk';

getCurrent()

Retrieve current account information.

Signature:

async getCurrent(): Promise<{ id: string }>

Returns: Promise resolving to account object

Example:

const account = await accounts().getCurrent();

Users API

Access information about the current user.

Import

import { users } from '@telemetryos/sdk';

getCurrent()

Retrieve current user information.

Signature:

async getCurrent(): Promise<{ id: string }>

Returns: Promise resolving to user object

Example:

const user = await users().getCurrent();

Devices API

Access device hardware information.

Import

import { devices } from '@telemetryos/sdk';

getInformation()

Retrieve hardware information about the current device.

Signature:

async getInformation(): Promise<DeviceInformation>

DeviceInformation Type:

type DeviceInformation = {
  deviceSerialNumber: string;
  deviceModel: string;
  deviceManufacturer: string;
  devicePlatform: string;
}

Returns: Promise resolving to device information

Example:

const info = await devices().getInformation();

Note: Only available on physical devices (not in admin portal)

Applications API

Discover and embed other TelemetryOS applications.

Import

import { applications } from '@telemetryos/sdk';

getAllByMountPoint()

Find all applications with a specific mount point.

Signature:

async getAllByMountPoint(mountPoint: string): Promise<Application[]>

Application Type:

type Application = {
  name: string;
  mountPoints: Record<string, MountPoint>;
}

type MountPoint = {
  path: string;
  [key: string]: any;
}

Parameters:

  • mountPoint - Mount point identifier to search for

Returns: Array of applications with that mount point

Example:

const widgets = await applications().getAllByMountPoint('dashboard-widget');

getByName()

Find a specific application by name.

Signature:

async getByName(name: string): Promise<Application | null>

Parameters:

  • name - Application name

Returns: Application object or null if not found

Example:

const weatherApp = await applications().getByName('weather-widget');

setDependencies()

Declare application dependencies for preloading.

Signature:

async setDependencies(applicationSpecifiers: string[]): Promise<{
  ready: string[];
  unavailable: string[];
}>

Parameters:

  • applicationSpecifiers - Array of application specifier strings

Returns: Object with ready and unavailable arrays

Example:

const result = await applications().setDependencies([
  'weather-widget-hash123',
  'news-ticker-hash456'
]);

Important: Call and await setDependencies() before loading sub-applications in iframes.

Environment API

Access environment settings including color scheme preferences, online status, and the runtime host the application is running in.

Import

import { environment } from '@telemetryos/sdk';

ColorScheme Type

type ColorScheme = 'light' | 'dark' | 'system'

EnvironmentType Type

The runtime host an application is running in.

type EnvironmentType = 'studio' | 'player' | 'web' | 'companion' | 'development'

getColorScheme()

Retrieve the current color scheme setting.

Signature:

async getColorScheme(): Promise<ColorScheme>

Returns: Promise resolving to the current color scheme

Example:

const colorScheme = await environment().getColorScheme();

subscribeColorScheme()

Subscribe to color scheme changes.

Signature:

async subscribeColorScheme(handler: (colorScheme: ColorScheme) => void): Promise<boolean>

Parameters:

  • handler - Callback function invoked when the color scheme changes

Returns: Promise resolving to true if subscription was successful

Example:

await environment().subscribeColorScheme((colorScheme) => {
  console.log('Color scheme changed:', colorScheme);
});

unsubscribeColorScheme()

Unsubscribe from color scheme changes.

Signature:

async unsubscribeColorScheme(handler?: (colorScheme: ColorScheme) => void): Promise<boolean>

Parameters:

  • handler - Optional. The specific handler to remove. If omitted, all handlers are removed.

Returns: Promise resolving to true if unsubscription was successful

Example:

await environment().unsubscribeColorScheme();

getEnvironment()

Retrieve the runtime host the application is running in. Useful for adapting behavior per host — for example, showing different UI in Studio versus on a Player, or enabling dev-only tooling.

Signature:

async getEnvironment(): Promise<EnvironmentType>

Returns: Promise resolving to the current EnvironmentType

Example:

const env = await environment().getEnvironment();
if (env === 'player') {
  // Running on a digital signage player
}

getIsOnline()

Retrieve whether the application currently has network connectivity.

Signature:

async getIsOnline(): Promise<boolean>

Returns: Promise resolving to true when online, false when offline

Example:

const isOnline = await environment().getIsOnline();

subscribeIsOnline()

Subscribe to online/offline status changes. The handler is invoked immediately with the current value, then again whenever connectivity changes — letting an app react when it comes back online (for example, reloading APIs or media).

Signature:

async subscribeIsOnline(handler: (isOnline: boolean) => void): Promise<boolean>

Parameters:

  • handler - Callback function invoked with the online status, and again on every change

Returns: Promise resolving to true if subscription was successful

Example:

await environment().subscribeIsOnline((isOnline) => {
  if (isOnline) {
    // Back online — refresh data
  }
});

unsubscribeIsOnline()

Unsubscribe from online/offline status changes.

Signature:

async unsubscribeIsOnline(handler?: (isOnline: boolean) => void): Promise<boolean>

Parameters:

  • handler - Optional. The specific handler to remove. If omitted, all handlers are removed.

Returns: Promise resolving to true if unsubscription was successful

Example:

await environment().unsubscribeIsOnline();

Next Steps