@vizbeetv/homesso-sdk

TV app authentication library — enables mobile-to-TV Single Sign-On (SSO) via the Vizbee platform.

Installation

npm install @vizbeetv/homesso-sdk

The default entry point ships ES5 output, safe for all TV platforms. An explicit ES6 subpath is available for modern engines.

Prerequisites

This SDK requires the Vizbee SDK (@vizbeetv/sdk) to be loaded first. That SDK populates window.vizbee.continuity and fires the VIZBEE_SDK_READY event, which this SDK listens for during initialisation.

Install it alongside this package:

npm install @vizbeetv/sdk @vizbeetv/homesso-sdk

Quick start

import { HomeSSOContext, ProgressStatus, SuccessStatus, FailureStatus } from '@vizbeetv/homesso-sdk';

const manager = HomeSSOContext.getInstance().getHomeSSOManager();

// Provide current sign-in state for the device
manager.setSignInInfoGetter(async () => [
  { userLoginType: 'email', isSignedIn: true, userLogin: '[email protected]' },
]);

// Handle an incoming sign-in request from a mobile device
manager.setSignInHandler((signInInfo, statusCallback) => {
  const { signInType } = signInInfo;

  statusCallback(new ProgressStatus(signInType, { regcode: 'ABC123' }));

  performSignIn(signInInfo)
    .then(user => statusCallback(new SuccessStatus(signInType, user.id, { email: user.email })))
    .catch(() => statusCallback(new FailureStatus(signInType, false, 'Sign-in failed')));
});

// Initialise the session (call after the Vizbee Continuity SDK is ready)
manager.init();

Package variants

| Import path | JS target | Use when | |---|---|---| | @vizbeetv/homesso-sdk | ES5 (default) | All TV platforms, legacy engines | | @vizbeetv/homesso-sdk/es5 | ES5 | Same as default, explicit | | @vizbeetv/homesso-sdk/es6 | ES6 | Tizen 5.5+, webOS 6+, Chrome 72+ | | @vizbeetv/homesso-sdk/script/es5 | ES5 UMD | <script> tag, legacy TV engines | | @vizbeetv/homesso-sdk/script/es6 | ES6 UMD | <script> tag, modern TV engines |

// ES6 build — modern bundlers / TV platforms that support ES2015+
import { HomeSSOContext } from '@vizbeetv/homesso-sdk/es6';

Script tag (CDN)

If you can't use a bundler, load the minified UMD bundle directly via <script>. The bundle exposes the SDK's named exports under window.Vizbee (e.g. window.Vizbee.HomeSSOContext).

| Variant | URL | |---|---| | ES5 | https://sdk.claspws.tv/homesso/es5/v1/vizbee.js | | ES6 | https://sdk.claspws.tv/homesso/es6/v1/vizbee.js |

/v1/ is the major-version live pointer — it always serves the newest 1.x release. To pin to a specific version, swap v1 for the full semver (e.g. /v1.0.1/vizbee.js); those paths are immutable.

<script src="https://sdk.claspws.tv/homesso/es5/v1/vizbee.js"></script>
<script>
  var manager = window.Vizbee.HomeSSOContext.getInstance().getHomeSSOManager();
  // ...same API as the npm package
</script>

API reference

HomeSSOContext

The main entry point. Use getInstance() to get the singleton.

const context = HomeSSOContext.getInstance();
const manager = context.getHomeSSOManager();
const uiManager = context.getHomeSSOUIManager();

// Toggle logging
context.enableLogger(true);
context.setLoggerLevel(LogLevel.DEBUG);

VizbeeHomeSSOManager

Retrieved via HomeSSOContext.getInstance().getHomeSSOManager().

init()

