应用开发基本信息

本页汇总了开发和使用HTML5应用所需的技术信息。基本机制非常简单：在autorun.txt中指定要启动的应用auid，在manifest.json中指定应用信息和启动方法。将USB驱动器插入显示器后，将根据autorun.txt启动HTML5应用。

1. 文件结构规则

开发HTML5应用时，需遵循以下目录文件结构规则。

			
USB:/
　├ sony/
　│　├ autorun.txt          // 指定应用ID
　│　└ apps/
　│　　　└ webapps/
　│　　　　　├ <app name 1>/  // 应用文件夹名称
　│　　　　　│　└ app/        // 应用目录
　│　　　　　│　　├ manifest.json
　│　　　　　│　　└ doc/      // 文档根目录
　│　　　　　├ <app name 2>/
　│　　　　　│　└ app/
　│　　　　　│　　├ manifest.json
　│　　　　　│　　└ doc/
　│　　　　　└ ...
　└ media/
　　　├ video1.mp4
　　　└ video2.mp4

		

HTML5应用名称可任意指定。
可在/sony/apps/webapps/目录下放置多个HTML5应用。

提示
可运行的应用为1个。如需同时将多个HTML5应用安装到显示器内置存储，可在/sony/apps/webapps/目录下放置多个应用。

2. 静态文件的配置

HTML、JavaScript、CSS、图像（.html、.js、.css、.png等）等静态文件的配置位置和访问方法因HTML5应用的启动方式而异。

配置在外部Web服务器的情况

将静态文件配置在外部Web服务器上，并在manifest.json的web_url属性中指定URL。

配置在USB驱动器或显示器内置存储的情况

静态文件配置在/doc/文件夹中，并在manifest.json的local_path属性中指定路径。

例　静态文件配置（local_path）

file://localhost/doc/<file_name>.html

3. 视频等大容量文件的配置

配置在外部Web服务器时，与静态文件相同，在manifest.json的web_url属性中指定URL。
配置在USB驱动器或显示器内置存储时，放置在/media/文件夹中，显示器将自动访问，无需在manifest.json中指定属性。

例　视频文件配置

file://localhost/media/<file_name>.mp4

autorun.txt基于JSON格式的键/值格式进行记述。

所有值均为字符串类型，仅auid属性为必填项。有关详细信息及可选属性，请参阅以下内容。还可以指定HTML5应用的操作（启动・安装・删除）。

autorun.txt结构及属性

结构

在autorun.txt中指定要启动的HTML5应用的ID auid。显示器插入USB驱动器后，将读取autorun.txt，并与各应用的manifest.json中的auid进行匹配，启动匹配成功的HTML5应用。

autorun.txt与manifest.json的auid对应关系

			
USB:/ 
/sony/
　　├ autorun.txt // auid
　　├ apps/webapps/
　　　　　　　├ <app name 1>/app/manifest.json // auid
　　　　　　　├ <app name 2>/app/manifest.json // auid_1
　　　　　　　├ :

		

提示
autorun.txt中只能指定1个auid。仅在同时将多个HTML5应用安装到显示器内置存储时，才会放置多个应用。

记述示例

autorun.txt的记述示例

JSON

{
  "action": "auid",              // auid: 启动 / copyapp: 安装 / removeapp: 删除
  "auid": "<app ID>",            // 必填项。要启动的应用ID
  "copyapp": {
    "app": "<app ID>",           // 要安装到内置存储的应用ID
    "media": "nocopy",           // copy / sync / nocopy
    "mode": "confirm",           // confirm / auto / dryrun
    "startup_uri": "<app ID>",   // 电源联动启动的应用ID
    "home_menu_app": "false"     // 主页菜单图标显示 true / false
  },
  "removeapp": {
    "app": "<app ID>",           // 要删除的应用ID
    "media": "keep",             // keep / remove
    "mode": "confirm"            // confirm / auto / purge
  }
}

