Technique Docs

Appearance

Host Implementation Contract (Android / Philips) ​

Scope ​

Ce contrat definit les actions bridge a implementer cote host natif:

  • GET_HOST_CAPABILITIES
  • CAN_LAUNCH_APP
  • OPEN_SYSTEM_SETTINGS
  • OPEN_MANUFACTURER_SETTINGS
  • LAUNCH_TV

Le format de transport reste:

  • request: TV_API_REQUEST
  • response: TV_API_RESPONSE

Response Envelope (mandatory) ​

Chaque reponse host doit respecter:

json
{
	"type": "TV_API_RESPONSE",
	"requestId": "req_xxx",
	"ok": true,
	"payload": {}
}

En erreur:

json
{
	"type": "TV_API_RESPONSE",
	"requestId": "req_xxx",
	"ok": false,
	"payload": {
		"code": "UNSUPPORTED_ACTION",
		"message": "Action not supported"
	}
}

Error Codes (canonical) ​

  • UNSUPPORTED_ACTION: action inconnue ou non implementee.
  • NOT_AVAILABLE_ON_DEVICE: action connue mais indisponible sur ce hardware.
  • INVALID_PARAMS: payload invalide.
  • APP_NOT_INSTALLED: app absente du device.
  • APP_BLOCKED_POLICY: app interdite par policy locale/MDM.
  • HOST_BUSY: host temporairement indisponible.
  • TIMEOUT: timeout interne host.
  • INTERNAL_ERROR: erreur non categorisee.

Action Contracts ​

1) GET_HOST_CAPABILITIES ​

Request ​

json
{
	"type": "TV_API_REQUEST",
	"requestId": "req_capabilities",
	"action": "GET_HOST_CAPABILITIES",
	"params": {}
}

Success payload ​

json
{
	"bridgeVersion": "2.0.0",
	"host": {
		"platform": "android",
		"vendor": "philips",
		"model": "65HFL6214U"
	},
	"capabilities": {
		"actions": {
			"LAUNCH_APP": true,
			"CAN_LAUNCH_APP": true,
			"LAUNCH_TV": true,
			"OPEN_SYSTEM_SETTINGS": true,
			"OPEN_MANUFACTURER_SETTINGS": true,
			"PURGE_DATA": true,
			"SWITCH_INPUT_SOURCE": false,
			"HOTSPOT_GET": true,
			"HOTSPOT_SET": true
		},
		"features": {
			"hasTvTuner": true,
			"hasSoftAp": false,
			"hasPurge": true
		},
		"manufacturerSettings": {
			"targets": ["default", "professional"],
			"vendors": ["philips"]
		},
		"inputSources": {
			"supported": false,
			"sources": []
		},
		"appLaunch": {
			"mode": "allowlist",
			"allowlist": ["com.netflix.ninja"],
			"denylist": [],
			"canQueryPerApp": true
		}
	}
}

Notes ​

  • actions = support protocolaire.
  • features = disponibilite hardware reelle.
  • appLaunch.canQueryPerApp doit etre true si CAN_LAUNCH_APP est pleinement implemente.

2) CAN_LAUNCH_APP ​

Request ​

json
{
	"type": "TV_API_REQUEST",
	"requestId": "req_can_launch",
	"action": "CAN_LAUNCH_APP",
	"params": {
		"appId": "com.netflix.ninja",
		"dataUri": "optional://uri"
	}
}

Success payload ​

json
{
	"canLaunch": true,
	"resolvedAppId": "com.netflix.ninja"
}

ou

json
{
	"canLaunch": false,
	"reasonCode": "APP_NOT_INSTALLED"
}

Rules ​

  • Le host doit evaluer install state + policy locale.
  • En cas de doute temporaire (HOST_BUSY, TIMEOUT), preferer ok:false avec code explicite.

3) OPEN_SYSTEM_SETTINGS ​

Request ​

json
{
	"type": "TV_API_REQUEST",
	"requestId": "req_sys_settings",
	"action": "OPEN_SYSTEM_SETTINGS",
	"params": {}
}

Success payload ​

json
{
	"opened": true
}

Rules ​

  • Android: ouvrir les parametres systeme generiques.
  • Si non disponible sur le device: ok:false, code: NOT_AVAILABLE_ON_DEVICE.

4) OPEN_MANUFACTURER_SETTINGS ​

Request ​

json
{
	"type": "TV_API_REQUEST",
	"requestId": "req_manu_settings",
	"action": "OPEN_MANUFACTURER_SETTINGS",
	"params": {
		"target": "professional",
		"vendor": "philips",
		"section": "network"
	}
}

Success payload ​

json
{
	"opened": true
}

Rules ​

  • target autorises: default, professional, vendor-specific.
  • Philips: professional doit ouvrir les professional settings.
  • TCL: vendor-specific + vendor: tcl doit ouvrir les settings constructeur TCL.
  • Si combinaison invalide: ok:false, code: INVALID_PARAMS.

5) LAUNCH_TV ​

Request ​

json
{
	"type": "TV_API_REQUEST",
	"requestId": "req_launch_tv",
	"action": "LAUNCH_TV",
	"params": {
		"packageName": "optional.override"
	}
}

Success payload ​

json
{}

Rules ​

  • L'action represente un retour TV, pas un launch applicatif standard.
  • Le host choisit le package/intent final selon vendor/model.
  • Si tuner absent (dongle sans TV): ok:false, code: NOT_AVAILABLE_ON_DEVICE.

Backward Compatibility ​

  • Tant que migration en cours, il est acceptable de garder:
    • OPEN_SETTINGS (legacy)
  • Les nouveaux hosts doivent implementer prioritairement les actions v2 listĂ©es ci-dessus.

Validation Checklist (Host) ​

  1. INITIALIZE_HOST repond en moins de 1s.
  2. GET_HOST_CAPABILITIES repond avec actions et features coherents.
  3. CAN_LAUNCH_APP renvoie un reasonCode stable en cas de refus.
  4. OPEN_SYSTEM_SETTINGS ouvre un ecran systeme sur Android/Philips supportes.
  5. OPEN_MANUFACTURER_SETTINGS gere professional (Philips) et vendor-specific (TCL).
  6. LAUNCH_TV renvoie NOT_AVAILABLE_ON_DEVICE si pas de tuner.