Introduction
This document explains how the web application integrates with the TV application via WebView.
It covers authentication payloads and communication protocols.
Integration flow
-
TV app opens WebView.
-
TV app injects authentication data along with additional information.
-
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
{
"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:
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_WEBVIEWmessage to the parent window. The parent application receives the message and closes the WebView. -
Android devices: the existing React Native WebView
canGoBackimplementation continues to handle Back navigation.
Mandatory security requirements
-
Always use HTTPS
-
Never log auth tokens
-
Sanitize payloads
-
Token expiration handling
High-level design flow
WebView back key handling
WebView security and cache properties from ION
|
Feature |
Affects cookies |
Affects cache |
Private session |
Platform |
|---|---|---|---|---|
|
|
Clears all |
Clears all |
Yes |
Android / iOS |
|
|
No |
Disk only |
No |
Android / Limited iOS |
|
|
No |
Ignores HTTP cache |
No |
Android only |
|
|
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
"selfCarePortal": {
"enable": true,
"portalUrl": "https://<host>:<port>/iristvapp/index.html",
"authenticationUrl": "",
"sendIdTokenInQuery": true,
"customHeaderIdToken": ["id_token"]
}
|
Configuration |
Description |
|---|---|
|
|
Shows the WebView only when enabled. |
|
|
URL to be loaded in the WebView |
|
|
URL used to retrieve the |
|
|
Determines how the |
|
|
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 |
|---|---|
|
|
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:
"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:
{ "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.