{
  "action": "auid",              // auid: 启动 / copyapp: 安装 / removeapp: 删除
  "auid": "<app ID>",            // 必填项。要启动的应用ID
  "copyapp": {
    "app": "<app ID>",           // 要安装到内置存储的应用ID
    "media": "nocopy",           // copy / sync / nocopy
    "mode": "confirm",           // confirm / auto / dryrun
    "startup_uri": "<app ID>",   // 电源联动启动的应用ID
    "home_menu_app": "false"     // 主页菜单图标显示 true / false
  },
  "removeapp": {
    "app": "<app ID>",           // 要删除的应用ID
    "media": "keep",             // keep / remove
    "mode": "confirm"            // confirm / auto / purge
  }
}

配置到显示器内置存储时的控制属性

1. “copyapp”

将HTML5应用配置到显示器内置存储时，可组合使用以下属性更精细地控制安装时的操作。

属性	必需/可选	默认值	说明
action	可选	auid	插入USB驱动器时的操作设置控制插入USB驱动器时自动执行的处理（autorun.txt的Key设置）。可在autorun.txt中设置的Key如下： auid: 启动指定auid的HTML5应用（必需）。 copyapp: 将HTML5应用安装到显示器。 removeapp: 从显示器卸载HTML5应用。
auid	必需		指定auid。
app	可选		指定要安装的HTML5应用的auid或auid列表。
media	可选	nocopy	指定USB:/media目录的安装操作为USB驱动器内的/media目录指定以下操作之一： copy: 从USB:/media复制文件。如果显示器端存在同名文件，则用USB:/media的文件覆盖。 sync: 在显示器端和USB:/media之间同步文件。显示器端会删除USB:/media中不存在的文件。显示器端会删除USB:/media中不存在的文件。 nocopy: 不复制文件。
mode	可选	confirm	指定HTML5应用安装流程中的UI操作在安装流程中将UI行为指定为以下之一： confirm: 在安装流程中显示确认对话框。 auto: 在安装流程中不显示对话框（自动执行）。 dryrun: 不安装，启动startup_uri中指定的HTML5应用。
startup_uri	可选		指定与startup_uri对应的auid。
home_menu_app	可选	FALSE	指定主页菜单（Leanback Launcher）图标的操作如果指定auid或uri，则会在主页菜单中显示用于启动它的图标。如果指定false或空字符串，则不显示图标。

关于”startup_uri”

startup_uri是copyapp的子属性。在startup_uri中指定auid后，可设置为在显示器开机时自动启动该HTML5应用。

JSON

{
  "action": "copyapp",
  "auid": "<app ID>",
  "copyapp": {
    "app": "<app ID>",
    "startup_uri": "<app ID>"  // 可选。使用电源联动启动时指定
  }
}

{
  "action": "copyapp",
  "auid": "<app ID>",
  "copyapp": {
    "app": "<app ID>",
    "startup_uri": "<app ID>"  // 可选。使用电源联动启动时指定
  }
}

2. “removeapp”

通过组合使用以下属性，可更精细地控制卸载时的操作。

属性	必需/可选	默认值	说明
app	可选		指定要删除的HTML5应用信息。
media	可选	keep	指定USB:/media的卸载操作 keep: 不删除AV媒体文件。 remove: 删除AV媒体文件。
mode	可选	confirm	指定HTML5应用卸载流程中的UI操作 confirm: 在卸载流程中显示确认对话框。 auto: 在卸载流程中不显示对话框（自动执行）。 purge: 卸载所有已安装的HTML5应用和AV媒体文件。在流程中显示确认对话框。

manifest.json用于指定auid、显示名称、启动URL、启动画面图像等应用信息。manifest文件必须命名为”manifest.json”。

示例　web_url

JSON

{
  "name": {
    "default": "en_US",
    "en_US": "<app display name>"　　// 主页菜单等中显示的应用名称
  },
  "auid": "com.example.myapp",　　// 反向域名格式（示例　http://example.com → com.example）
  "version": "1.0",
  "manifest_version": "1.0",
  "app": {
    "launch": {
      "web_url": "http://example.com/myapp"　// 指定URL
    }
  },
  "splash": "splash.jpg",
  "minimum_web_platform_version": "1.0"
}

{
  "name": {
    "default": "en_US",
    "en_US": "<app display name>"　　// 主页菜单等中显示的应用名称
  },
  "auid": "com.example.myapp",　　// 反向域名格式（示例　http://example.com → com.example）
  "version": "1.0",
  "manifest_version": "1.0",
  "app": {
    "launch": {
      "web_url": "http://example.com/myapp"　// 指定URL
    }
  },
  "splash": "splash.jpg",
  "minimum_web_platform_version": "1.0"
}