Connects to the Vizbee session. Call this after window.vizbee.continuity is available (i.e. inside your app's Vizbee ready callback).

manager.init();

setSignInInfoGetter(getter)

Provides the current sign-in state of the TV device. Called internally before deciding whether to trigger a sign-in flow.

import type { VizbeeSignInInfo } from '@vizbeetv/homesso-sdk';

manager.setSignInInfoGetter(async (): Promise<VizbeeSignInInfo[]> => {
  return [
    {
      userLoginType: 'email',        // must match the signInType sent by the mobile app
      isSignedIn: isUserLoggedIn(),
      userLogin: getCurrentUserEmail(),
    },
  ];
});

setSignInHandler(handler)

Receives sign-in requests from mobile devices. The handler is called with a signInInfo payload and a statusCallback to report progress.

import { ProgressStatus, SuccessStatus, FailureStatus } from '@vizbeetv/homesso-sdk';

manager.setSignInHandler((signInInfo, statusCallback) => {
  const { signInType } = signInInfo;

  // Report in-progress (shows the progress snackbar; regcode is required)
  statusCallback(new ProgressStatus(signInType, { regcode: 'ABC123' }));

  // Later, report success (email in customData is required to show success UI)
  statusCallback(new SuccessStatus(signInType, 'user-id-123', { email: '[email protected]' }));

  // Or report failure / cancellation
  statusCallback(new FailureStatus(signInType, false, 'Authentication failed'));
  statusCallback(new FailureStatus(signInType, true));   // isCancelled = true
});

addCustomEventAttributes(attributes)

Attaches custom key/value pairs to all analytics events emitted by the SDK.

manager.addCustomEventAttributes({ appVersion: '3.2.1', platform: 'tizen' });

Status classes

ProgressStatus

Signals that sign-in is in progress. customData.regcode is required to trigger the progress UI.

new ProgressStatus(
  signInType,          // string — matches the mobile app's sign-in type
  { regcode: 'XYZ' }, // customData — must include regcode
)

SuccessStatus

Signals a successful sign-in. customData.email is required to trigger the success UI.

new SuccessStatus(
  signInType,                         // string
  'user-id-123',                      // userId (optional)
  { email: '[email protected]' },      // customData — must include email
)

FailureStatus

Signals a failed or cancelled sign-in.

new FailureStatus(
  signInType,          // string
  false,               // isCancelled
  'Reason string',     // reason (optional)
  new Error('...'),    // exception (optional)
  { key: 'value' },   // customData (optional)
)

VizbeeHomeSSOUIManager

Retrieved via HomeSSOContext.getInstance().getHomeSSOUIManager().

Controls the appearance of the three snackbar states: informational (sign-in requested), progress (sign-in underway), and success (sign-in complete).

Apply a theme

Sets colours and fonts across all modal states at once.

import type { VizbeeHomeSSOTheme } from '@vizbeetv/homesso-sdk';

uiManager.setTheme({
  primaryColor: '#1a1a2e',           // border colour
  secondaryColor: '#16213e',         // background colour
  tertiaryColor: '#e94560',          // title text colour
  subTextColor: '#ffffff',           // description text colour
  primaryFont: 'Roboto, sans-serif',
  direction: 'ltr',                  // 'ltr' | 'rtl'
});

Default theme:

| Property | Default | |---|---| | primaryColor | #000000 | | secondaryColor | #262626 | | tertiaryColor | #FFFFFF | | subTextColor | undefined (inherits tertiary) | | direction | ltr |

Override common modal options

Applies to all three modal states.

uiManager.setCommonModalConfig({
  borderRadius: '16px',
  borderWidth: '2px',
  boxShadow: '0 0 20px rgba(0, 200, 83, 0.6)',
  width: '480px',
  padding: '24px',
  iconWidth: '64px',
  iconHeight: '64px',
});

Override per-state modal options

// Informational — shown when sign-in is first requested
uiManager.setInformationalSignInModalConfig({
  titleText: 'Sign in with your phone',
  descriptionText: 'Open the app on your mobile device to continue.',
  position: 'bottom-right',   // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  iconBase64String: '<your-base64-icon>',
});

// Progress — shown while sign-in is underway
uiManager.setProgressSignInModalConfig({
  descriptionText: 'Signing you in…',
  position: 'bottom-right',
});

// Success — shown on successful sign-in
uiManager.setSuccessSignInModalConfig({
  titleText: 'Welcome!',
  descriptionText: 'Sign-in successful. Start watching.',
  duration: 5000,             // milliseconds before auto-dismiss
  position: 'bottom-right',
});

Default modal copy:

| State | Title | Description | |---|---|---| | Informational | Mobile Sign In | Please use your mobile app to complete the sign in process. | | Progress | (none) | Signing in using your mobile app ... | | Success | Mobile Sign In Successful! | Cast or select any content to start watching. |

Logging

import { LogLevel } from '@vizbeetv/homesso-sdk';

const context = HomeSSOContext.getInstance();

context.enableLogger(true);               // on/off toggle
context.setLoggerLevel(LogLevel.DEBUG);   // sets level and enables logging

| LogLevel | Value | Description | |---|---|---| | ERROR | 0 | Critical errors | | WARN | 1 | Non-fatal warnings | | INFO | 2 | General operational info | | DEBUG | 3 | Detailed diagnostics | | TRACE | 4 | Verbose execution flow |

TypeScript types

All public types are exported from the package root:

import type {
  VizbeeSignInInfo,
  VizbeeSignInStatusCallback,
  MessagePayload,
  VizbeeSenderDevice,
  IVizbeeMessagingClient,
  IVizbeeSession,
  IVizbeeBicastSessionManager,
  ISessionStateListener,
  IVizbeeAnalyticsProvider,
  IVizbeeXMessages,
  VizbeeHomeSSOTheme,
  CommonModalPreferenceOptions,
  InformationalSignInPreferenceOptions,
  ProgressSignInPreferenceOptions,
  SuccessSignInPreferenceOptions,
} from '@vizbeetv/homesso-sdk';

License

MIT