Skip to content

Add webview communication with the frontend #2965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
TimoPtr wants to merge 2 commits into
base: master
Choose a base branch
from
+51 −0
Draft

Add webview communication with the frontend #2965

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4da38fc
Add webview communication with the frontend
TimoPtr Feb 17, 2026
47b9b01
Adjust links
TimoPtr Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/android/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,54 @@ The automotive application reuses the sources of the `:app` module, simplifying
### Wear OS

The Wear OS app communicates with the mobile app to retrieve credentials for the Home Assistant server and other configurations using the [Messaging API](https://developer.android.com/training/wearables/data/messages). It only works with the `full` flavor, as it requires Google Play Services. Once the initial setup is complete, all further communication is handled directly with Home Assistant through the WebSocket and the [webhook](/docs/api/native-app-integration/sending-data) that is created for the app.

## WebView communication architecture

The Android app's WebView acts as a bridge between the Home Assistant frontend and native Android capabilities. This architecture enables [external authentication](/docs/api/native-app-integration/frontend/external-authentication) and [external bus](/docs/api/native-app-integration/frontend/external-bus) messaging between the frontend and native code.

### Architecture overview

```mermaid
flowchart TB
subgraph WebView
JS[Home Assistant Frontend JS]
end

subgraph Bridge
JsBridge[FrontendJsBridge]
end

subgraph Handler
MsgHandler[FrontendMessageHandler]
end

subgraph Repositories
ExternalBusRepo[FrontendExternalBusRepository]
SessionMgr[ServerSessionManager]
end

JS -->|"getExternalAuth()"| JsBridge
JS -->|"revokeExternalAuth()"| JsBridge
JS -->|"externalBus()"| JsBridge

JsBridge -->|"FrontendJsHandler"| MsgHandler

MsgHandler -->|"onMessageReceived()"| ExternalBusRepo
MsgHandler -->|"getExternalAuth()"| SessionMgr
MsgHandler -->|"revokeExternalAuth()"| SessionMgr

SessionMgr -->|"ExternalAuthResult"| MsgHandler
SessionMgr -->|"RevokeAuthResult"| MsgHandler
ExternalBusRepo -->|"incomingMessages()"| MsgHandler
MsgHandler -->|"send()"| ExternalBusRepo

ExternalBusRepo -->|"scriptsToEvaluate()"| JS
MsgHandler -->|"evaluateScript()"| ExternalBusRepo
```

### Component responsibilities

- **FrontendJsBridge**: JavaScript interface exposed to the WebView that receives calls from the frontend
- **FrontendMessageHandler**: Central message handler that routes requests between the frontend and native components
- **FrontendExternalBusRepository**: Manages bidirectional message passing for the external bus protocol, parsing JSON messages into strongly-typed data structures
- **ServerSessionManager**: Handles authentication token management for external authentication