示例　local_path

JSON

{
  "name": {
    "default": "en_US",
    "en_US": "<app display name>"　　 // 主页菜单等中显示的应用名称
  },
  "auid": "<app ID>",　
  "version": "1.0",
  "manifest_version": "1.0",
  "app": {
    "launch": {
      "local_path": "file://localhost/doc/index.html"  // 通过USB或内置存储启动的HTML文件路径
    }
  },
  "splash": "splash.jpg",
  "minimum_web_platform_version": "1.0"
}

{
  "name": {
    "default": "en_US",
    "en_US": "<app display name>"　　 // 主页菜单等中显示的应用名称
  },
  "auid": "<app ID>",　
  "version": "1.0",
  "manifest_version": "1.0",
  "app": {
    "launch": {
      "local_path": "file://localhost/doc/index.html"  // 通过USB或内置存储启动的HTML文件路径
    }
  },
  "splash": "splash.jpg",
  "minimum_web_platform_version": "1.0"
}

查看manifest.json的属性详情

属性			必需/可选	说明
name			必需	指定HTML5应用名称。
	default		必需	既指定默认显示语言（例如：en_US）。 ※必须定义与指定语言对应的HTML5应用名称。
	en_US			指定HTML5应用名称语言（英语）。
	ja_JP			指定HTML5应用名称语言（日语）。
	…			※根据需要，按上述方式列出每种语言的HTML5应用名称。
auid			必需	指定auid。
version			必需	指定HTML5应用的版本号。
manifest_version			必需	指定manifest的版本。※请指定1.0
app			必需	指定HTML5应用信息。
	launch		必需	使用以下方法之一指定启动页面。
		local_path		启动页面指定方法1：使用以 file:// 开头的文件路径指定。
		web_url		启动页面指定方法2：http://或 https:// 开头的URL。使用https://时，请注意以下事项: 1: 显示器的日期和时间设置必须准确 2: 使用正式颁发的服务器证书 3: 通过 [Pro 设置] → [HTML5 平台] 将根证书导入显示器
		cold_boot_delay	可选	启动页面指定方法3：指定显示器首次开机时HTML5应用的启动延迟时间（以毫秒为单位）。默认值为0。用于指定等待网络连接建立的时间等。
	screen		可选	指定屏幕设置。
		orientation	可选	指定显示方向。 0：正常方向（默认值） 90：顺时针旋转90度 270：顺时针旋转270度（逆时针旋转90度）无法指定180度。提示：建议通过 [Pro 设置] 进行配置。* 操作步骤：[Pro 设置]→[HTML5平台]→[Web应用显示方向] → 启用[优先Web应用]并设置方向。 ※Pro 设置优先。
		bgcolor	可选	指定背景色（例如：#FFFFFFFF）。
	window_close		可选	指定window.close()的操作。 0：无效（默认值） 1：有效
	attachkeys		可选	指定HTML5应用可获取的附加按键事件。请参阅此处。
	alert_dialog		可选	指定警告对话框的显示操作。 ignore：不显示警告对话框。 *如果未指定`alert_dialog`, 则显示警告对话框。
	confirm_dialog		可选	指定确认对话框的显示操作。 yes：显示（默认值） no：不显示
	prompt_dialog		可选	设置在输入对话框的输入栏中显示的字符串。指定字符串后, 无需用户操作即可确认输入内容。
	initial_input		可选	BZ40P / BZ35P / BZ30P: 不支持指定默认应用的显示画质设置。 video：适合视频显示的设置（默认值） photo：适合静止图像显示的设置
	fixed_input		可选	BZ40P / BZ35P / BZ30P: 不支持指定HTML5应用切换内容时的操作。指定在静止图像/视频/外部输入之间切换时的操作。根据内容更改显示画质设置（默认值）。 true：无论内容如何, 都不更改显示画质设置。 ※可抑制切换时的闪烁。
	fixed_picture_mode		可选	BZ40P / BZ35P / BZ30P: 不支持画质模式固定设置。无论播放内容如何，都固定[画质模式]。如果指定了,picture_mode，则initial_input和fixed_input的设置无效。 none：根据播放内容自动切换[画质模式]（默认值）。 game：始终将画质模式固定为[Game]。 ※如果希望减少HDMI延迟, 请使用此选项。
	onsleep		可选	指定通过遥控器关闭显示器电源时的内置浏览器操作。 stop：停止浏览器操作（默认值）。 pause：暂停浏览器操作。在电源开启时恢复。 continue：继续浏览器操作。
	background		可选	指定显示器处于后台时的JavaScript操作。 ※例如：在HTML5应用运行时启动YouTube等情况。 true：继续运行JavaScript。。 false：停止JavaScript（默认值）。
	cache_files_and_images		可选	指定缓存操作。 true：启用缓存（默认值）。 ※启用HTML、CSS、JavaScript以及视频/静止图像内容的缓存。 false：禁用缓存。
	video		可选
		multiple_video_tags	可选	BZ40P / BZ35P / BZ30P: 不支持指定同时使用多个video元素。 true：允许同时使用多个video元素。 ※当为true时，上限为2K视频 x 2个，不支持4K + 2K。 false：不允许同时使用。 ※创建多个video元素时，后创建的优先, 采用”后胜方式”（默认值）。
	error_page		可选	指定错误页面。
		default	可选	指定HTTP错误发生时的页面。可用的协议为 http://, https://, file://。提示：http:// example.com/error/404.html
		detail	可选	指定各HTTP状态码的错误页面可用的 URL 协议为 http://, https://, file://。 403、500 和超时错误时的指定示例，请参阅此处。
