Android TV

WebToNative's Smart TV Support

WebToNative's Support for TV add-on lets your website publish content to the Android TV home screen: a Watch Next row (the "Continue Watching" row Android TV shows near the top of the launcher, with a progress bar drawn from how far the user got into a video) and your own recommendation channel of programs the user can browse and launch straight into your app.

Your website calls these functions whenever it knows something worth surfacing — e.g. every time playback position updates, or once you've built a catalog of recommended content.

You'll need to import the javascript file in your website before starting from this link.

Platform support: Android only.

---

Setting Up Smart TV Support

1. Go to your WebToNative dashboard → Add-ons → Smart TV Support and enable it.

2. No further credentials are required.

Every function below is a no-op (and reports errorCode: "NOT_SUPPORTED" — see Callback Response Format) unless the add-on is enabled and the app is running on a device the SDK detects as Android TV. Call isSupported first if you want to confirm before building your Watch Next / channel calls into your site's playback logic.

---

JavaScript API Reference

isSupported

Checks whether Smart TV features are available right now (add-on enabled and running on an Android TV device).

Plain Javascript

window.WTN.SmartTV.isSupported({
  callback: function (response) {
    console.log(response.isSupported);
  },
});

npm

import { isSupported } from "webtonative/SmartTV";

isSupported({
  callback: (response) => {
    console.log(response.isSupported);
  },
});

Parameters:

Key	Type	Required	Description
callback	Function	No	Callback function invoked with the response.

Callback Response:

Key	Type	Description
type	String	Always "smartTvIsSupported".
success	Boolean	Always true for this call.
isSupported	Boolean	true if Watch Next / channel calls will do anything on this device.

---

watchNextUpsert

Adds a new item to the Android TV Watch Next row, or updates one already there (matched by contentId). This is what drives the "Continue Watching" progress bar shown on the card — Android TV computes the progress fraction itself from lastPlaybackPositionMs / durationMs, there's no separate percentage field to send.

