External bus

An app that embeds the frontend, like the companion apps, can do things a browser can't: scan a barcode, write an NFC tag, commission a Matter device, or show a native screen. The external bus is how the frontend and the app talk about that. It works next to external authentication, and uses the same bridges. The code is in src/external_app/.

Messages are JSON objects.

From the frontend to the app, the frontend uses the bridge that is available:

// Android, V2: the message is wrapped and serialized
window.externalAppV2.postMessage(
  JSON.stringify({ type: "externalBus", payload: message })
);

// Android, V1: the message is serialized
window.externalApp.externalBus(JSON.stringify(message));

// iOS and macOS: the message is passed as an object
window.webkit.messageHandlers.externalBus.postMessage(message);

From the app to the frontend, the app calls a function the frontend defines:

window.externalBus(message);

Every message has an id and a type, and a payload when the type needs one:

interface Message {
  id: number;
  type: string;
  payload?: unknown;
}

Some messages expect an answer. The answer is a result message with the same id:

interface SuccessResult {
  id: number;
  type: "result";
  success: true;
  result: unknown;
}

interface ErrorResult {
  id: number;
  type: "result";
  success: false;
  error: { code: string; message: string };
}

Messages from the app to the frontend are commands, with type: "command" and the name of the command in command:

{
  "id": 5,
  "type": "command",
  "command": "navigate",
  "payload": { "path": "/config/areas/dashboard" }
}

The frontend answers every command with a result. Go by when the two general error codes are sent, not by their names alone:

• unknown_command: the frontend has no command handler yet, because it is still starting up. The command itself may well be known.
• not_ready: the command handler is in place, but it does not handle this command.

Both are sent by receiveMessage in src/external_app/external_messaging.ts.

The frontend asks what the app can do, right after it connects. Payload: none. The app answers with an object. All keys are optional:

The frontend asks where an entity can be added, like a home screen widget or a watch face.

Payload:

{ entity_id: string }

Answer:

{
  actions: Array<{
    enabled: boolean;
    name: string;
    details?: string;
    mdi_icon: string;
    app_payload: string;
  }>;
}

name and details are shown as they are, so translate them in the app. mdi_icon is an icon name like mdi:car. app_payload is any string, which the frontend sends back with entity/add_to when the user picks the action.

All commands get a result back. On success, result is null.