splash			可选	指定HTML5应用内的启动画面图像文件名，例如splash.jpg。
reboot			可选	指定HTML5应用崩溃时的操作。 true：自动重启HTML5应用。 alse：不执行任何操作（默认值）。
minimum_web_platform_version			必需	指定Web app runtime的版本。 ※请在JavaScript中确认`navigator.userAgent` 例如：1.0等）。

遥控指令

遥控指令列表和示例HTML5应用已准备就绪。

遥控器示例ダウンロード

可在manifest.json的attachkeys属性中指定显示器遥控器的遥控指令（[主页]键、频道操作键、方向键等），并在HTML5应用中接收。

示例　各遥控指令的指定

JSON

"app": {
  "attachkeys": [
    "VK_HOME",   // 主页按钮
    "VK_CH_UP",  // 频道上
    "VK_CH_DOWN"  // 频道下
  ]
},

"app": {
  "attachkeys": [
    "VK_HOME",   // 主页按钮
    "VK_CH_UP",  // 频道上
    "VK_CH_DOWN"  // 频道下
  ]
},

示例　遥控指令的接收

JSON

document.onkeydown = function(e) {
  if (e.keyCode === VK_HOME) {
    // 请在此处实现主页键行为。
  }
}

document.onkeydown = function(e) {
  if (e.keyCode === VK_HOME) {
    // 请在此处实现主页键行为。
  }
}

403、500和超时错误时的指定示例

以下显示HTTP错误发生时要显示的页面的指定示例。

JSON