The common pattern is to call this periodically while the user watches (e.g. on your video element's timeupdate event, throttled), not just once:

Plain Javascript

const video = document.querySelector("video");

function syncWatchNext() {
  window.WTN.SmartTV.watchNextUpsert({
    contentId: "movie-123",
    title: "The Great Adventure",
    playbackUri: "https://example.com/watch/movie-123",
    description: "A thrilling journey across the mountains.",
    posterArtUri: "https://example.com/posters/movie-123.jpg",
    durationMs: Math.round(video.duration * 1000),
    lastPlaybackPositionMs: Math.round(video.currentTime * 1000),
    type: "MOVIE",
    callback: function (response) {
      if (!response.success) {
        console.warn("Watch Next update failed:", response.errorCode, response.message);
      }
    },
  });
}

let lastSyncMs = 0;
video.addEventListener("timeupdate", function () {
  const now = Date.now();
  if (now - lastSyncMs > 15000) { // throttle to every 15s
    lastSyncMs = now;
    syncWatchNext();
  }
});

npm

import { watchNextUpsert } from "webtonative/SmartTV";

watchNextUpsert({
  contentId: "movie-123",
  title: "The Great Adventure",
  playbackUri: "https://example.com/watch/movie-123",
  description: "A thrilling journey across the mountains.",
  posterArtUri: "https://example.com/posters/movie-123.jpg",
  durationMs: Math.round(video.duration * 1000),
  lastPlaybackPositionMs: Math.round(video.currentTime * 1000),
  type: "MOVIE",
  callback: (response) => {
    if (!response.success) {
      console.warn("Watch Next update failed:", response.errorCode, response.message);
    }
  },
});

Parameters:

Key	Type	Required	Description
contentId	String	Yes	Stable identifier for this content. Calling again with the same contentId updates the existing card instead of creating a new one.
title	String	Yes	Title shown on the card.
playbackUri	String	Yes	Deep link opened when the user selects the card. Must be https:// — an http:// URL is rejected.
description	String	No	Description text shown for the card.
posterArtUri	String	No	Poster/thumbnail image URL. Must be https:// if provided.
durationMs	Number	No	Total content duration in milliseconds. Defaults to 0. Drives the progress bar together with lastPlaybackPositionMs.
lastPlaybackPositionMs	Number	No	Current playback position in milliseconds. Defaults to 0.
type	String	No	One of "MOVIE", "TV_EPISODE", "CLIP". Defaults to "MOVIE" if omitted or unrecognized.
callback	Function	No	Callback function invoked with the response.

Callback Response: see Callback Response Format.

contentId, title, and playbackUri are required — the call fails with errorCode: "INVALID_PAYLOAD" if any is missing.

There are two dashboard-configurable thresholds (default: 120,000ms minimum position, 95% completion) that affect this call automatically:

• An update where lastPlaybackPositionMs is still below the minimum-position threshold is rejected — Android TV doesn't show a card for content the user has barely started.

• An update where lastPlaybackPositionMs / durationMs reaches the completion threshold removes the item from Watch Next instead of updating it — matching Android TV's own "finished watching" behavior. You don't need to call watchNextRemove yourself when a video finishes.

---

watchNextRemove

Removes a single item from the Watch Next row.

Plain Javascript

window.WTN.SmartTV.watchNextRemove({
  contentId: "movie-123",
  callback: function (response) {
    console.log(response.success);
  },
});

npm

import { watchNextRemove } from "webtonative/SmartTV";

watchNextRemove({
  contentId: "movie-123",
  callback: (response) => {
    console.log(response.success);
  },
});

Parameters:

Key	Type	Required	Description
contentId	String	Yes	The contentId of the item to remove.
callback	Function	No	Callback function invoked with the response.

Callback Response: see Callback Response Format.

---

watchNextClear

Removes every item from the Watch Next row.

Plain Javascript

window.WTN.SmartTV.watchNextClear({
  callback: function (response) {
    console.log(response.success);
  },
});

npm

import { watchNextClear } from "webtonative/SmartTV";

watchNextClear({
  callback: (response) => {
    console.log(response.success);
  },
});

Parameters:

Key	Type	Required	Description
callback	Function	No	Callback function invoked with the response.

Callback Response: see Callback Response Format. Use this on sign-out, for example, so a shared TV device doesn't keep showing the previous user's Watch Next items.

---

channelPublish

Creates or updates one of your own recommendation channels on the Android TV home screen, with the list of programs it should show. Calling it again with the same channelId replaces the channel's programs with the ones you send.

Plain Javascript

window.WTN.SmartTV.channelPublish({
  channelId: "trending-now",
  name: "Trending Now",
  programs: [
    {
      programId: "movie-123",
      title: "The Great Adventure",
      playbackUri: "https://example.com/watch/movie-123",
      description: "A thrilling journey across the mountains.",
      posterArtUri: "https://example.com/posters/movie-123.jpg",
    },
    {
      programId: "movie-456",
      title: "City Lights",
      playbackUri: "https://example.com/watch/movie-456",
    },
  ],
  callback: function (response) {
    console.log(response.success);
  },
});

npm

import { channelPublish } from "webtonative/SmartTV";

channelPublish({
  channelId: "trending-now",
  name: "Trending Now",
  programs: [
    {
      programId: "movie-123",
      title: "The Great Adventure",
      playbackUri: "https://example.com/watch/movie-123",
      description: "A thrilling journey across the mountains.",
      posterArtUri: "https://example.com/posters/movie-123.jpg",
    },
    {
      programId: "movie-456",
      title: "City Lights",
      playbackUri: "https://example.com/watch/movie-456",
    },
  ],
  callback: (response) => {
    console.log(response.success);
  },
});

Parameters:

Key	Type	Required	Description
channelId	String	Yes	Stable identifier for this channel. Reusing it updates the channel in place.
name	String	Yes	Channel name shown on the home screen.
logoUri	String	No	Channel logo image URL. Currently not rendered — accepted but has no visible effect yet. Safe to omit.
programs	Array	No	List of programs in the channel. Each entry uses the fields below. Defaults to an empty channel if omitted.
callback	Function	No	Callback function invoked with the response.

programs[] fields:

Key	Type	Required	Description
programId	String	Yes	Stable identifier for this program.
title	String	Yes	Title shown for the program.
playbackUri	String	Yes	Deep link opened when the user selects it. Must be https://.
description	String	No	Description text.
posterArtUri	String	No	Poster/thumbnail image URL. Must be https:// if provided.

Callback Response: see Callback Response Format.

---

channelRemove

Removes a previously published channel from the home screen.

Plain Javascript

window.WTN.SmartTV.channelRemove({
  channelId: "trending-now",
  callback: function (response) {
    console.log(response.success);
  },
});

npm

import { channelRemove } from "webtonative/SmartTV";

channelRemove({
  channelId: "trending-now",
  callback: (response) => {
    console.log(response.success);
  },
});

Parameters:

Key	Type	Required	Description
channelId	String	Yes	The channelId of the channel to remove.
callback	Function	No	Callback function invoked with the response.

Callback Response: see Callback Response Format.

---

Callback Response Format

Every function above (except isSupported, documented separately) reports back in the same shape:

Success:

{
  "type": "smartTvWatchNextUpsert",
  "success": true
}

Failure:

{
  "type": "smartTvWatchNextUpsert",
  "success": false,
  "errorCode": "VALIDATION_FAILED",
  "message": "playbackUri must be https"
}

errorCode	Meaning
NOT_SUPPORTED	The add-on is disabled, or the device isn't detected as Android TV.
INVALID_PAYLOAD	A required field (contentId/title/playbackUri, or a channel/program's channelId/name/programId/title/playbackUri) was missing.
VALIDATION_FAILED	A field was present but invalid — most commonly a playbackUri or posterArtUri that wasn't https://, or a position below the minimum-position threshold.
UNKNOWN_ERROR	An unexpected native error occurred.

---

Implementation Checklist

WebToNative Dashboard

• Smart TV Support add-on enabled

Your Website

• Imported the WebToNative JavaScript bridge

• Every playbackUri / posterArtUri is https:// — http:// is rejected

• watchNextUpsert is called periodically during playback (not just once), so the progress bar stays accurate

• Not manually calling watchNextRemove when playback finishes — items near the completion threshold are removed automatically

• Called watchNextClear on sign-out for shared/family TV devices

---

Frequently Asked Questions

Why doesn't a Watch Next card show up on my TV?

Check three things: the Smart TV Support add-on is enabled, the device is actually detected as Android TV (call isSupported to confirm), and lastPlaybackPositionMs is above the minimum-position threshold — very early playback positions are intentionally rejected so users don't see cards for content they barely started.

How do I control the progress bar shown on the card?

You can't set a percentage directly — send durationMs and lastPlaybackPositionMs, and Android TV computes the bar from those two values. Keep calling watchNextUpsert as playback progresses to keep it accurate.

Do I need to remove a Watch Next item once the user finishes it?

No. Once lastPlaybackPositionMs / durationMs crosses the completion threshold (95% by default), the item is automatically removed from Watch Next on your next watchNextUpsert call for it.

Why is my channel logo not showing?

Channel logo rendering isn't implemented yet — logoUri is accepted but currently has no visible effect. This will be documented as functional once it ships.

Is there a tvOS / Apple TV equivalent?

No. This feature is Android TV-only today.