Contrat de Reponse Host (Bridge Unifie)

Ce document definit le contrat obligatoire des reponses emises par les applications hotes (Android TV, LG, Samsung) vers l'iframe SvelteKit.

Problem Statement

Des ecarts de format de reponse (tag/success/result vs type/ok/payload) peuvent provoquer des timeouts cote application, puis des fallbacks invalides (uid = unknown) et des appels CMS incorrects.

Format de reponse obligatoire

Le host doit repondre uniquement avec ce format:

{
	"type": "TV_API_RESPONSE",
	"requestId": "req_1775343802285_kst2somz9",
	"ok": true,
	"payload": {
		"id": "b25040d615a81b68"
	}
}

En cas d'erreur:

{
	"type": "TV_API_RESPONSE",
	"requestId": "req_1775343802285_kst2somz9",
	"ok": false,
	"payload": {
		"message": "Unknown action: GET_MAC",
		"code": "UNSUPPORTED_ACTION"
	}
}

Regles de protocole

• requestId doit etre strictement identique a celui de la requete.
• Une requete TV_API_REQUEST doit produire exactement une reponse.
• La reponse doit etre postee vers le bon contexte WebView/iframe (pas seulement loggee cote natif).
• Le host doit repondre rapidement (< 800ms recommande pour les actions GET_*).
• Le format legacy (tag/success/result) n'est pas supporte.

Actions minimales a implementer

Action	payload en succes	Notes
INITIALIZE_HOST	{}	Demarrage du bridge
GET_IDENTIFIER	{ id: string }	Valeur non vide, jamais unknown
GET_MANUFACTURER	{ manufacturer: string }	Exemple: SEI Robotics
GET_MODEL	{ model: string }	Exemple: Dongle G 4K
GET_MAC	{ mac: string }	Si indisponible: ok: false + message explicite
GET_SYSTEM_INFO	{ os?: string, osVersion?: string }	Succes partiel autorise, jamais unknown
GET_STORAGE_INFO	{ diskFree?: number, diskTotal?: number }	Valeurs en bytes, succes partiel autorise
LAUNCH_APP	{ launched?: true } ou {}	Selon implementation host
CAN_LAUNCH_APP	{ canLaunch: boolean, reasonCode?: string }	Verification dynamique avant lancement app
LAUNCH_TV	{}	Retour TV natif
OPEN_SYSTEM_SETTINGS	{ opened: true } ou true	Parametres systeme
OPEN_MANUFACTURER_SETTINGS	{ opened: true } ou true	Parametres constructeur (target/vendor/section)
OPEN_SETTINGS (legacy)	{ opened: true } ou true	Fallback legacy
GET_HOST_CAPABILITIES	{ bridgeVersion, host, capabilities }	Snapshot des capacites
GET_NETWORK_INFO	{ wifi, ethernet, vpn, collectedAt }	Etat reseau du host
PURGE_DATA	{}	Purge systeme
REBOOT	{}	Reboot systeme
INSTALL_APP	{}	Installation APK
HOTSPOT_GET	{ enabled, ssid?, password? }	Etat hotspot courant
HOTSPOT_SET	{}	Start/stop et mises a jour hotspot

Verification manuelle

1. Ouvrir l'app en mode host.
2. Verifier qu'aucun timeout bridge n'apparait dans les logs UI.
3. Verifier que GET_IDENTIFIER retourne un identifiant valide.
4. Verifier l'absence d'appels vers /items/devices/unknown.
5. Verifier que GET_MAC ne renvoie plus Unknown action.

Troubleshooting

• Timeout cote UI: verifier que la reponse contient type: TV_API_RESPONSE et le bon requestId.
• Reponse ignoree par l'UI: verifier ok/payload et la cible postMessage.
• UID invalide: verifier que GET_IDENTIFIER ne renvoie jamais une chaine vide/unknown.

References

• Bridge overview: docs/technique/bridge/overview.md
• Echanges complets: docs/technique/bridge/exchanges.md