[
  {“status_code” : “403”, “path” : “http://example.com/doc/403.html”},
  {“status_code” : “500”, “path” : “file://localhost/doc/500.html”},
  {“status_code” : “timeout”, “path” : “file://localhost/doc/timeout.html”}
]

[
  {“status_code” : “403”, “path” : “http://example.com/doc/403.html”},
  {“status_code” : “500”, “path” : “file://localhost/doc/500.html”},
  {“status_code” : “timeout”, “path” : “file://localhost/doc/timeout.html”}
]

在一般浏览器和Web环境中普遍支持的规范和功能中，显示器支持的内容存在部分限制。详情请确认W3C/HTML5 API规范。

提供定制对象标签和JavaScript API

BRAVIA商用显示器提供独有的定制对象标签与JavaScript API。

定制对象标签和JavaScript API列表

定制对象标签

通过在<object>标签中指定以下MIME类型，可以在HTML5应用内显示各种媒体。与JavaScript控制代码结合使用。

示例

application/x-decimated-video　在HTML5应用内显示HDMI输入视频
application/x-multicast-video　组播视频播放
application/x-4k-photo　显示高质量图像

JavaScript API

JavaScript API是用于从HTML5应用内获取显示器状态和控制显示器的接口。

示例

sony.tv.DirectoryReader　获取目录内的文件列表
sony.tv.systemevents　检测显示器系统事件（输入切换、电源状态等）
sony.tv.picturemode 　获取和更改画质模式

通过有线或Wi-Fi使用adb命令可进行远程调试和日志获取。适用于存储在内置存储、USB驱动器或外部Web服务器中的HTML5应用。

注意
不支持USB数据线调试。

安装方法

要使用调试功能，请按以下步骤操作。

显示器：启用[开发者选项]
操作步骤：[设置]→[开发者选项]→启用[开发者选项]。
PC：安装adb命令
在PC上安装Android SDK Platform-Tools以使用adb命令。
将PC连接到显示器
运行以下命令，通过以太网或Wi-Fi将PC连接到显示器。

adb connect <显示器的IP地址>

日志获取方法

控制台日志方法
显示器支持控制台日志。使用以下命令获取日志。
Logcat不仅显示 javascript console.log() , 还显示其他系统日志。

			
$ adb logcat -c                   # 清除缓冲区
$ adb logcat -v time              # 获取日志
$ adb logcat -v time > log.txt    # 使用 ">"（重定向）保存数据

日志停止方法
按[Control] + [c]停止。

远程调试方法

显示器支持远程调试功能。可从PC浏览器调试在显示器上运行的HTML5应用。

WebAppRuntime v1.4.10或更高版本

1. 运行命令
使用<HTML5应用url>指定应用并运行以下命令后，远程调试功能将启用，WebAppRuntime将启动。

$ adb shell am start -a android.intent.action.VIEW -n com.sony.dtv.browser.webappruntime/.WebAppRuntimeActivity –es uri -e args ‘–remote-debugging-socket-name=tvsdk-debugging-socket’

2. 显示Devices画面

在PC上打开Chrome，在地址栏中输入chrome://inspect/#devices，将显示Devices画面。

3. 运行远程调试
点击Devices画面上型号名称下方的”inspect”按钮。新的DevTools窗口将打开并开始远程调试。
– true　启用缓存。默认值为”true”。
– false　禁用缓存。

WebAppRuntime v1.3.22或更早版本

1. WebAppRuntime的启动
运行以下命令后，远程调试功能将启用，WebAppRuntime将启动。

$ adb shell am start -a android.intent.action.VIEW -n com.sony.dtv.browser.webappruntime/.WebAppRuntimeActivity -e args ‘–remote-debugging-socket-name=tvsdk-debugging-socket’
$ adb forward tcp:9222 localabstract:tvsdk-debugging-socket

2. 连接PC和显示器
在PC上启动Chrome，在地址栏中输入 “http//localhost:9222”, 即可连接PC和显示器。

3. 显示控制台日志
Chrome浏览器中将显示调试信息和控制台日志。

缓存模式的禁用

如需禁用缓存功能，可在manifest.json中进行配置。要在页面加载时删除缓存的图像和文件，请将manifest.json的cache_files_and_images属性设置为false。

JSON

{
  "app": {
    "cache_files_and_images" : false // 禁用缓存机制
  }
}

{
  "app": {
    "cache_files_and_images" : false // 禁用缓存机制
  }
}

应用开发基本信息

文件结构

1. 文件结构规则

2. 静态文件的配置

配置在外部Web服务器的情况

配置在USB驱动器或显示器内置存储的情况

3. 视频等大容量文件的配置

使用 autorun.txt 指定应用启动

autorun.txt结构及属性

结构

记述示例

配置到显示器内置存储时的控制属性

1. “copyapp”

关于”startup_uri”

2. “removeapp”

使用 manifest.json 指定信息

查看manifest.json的属性详情

遥控指令

403、500和超时错误时的指定示例

标准web功能的限制

提供定制对象标签和JavaScript API

定制对象标签

示例

JavaScript API

示例

html5应用调试方法（Android TV OS 12或更早版本）

安装方法

日志获取方法

远程调试方法

WebAppRuntime v1.4.10或更高版本

WebAppRuntime v1.3.22或更早版本

缓存模式的禁用