OpenTV ION

Self-care portal integration guide

Introduction

This document explains how the web application integrates with the TV application via WebView.

It covers authentication payloads and communication protocols.

Integration flow

  1. TV app opens WebView.

  2. TV app injects authentication data along with additional information.

  3. Web page validates session.

Key navigation within WebView

The webpage should handle the user key navigation (TV remote) for navigating between the components and accessing them inside the WebView component.

The Back key is also handled by the webpage.

If the webpage wants to close the WebView, it must send the COLLAPSE_WEBVIEW message, as explained in the next section.

WebView close message handling

Web devices

The portal should support sending a COLLAPSE_WEBVIEW message so that the parent application can close the WebView. When the user presses the Back button on the Home screen (first page), this message must be sent for all Smart TV devices and web platforms.

It is the responsibility of the web portal to send this message from the Home screen.

Note: the WebView is also closed if this message is sent from a child page.

Message format

JSON
{
  "COLLAPSE_WEBVIEW": "TRUE"
}

Example implementation

When the user presses Back on the Home screen, the portal should send the following message to the parent window to close the WebView:

JavaScript
window.parent.postMessage(
  {
    COLLAPSE_WEBVIEW: "TRUE"
  },
  "*"
);

Android devices

This message is not applicable to Android TV devices. Even if it is sent, it is not received. On Android devices, the existing React Native WebView canGoBack implementation continues to handle Back navigation. On Android TV devices, pressing Back on the Home screen closes the WebView.

Guidelines

  • Internal pages: the portal should handle Back navigation as usual.

  • Smart TV platforms: when the user presses Back on the Home screen, the portal should send the COLLAPSE_WEBVIEW message to the parent window. The parent application receives the message and closes the WebView.

  • Android devices: the existing React Native WebView canGoBack implementation continues to handle Back navigation.

Mandatory security requirements

  • Always use HTTPS

  • Never log auth tokens

  • Sanitize payloads

  • Token expiration handling

High-level design flow

Screenshot 2026-02-25 at 2.26.21 PM.png


WebView back key handling

Screenshot 2026-02-25 at 3.46.06 PM.png


WebView security and cache properties from ION

Feature

Affects cookies

Affects cache

Private session

Platform

incognito

Clears all

Clears all

Yes

Android / iOS

cacheEnabled={false}

No

Disk only

No

Android / Limited iOS

cacheMode="LOAD_NO_CACHE"

No

Ignores HTTP cache

No

Android only

thirdPartyCookiesEnabled

Controls third-party only

No

No

Android / Limited iOS

incognito

The incognito property creates a non-persistent WebView session.

Clears all cookies, cache, and localStorage when unmounted.

cacheEnabled

Disables WebView disk cache.

cacheMode="LOAD_NO_CACHE"

Ignores HTTP cache completely.

thirdPartyCookiesEnabled

Controls whether the WebView accepts third-party cookies (cookies set by a domain other than the main page).

Platform configuration changes

JSON
"selfCarePortal": {
    "enable": true,
    "portalUrl": "https://<host>:<port>/iristvapp/index.html",
    "authenticationUrl": "",
    "sendIdTokenInQuery": true,
    "customHeaderIdToken": ["id_token"]
}

Configuration

Description

enable

Shows the WebView only when enabled.

portalUrl

URL to be loaded in the WebView

authenticationUrl

URL used to retrieve the id_token

sendIdTokenInQuery

Determines how the id_token is passed to the WebView

customHeaderIdToken

Custom request header that carries the user's ID token for authentication

sendIdTokenInQuery = true

The id_token is sent as a query parameter:

https://<host>:<port>/iristvapp/index.html?id_token=xyz

Parameter

Description

id_token

Authentication token used for authorization on the web page

sendIdTokenInQuery = false

The id_token is sent in the request headers. The header used is defined by customHeaderIdToken:

JSON
"customHeaderIdToken": ["id_token"]

The value passed to customHeaderIdToken can be any valid string, and is forwarded to the WebView together with the id_token. For example:

JSON
{ "id_token": "Bearer id_token" }

If no value is passed to customHeaderIdToken, the token is not passed to the WebView.

Note: only the id_token header key is configurable.