Android TV D-Pad Functions
WebToNative's Smart TV Support add-on forwards every remote button press into your website as a JavaScript function call, so your site can react to it
When your app runs on an Android TV device, users navigate with a remote control (D-Pad) instead of touch.
Unlike the other bridges in these docs, this is not something your website calls it's a contract in the other direction: your website defines a global function, and the native app calls it whenever the user presses a remote key.
You'll need to import the javascript file in your website before starting from this link.
Platform support: Android only. This add-on has no iOS/tvOS equivalent
handleKeyEventis never called on iOS.
How It Works
Enable Smart TV Support in the WebToNative dashboard (see Setup below).
On your website, define a global
window.handleKeyEvent(key)function.When the app is running on a device the SDK detects as Android TV, every remote button press is checked against
typeof handleKeyEvent === 'function'. If your function exists, it's called with a string identifying the key (see Key Values below).
Your website cannot block or "consume" a key press. The native side does not look at anything handleKeyEvent returns. For the navigation keys (UP, DOWN, LEFT, RIGHT, CENTER, HOME, MENU, ENTER, INFO), the native app always additionally re-dispatches the raw key event into the WebView right after calling handleKeyEvent, to move DOM focus between focusable elements. You can react to these keys (e.g. play a sound, update some UI state) but you cannot prevent the underlying focus movement from also happening. The media transport keys (PLAY, PAUSE, STOP, NEXT, PREVIOUS) are the exception, see the note below.
Setting Up Smart TV Support
Go to your WebToNative dashboard → Add-ons → Smart TV Support and enable it.
No credentials are required — once enabled, the behaviour described on this page is active automatically whenever the app is running on a device detected as Android TV.
Detection is automatic: the SDK checks the device's UiModeManager for TV mode and for the Android TV "leanback" feature. You don't need to detect Android TV yourself in JavaScript before defining handleKeyEvent just define it, and it will simply never be called on a phone/tablet.
Defining handleKeyEvent
Define this function anywhere on your page, before the user starts interacting with the remote (e.g. on page load):
Parameters passed to your function:
Your function has no meaningful return value — nothing reads it.
Key Values
UP
D-Pad Up
Always also moves DOM focus upward, in addition to calling handleKeyEvent.
DOWN
D-Pad Down
Always also moves DOM focus downward, in addition to calling handleKeyEvent.
LEFT
D-Pad Left
Always also moves DOM focus left, in addition to calling handleKeyEvent.
RIGHT
D-Pad Right
Always also moves DOM focus right, in addition to calling handleKeyEvent.
CENTER
D-Pad Center / Select
Also re-dispatched to the WebView for native focus handling, see the warning above.
HOME
Home
Also re-dispatched to the WebView.
MENU
Menu
Also re-dispatched to the WebView.
ENTER
Enter
Also re-dispatched to the WebView.
INFO
Info
Also re-dispatched to the WebView.
PLAY
Media Play/Pause (while paused)
Not re-dispatched your website is fully responsible for handling it. If handleKeyEvent isn't defined, the user sees a "Media Player not working" toast and nothing happens.
PAUSE
Media Play/Pause (while playing)
Same as PLAY not re-dispatched, fully your responsibility.
STOP
Media Stop
Same as PLAY not re-dispatched, fully your responsibility.
NEXT
Media Next Track
Not re-dispatched. No fallback toast if undefined it's simply a no-op.
PREVIOUS
Media Previous Track
Not re-dispatched. No fallback toast if undefined it's simply a no-op.
PLAY, PAUSE, and STOP are only forwarded to handleKeyEvent if the separate Custom Media Player add-on is disabled. If you also have WebToNative's Custom Media Player add-on enabled, those three keys are intercepted by the native custom player instead, and your handleKeyEvent never receives them at all. Disable Custom Media Player if you need to handle transport controls yourself in JavaScript.
Keys That Never Reach handleKeyEvent
Back
Handled entirely natively as the app's back-navigation action. Never forwarded to JavaScript.
Voice/Assistant button
Natively launches Google Assistant. Never forwarded to JavaScript.
Implementation Checklist
WebToNative Dashboard
Your Website
Frequently Asked Questions
Why is `handleKeyEvent` never called on my device?
Two things are required: the Smart TV Support add-on must be enabled in the WebToNative dashboard, and the device must be detected as Android TV (TV UI mode or the "leanback" feature). On a regular phone or tablet or on iOS handleKeyEvent is never called.
Can I prevent the D-Pad from moving focus to the next element?
No, not for the navigation keys (UP, DOWN, LEFT, RIGHT, CENTER, HOME, MENU, ENTER, INFO). The native app calls handleKeyEvent (if defined) and then unconditionally re-dispatches the key event for native focus handling there's no way to intercept or cancel that from JavaScript today.
Why did the user see a "Media Player not working" message?
That toast only appears for the media transport keys (PLAY, PAUSE, STOP) when window.handleKeyEvent isn't defined at all. Define the function and handle those key values to remove it.
I pressed Play/Pause/Stop but nothing happened in my JavaScript function.
Check whether the Custom Media Player add-on is also enabled if it is, those three keys are consumed by the native custom player before they ever reach handleKeyEvent.
Last updated