Update the implementation details of the external bus for the apps

Author: TimoPtr

docs/frontend/external-authentication.md

@@ -6,25 +6,36 @@ By default, the frontend will take care of its own authentication tokens. If non
 
 If you want to embed the Home Assistant frontend in an external app, you will want to store the authentication inside the app but make it available to the frontend. To support this, Home Assistant exposes an external authentication API.
 
-To activate this API, load the frontend with `?external_auth=1` appended to the URL. If this is passed in, Home Assistant will expect either `window.externalApp` (for Android) or `window.webkit.messageHandlers` (for iOS) to be defined containing the methods described below.
+To activate this API, load the frontend with `?external_auth=1` appended to the URL. If this is passed in, Home Assistant will expect either `window.externalAppV2` (Android V2, recommended), `window.externalApp` (Android V1, fallback) or `window.webkit.messageHandlers` (iOS) to be defined containing the methods described below.
 
-## Get access token
+:::note
+V2 (`window.externalAppV2`) is only available when the WebView supports [`WebViewFeature.WEB_MESSAGE_LISTENER`][web-message-listener]. The app should fall back to V1 otherwise.
+:::
 
-_This API has been introduced in Home Assistant 0.78._
+## Get access token
 
 When the frontend loads, it will request an access token from the external authentication. It does so by calling one of the following methods with an options object. The options object defines the callback method to be called with the response and an optional `force` boolean which is set to `true` if the access token should be refreshed, regardless if it has expired or not.
 
 The `force` boolean has been introduced in Home Assistant 0.104 and might not always be available.
 
 ```js
-window.externalApp.getExternalAuth({
-  callback: "externalAuthSetToken",
-  force: true
-});
-// or
+// V2 (recommended)
+window.externalAppV2.postMessage(
+  JSON.stringify({
+    type: "getExternalAuth",
+    payload: { callback: "externalAuthSetToken", force: true },
+  })
+);
+
+// V1 (fallback)
+window.externalApp.getExternalAuth(
+  JSON.stringify({ callback: "externalAuthSetToken", force: true })
+);
+
+// iOS
 window.webkit.messageHandlers.getExternalAuth.postMessage({
   callback: "externalAuthSetToken",
-  force: true
+  force: true,
 });
 ```
 
@@ -45,17 +56,25 @@ The frontend will call this method when the page first loads and whenever it nee
 
 ## Revoke token
 
-_This API has been introduced in Home Assistant 0.78._
-
 When the user presses the logout button on the profile page, the external app will have to [revoke the refresh token](auth_api.md#revoking-a-refresh-token), and log the user out.
 
 ```js
-window.externalApp.revokeExternalAuth({
-  callback: "externalAuthRevokeToken"
-});
-// or
+// V2 (recommended)
+window.externalAppV2.postMessage(
+  JSON.stringify({
+    type: "revokeExternalAuth",
+    payload: { callback: "externalAuthRevokeToken" },
+  })
+);
+
+// V1 (fallback)
+window.externalApp.revokeExternalAuth(
+  JSON.stringify({ callback: "externalAuthRevokeToken" })
+);
+
+// iOS
 window.webkit.messageHandlers.revokeExternalAuth.postMessage({
-  callback: "externalAuthRevokeToken"
+  callback: "externalAuthRevokeToken",
 });
 ```
 
@@ -68,3 +87,5 @@ window.externalAuthRevokeToken(true);
 // If unable to logout
 window.externalAuthRevokeToken(false);
 ```
+
+[web-message-listener]: https://developer.android.com/reference/androidx/webkit/WebViewCompat.WebMessageListener