HeimLink ty compatibility v1 2026.09.13

HeimLink `window.ty`

API 接口文档

面向控制页面的涂鸦 API 兼容命名空间。沿用现有认证设备会话，保留 window.rti。

38接口入口32有实现4不计划实现2暂不支持

当前实现快照 910148bd · 2026-09-14 更新产品级契约与 getDeviceInfo 返回字段。部分能力受设备、驱动或平台限制；不代表 DOWT 已可直接运行。

38 / 38 个 API

通用约定与支持边界

HeimLink 为双路浇花器实际使用的 38 个涂鸦原生 API 提供同名入口。32 项有宿主实现（部分受设备/平台限制），4 项明确 NOT_PLANNED，2 项当前 NOT_SUPPORTED。逐项权威清单见 API 入口。

这不是完整的涂鸦小程序运行时：没有 App/Page/setData、JSSDK、涂鸦账号、产品云身份或通用云 DP 日志。仅新增命名空间，不代表原 DOWT 包可直接运行，也没有新增浇花器硬件协议。现有 window.rti 签名、DP 名称、物理单位和 Base64 形态保持不变。

调用形态

同步接口直接返回快照或结果。一般异步方法接受 {...参数, success?, fail?, complete?}：成功只调用 success，失败只调用 fail，之后调用 complete，各一次。传入任何回调时返回 undefined；无回调时返回 Promise，失败会 reject。这样兼容 DOWT 的回调封装，以及 connectBLEDevice/getAnalyticsLogsStatusLog 的 Promise 用法。调用者必须处理 Promise 拒绝。

panel.initPanelKit 与 createWebviewContext 是例外：它们同步返回 NOT_PLANNED 对象。前者还支持 fail/complete 回调，避免原壳的无等待初始化调用留下未处理拒绝。不会提供假的 context.postMessage。

事件注册接受函数并返回 () => void，不自动回放。初始值通过对应查询获取。跨页面消息订阅随页面销毁清理；原生断连、状态通知不会扩展到其他设备。

统一失败

{
  success: false,
  errorCode: "NOT_PLANNED",
  errorMsg: "This API is intentionally not implemented in HeimLink.",
  api: "ty.getUserInfo",
  errMsg: "ty.getUserInfo:fail This API is intentionally not implemented in HeimLink."
}

NOT_PLANNED 表示明确不实现这项涂鸦平台能力。NOT_SUPPORTED 表示有业务意义但当前版本、驱动、参数或平台不支持，不能混同。网络、断连、权限、超时等故障使用各自错误码，不会归入“不计划实现”。通用失败还包括 BAD_REQUEST、DEVICE_SCOPE_VIOLATION、UNAUTHORIZED、NOT_CONNECTED、NOT_PAIRED、TIMEOUT、NETWORK_ERROR、PERMISSION_DENIED、CANCELLED、STORAGE_NOT_FOUND、DP 错误及 INTERNAL。

设备与状态

只接受 getLaunchOptionsSync().query.deviceId 提供的本地句柄。没有跨设备枚举、扫描或任意 GATT 权限。设备字段缺失时不伪造：不能把手机时区当设备时区、添加时间当激活时间、认证产品 hash 当涂鸦 productId。

数字 DP ID/code、类型、范围和读写权限来自当前设备已识别产品的 Git 锁定契约，不套用浇花器或其他同品类产品的 DP 表。schema.type === "raw" 保留 DOWT 启动过滤 RAW 查询的逻辑；RAW 值用偶数长度 hex。数值 DP 遵守涂鸦十进制 scale，例如 setpoint 21.5 摄氏度在 scale=2 时为 2150。不存在的 ID 失败；相同编号即使在同品类也可能有不同含义，必须使用产品匹配的控制 App。

getDeviceInfo 的顶层 productId 和 heimlink.productId 返回 HeimLink 产品字符串，例如 rtitek-therm-01，不是涂鸦云 PID，也不是认证 hash。heimlink.contractRevision 是正整数修订号，heimlink.contractDigest 是 64 位小写十六进制 SHA-256 摘要；它们标识本次 App 构建锁定的契约，不表示在线协商结果。无法可靠确定产品时返回 NOT_SUPPORTED，不按品类猜测。

例如 rtitek-therm-01 的 DP4 为 fan 枚举，rus695 的 DP4 为 childLock 布尔值且没有 fan。schema、DP 查询、写入和通知均按产品解释。离线缓存仅在产品及契约来源匹配时返回，否则为空；不会因此删除配对密钥或用户信息。

getDeviceInfo 的 heimlink.stateSource 区分 authenticated-live 与 last-known。dpsTime 不编造单 DP 时间。BLE 物理在线与完成安全配对是两个状态。publishCommands 复用设备驱动本身的写语义，不给 TRV901Z 的逐项 ACK 增加虚假的原子性保证。

同步快照与存储

同步 launch/system/storage 数据在页面业务脚本之前可用。返回拷贝，不允许页面修改快照对象来改宿主身份。系统变化更新镜像；原生 get/set/removeStorage 完成前刷新当前页镜像，并通知同范围其他页面。刚发起但未完成的异步写入，不保证立即可由 getStorageSync 看到。

数据按应用和本地设备记录隔离，跨页面/重启持久化，不访问宿主账号、密钥或任意 MMKV key。存储内容与种子中的文本安全转义，不能通过 </script> 或替换字符串元字符插入脚本。

网络与 DOWT 启动

当前 DOWT 中 getUserInfo 是非阻塞资料读取，失败仅记录日志；不是服务探测。getAppInfo.regionCode 用于服务选区，HeimLink 不伪造该字段，调用方采用缺失区域的回退路径。

真正的连通性检查是 ty.request 访问 RTI /v1/version，并检查状态码以及 service/version 字段。本层返回真实 HTTP 响应，不替调用者判断健康、不自动附加宿主秘密。HTTP 401/503 不等于传输失败，更不等于服务健康。产品服务所需的真实认证和产品上下文仍由业务层解决。

支持边界

NOT_PLANNED：getUserInfo、getAnalyticsLogsStatusLog、panel.initPanelKit、createWebviewContext；非定位的涂鸦权限 scope 也返回此结果。
NOT_SUPPORTED：当前 map.chooseLocation 和 device.getOTAUpdateInfo。前者不冒充 GPS 取点；后者不返回“无更新”，但可打开原生 OTA 页实际检查。
位置和触感依赖原生模块；旧二进制缺少模块时返回 NOT_SUPPORTED，必须重建 App。只请求前台定位，不请求后台位置。
纯浏览器中没有原生宿主时，ty 不复用 rti 的离线模拟设备来制造成功。

默认异步 RPC 超时 15 秒；BLE 连接 20 秒；定位/授权 62 秒；HTTP 使用自身 1..60000ms 超时加 2 秒交付预算。Promise 超时不会撤销已经提交到硬件的写入；查询/命令并非事务取消接口。

启动与系统5

已实现同步

`ty.getLaunchOptionsSync`

继承 ty 通用约定、安全模型和数据类型。

功能

读取当前设备页面的启动上下文。

请求字段

无参数。

返回字段

{query: {deviceId, ...页面查询参数}, path}；deviceId 是本地不透明句柄，不是涂鸦云设备 ID 或蓝牙地址。

错误与限制

无原生上下文时 NOT_SUPPORTED。

超时

同步，无 RPC 超时。

示例

const launch = ty.getLaunchOptionsSync();

NOT_PLANNED同步

`ty.panel.initPanelKit`

继承 ty 通用约定、安全模型和数据类型。

功能

明确拒绝初始化涂鸦 PanelKit。HeimLink 已拥有设备会话及配对界面。

请求字段

原调用的配置对象可以传入，但不会启动 PanelKit，也不会改变配对、离线遮罩或 OTA 策略。

返回字段

同步返回统一失败对象；传入 fail/complete 时异步调用它们，不调用 success。

错误与限制

NOT_PLANNED；不返回被忽略后产生未处理拒绝的 Promise。

超时

同步，无 RPC 超时。

示例

const result = ty.panel.initPanelKit({ deviceId });

已实现同步

`ty.getSystemInfoSync`

继承 ty 通用约定、安全模型和数据类型。

功能

读取真实手机系统与安全区快照。

请求字段

无参数。

返回字段

platform, system, language, timezoneId, theme, pixelRatio, screenWidth, screenHeight, windowWidth, windowHeight, statusBarHeight, safeArea。safeArea 含 top/right/bottom/left/width/height，单位为逻辑像素；是屏幕坐标矩形，不是 rti.insets。heimlink.uses24HourClock 为扩展字段。不伪造品牌、型号或涂鸦 SDK 版本。

错误与限制

无原生上下文时 NOT_SUPPORTED。

超时

同步，无 RPC 超时。

示例

const info = ty.getSystemInfoSync();

已实现回调 / Promise

`ty.getAppInfo`

继承 ty 通用约定、安全模型和数据类型。

功能

读取 HeimLink 宿主名称和版本，不伪造涂鸦账号服务区。

请求字段

仅通用回调参数。

返回字段

{appName, version, heimlink:{runtime:"heimlink", regionSource:"unavailable"}}。有实际配置才返回版本；不包含 regionCode。DOWT 会走缺少服务区时的回退，并通过真实 HTTP 探测服务。

错误与限制

通用错误。

超时

SDK 15 秒。

示例

const info = await ty.getAppInfo();

NOT_PLANNED回调 / Promise

`ty.getUserInfo`

继承 ty 通用约定、安全模型和数据类型。

功能

HeimLink 不实现涂鸦账号资料。

请求字段

仅通用回调参数。

返回字段

失败对象，不返回假用户，不调用成功回调。当前 DOWT 的此调用是非阻塞资料读取，不是服务连通性门禁。

错误与限制

NOT_PLANNED。

超时

SDK 15 秒。

示例

ty.getUserInfo({ fail: handleFailure });

设备与蓝牙13

已实现（有限字段）回调 / Promise

`ty.device.getDeviceInfo`

继承 ty 通用约定、安全模型和数据类型。

功能

读取当前绑定设备元数据、契约 schema 和状态。

请求字段

deviceId?；省略时使用当前会话。传入时必须是启动上下文的句柄。

返回字段

devId, deviceId, name, productId, schema, dps, dpCodes, dpsTime:{}, isOnline, deviceOnline, isCloudOnline:false, isLocalOnline:false, isShare:false, capability:1024。schema 使用当前已识别产品锁定契约的编号/code、权限及类型；RAW 为 hex，数值按 schema.scale 编码。同品类其他产品的 DP 表不能复用。

productId 为 HeimLink 产品字符串，不是涂鸦云 PID 或 hash。heimlink 包含 category, productId, contractRevision, contractDigest, transport, stateSource, unavailableFields；修订号是正整数，摘要是 64 位小写十六进制 SHA-256，表示当前 App 构建的契约 pin，不是设备在线协商的版本。

activeTime, devTimezoneId, latitude, longitude 缺失时不伪造；不把本地添加时间称为激活/配对时间。离线业务缓存只有在产品与契约来源匹配时返回，否则为空；绑定和用户信息不因此删除。

错误与限制

产品未知、身份冲突或缺少产品契约为 NOT_SUPPORTED，不按品类回退；设备已删除为 BAD_REQUEST；跨设备为 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

const info = await ty.device.getDeviceInfo({ deviceId });

已实现回调 / Promise

`ty.device.registerDeviceListListener`

继承 ty 通用约定、安全模型和数据类型。

功能

确认设备事件订阅范围；不创建第二条 BLE 监听。

请求字段

deviceIdList: [deviceId]，只接受当前设备一个句柄。

返回字段

{}。事件监听器可在此前或此后注册，均仅接收本会话设备。

错误与限制

空列表、其他设备或多个设备为 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

await ty.device.registerDeviceListListener({ deviceIdList: [deviceId] });

已实现事件

`ty.device.onDpDataChange`

继承 ty 通用约定、安全模型和数据类型。

功能

订阅本会话设备的已认证 DP 变化以及 queryDps 的查询结果。

订阅签名

callback(event)；返回退订函数。

事件字段

{deviceId, devId, dps}；dps 为数字 ID 字符串键的部分映射，RAW 为 hex，数值遵守 schema.scale。不自动回放初始状态；queryDps 可报告与已有值相同的数据。

错误与限制

无监听回放；不能把事件到达时间当作设备执行时间。

超时

订阅无 RPC 超时；调用退订函数或卸载页面时清理。

示例

const off = ty.device.onDpDataChange(event => update(event.dps));

已实现（BLE）回调 / Promise

`ty.device.publishCommands`

继承 ty 通用约定、安全模型和数据类型。

功能

通过当前认证设备会话下发控制指令。

请求字段

deviceId?, dps；mode 省略或 2；options 省略或空对象；pipelines 省略或包含 3（BLE）的数组。

返回字段

成功 {}，不返回乐观状态。数字 ID 映射至实际设备契约，RAW hex 转为现有 rti Base64；数值从缩放整数转为物理单位。HeimLink 会话保留原子 SET_STATE；TRV901Z 驱动为逐字段 ACK，可能部分提交，不提升其原子性。

错误与限制

DP_UNKNOWN, DP_READ_ONLY, DP_TYPE_MISMATCH, DP_VALUE_INVALID, NOT_CONNECTED, NOT_PAIRED；非 BLE 选择或扩展选项为 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

await ty.device.publishCommands({ deviceId, dps: { 1: "heat" }, mode: 2, pipelines: [3] });

已实现（支持主动读取的驱动）回调 / Promise

`ty.device.queryDps`

继承 ty 通用约定、安全模型和数据类型。

功能

主动读取指定 DP，并通过事件交付结果。

请求字段

deviceId?, dpIds: number[] 非空；queryType 省略或 0。

返回字段

成功 {} 不含 DP；值通过 onDpDataChange 返回。当前 HeimLink 驱动读取完整状态后筛选指定编号；TRV901Z 的 getState 只是报告缓存，不能当成主动查询。事件可能先于成功回调，需先订阅。

错误与限制

TRV901Z 或未返回全部指定 DP 为 NOT_SUPPORTED；未知 ID 为 DP_UNKNOWN。

超时

SDK 15 秒。

示例

await ty.device.queryDps({ deviceId, dpIds: [1, 2] });

已实现回调 / Promise

`ty.device.getBLEOnlineState`

继承 ty 通用约定、安全模型和数据类型。

功能

查询当前设备真实 BLE 物理连接状态。

请求字段

deviceId?。

返回字段

{isOnline:boolean}。其他设备的连接不会使当前设备在线；物理在线不代表已认证或控制命令一定可用。

错误与限制

通用设备范围错误。

超时

SDK 15 秒。

示例

const state = await ty.device.getBLEOnlineState({ deviceId });

已实现回调 / Promise

`ty.device.connectBLEDevice`

继承 ty 通用约定、安全模型和数据类型。

功能

定向连接本页面绑定设备并发现服务。

请求字段

deviceId?。

返回字段

{isOnline:boolean}。保留无回调时返回 Promise 的调用方式。连接成功不等于安全配对完成。

错误与限制

连接和权限失败如实返回，不能当作 NOT_PLANNED。

超时

SDK 20 秒。

示例

await ty.device.connectBLEDevice({ deviceId });

已实现（BLE）事件

`ty.device.onDeviceOnlineStatusUpdate`

继承 ty 通用约定、安全模型和数据类型。

功能

订阅本设备 BLE 在线状态变化。

订阅签名

callback(event)；返回退订函数。

事件字段

{deviceId, devId, online:boolean, heimlink:{transport:"ble"}}。不伪造涂鸦云在线、网关或 onlineType 枚举。不初始回放；用 getBLEOnlineState 查询当前值。

错误与限制

只报告当前设备的变化。

超时

订阅无 RPC 超时；调用退订函数或卸载页面时清理。

示例

const off = ty.device.onDeviceOnlineStatusUpdate(event => updateOnline(event.online));

已实现事件

`ty.device.onDeviceRemoved`

继承 ty 通用约定、安全模型和数据类型。

功能

订阅当前已保存设备被移除。

订阅签名

callback(event)；返回退订函数。

事件字段

{deviceId, devId}，均为本地句柄。事件不是删除命令；收到后原生设备页面将退出。

错误与限制

不返回原始蓝牙 locator。

超时

订阅无 RPC 超时；调用退订函数或卸载页面时清理。

示例

const off = ty.device.onDeviceRemoved(event => handleRemoved(event));

已实现回调 / Promise

`ty.device.renameDeviceName`

继承 ty 通用约定、安全模型和数据类型。

功能

修改当前设备在 HeimLink 中的本地名称。

请求字段

deviceId?, name：去除首尾空白后非空，原始长度最多 100 字符。

返回字段

{}，使用既有设备持久化流程；不改广播名、云端名或出水口别名。

错误与限制

空白名称 BAD_REQUEST；跨设备 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

await ty.device.renameDeviceName({ deviceId, name: "Garden timer" });

NOT_SUPPORTED回调 / Promise

`ty.device.getOTAUpdateInfo`

继承 ty 通用约定、安全模型和数据类型。

功能

OTA 查询有业务意义，但当前尚无等价的模块状态/可升级性查询。

请求字段

deviceId?。

返回字段

明确失败；不返回 [] 或 upgradeStatus:0 冒充“没有更新”。可用 openOTAUpgrade 进入原生页面进行实际检查。

错误与限制

NOT_SUPPORTED，不是 NOT_PLANNED。

超时

SDK 15 秒。

示例

ty.device.getOTAUpdateInfo({ deviceId, fail: handleFailure });

已实现回调 / Promise

`ty.device.openOTAUpgrade`

继承 ty 通用约定、安全模型和数据类型。

功能

打开当前设备的原生固件升级页面。

请求字段

deviceId?。

返回字段

{} 表示打开页面，不表示升级开始或成功；仍由原生页校验固件、设备家族、权限和版本。

错误与限制

通用设备范围/导航错误；不允许页面提供任意固件 URL 绕过校验。

超时

SDK 15 秒。

示例

await ty.device.openOTAUpgrade({ deviceId });

已实现回调 / Promise

`ty.device.openDeviceDetailPage`

继承 ty 通用约定、安全模型和数据类型。

功能

打开当前设备的 HeimLink 原生设置页。

请求字段

deviceId?。

返回字段

{}；不承诺提供涂鸦分享、账号或云自动化入口。

错误与限制

通用设备范围/导航错误。

超时

SDK 15 秒。

示例

await ty.device.openDeviceDetailPage({ deviceId });

本地存储4

已实现同步

`ty.getStorageSync`

继承 ty 通用约定、安全模型和数据类型。

功能

同步读取本应用、本设备的持久化数据镜像。

请求字段

字符串 key，不是 {key}。

返回字段

直接返回 JSON 值的拷贝，不包 {data}；缺失返回空字符串。0、false、null 不当作缺失。镜像在页面加载及原生提交事件后刷新。

错误与限制

空 key 或非字符串为 BAD_REQUEST；它不阻塞等待尚未完成的 setStorage。

超时

同步，无 RPC 超时。

示例

const theme = ty.getStorageSync("theme");

已实现回调 / Promise

`ty.getStorage`

继承 ty 通用约定、安全模型和数据类型。

功能

读取本应用、本设备的持久化存储。

请求字段

key：非空字符串，最多 256 字符。

返回字段

{data: JSON值}；读取时也刷新同步镜像。

错误与限制

缺失为 STORAGE_NOT_FOUND，不是成功的空值。

超时

SDK 15 秒。

示例

const result = await ty.getStorage({ key: "theme" });

已实现回调 / Promise

`ty.setStorage`

继承 ty 通用约定、安全模型和数据类型。

功能

写入本应用、本设备的持久化存储。

请求字段

key：1..256 字符；data：JSON 值，不接受 undefined。

返回字段

{}；提交成功并更新镜像后才成功。不同应用/设备隔离，同范围多个页面同步。每范围总 JSON 序列化内容上限 1 Mi 字符。

错误与限制

参数或配额错误为 BAD_REQUEST。

超时

SDK 15 秒。

示例

await ty.setStorage({ key: "theme", data: "dark" });

已实现回调 / Promise

`ty.removeStorage`

继承 ty 通用约定、安全模型和数据类型。

功能

移除本应用、本设备存储项。

请求字段

key：1..256 字符。

返回字段

{}；缺失也成功，完成前更新同步镜像。不允许操作宿主其他存储区域。

错误与限制

通用错误。

超时

SDK 15 秒。

示例

await ty.removeStorage({ key: "theme" });

网络与日志2

NOT_PLANNED回调 / Promise

`ty.getAnalyticsLogsStatusLog`

继承 ty 通用约定、安全模型和数据类型。

功能

明确拒绝涂鸦云端 DP 分析日志查询。

请求字段

可传原涂鸦查询对象；deviceId 若传入仍检查范围。

返回字段

失败对象，不返回空数组伪装“没有日志”。HeimLink 温控历史模型并不等价于 DOWT 浇水/流量/故障日志。

错误与限制

NOT_PLANNED。未来本地通用设备日志需独立定义，不代表日志能力整体永远不做。

超时

SDK 15 秒。

示例

try { await ty.getAnalyticsLogsStatusLog({ deviceId, dpIds: "1" }); } catch (error) { handleFailure(error); }

已实现（文本 HTTP）回调 / Promise

`ty.request`

继承 ty 通用约定、安全模型和数据类型。

功能

通过原生网络栈发起真实业务 HTTP 请求，包括 RTI /v1/version 探测。

请求字段

url 绝对 HTTPS URL；method 默认 GET，可为 GET/HEAD/POST/PUT/PATCH/DELETE/OPTIONS；header（兼容 headers）；data；timeout 1..60000ms；responseType 仅 text。

返回字段

{statusCode, data:string, header}。HTTP 4xx/5xx 仍是成功收到 HTTP 响应，调用者检查状态码和内容；不会伪造 service/version。GET/HEAD 对象编码为查询参数，POST 等对象默认 JSON，表单 content-type 时使用表单编码。请求体和响应体各限制 1 Mi 字符。

错误与限制

非法 URL/参数为 BAD_REQUEST；传输失败 NETWORK_ERROR；超时 TIMEOUT；页面关闭 CANCELLED。生产只允许 HTTPS，开发/preview 允许 HTTP；不允许 URL 内嵌凭据。不提供 RequestTask/abort、二进制或上传/下载接口。

超时

宿主默认 60 秒；SDK 多留 2 秒交付失败结果。

示例

ty.request({ url: "https://example.com/v1/version", success: inspectResponse, fail: handleFailure });

定位与权限4

已实现（定位）回调 / Promise

`ty.authorizeStatus`

继承 ty 通用约定、安全模型和数据类型。

功能

查询系统定位授权，不弹出授权框。

请求字段

scope.userLocation；Android 额外支持 scope.userPreciseLocation。

返回字段

{authorized, granted?, denied, canAskAgain}；权限尚未询问时省略 granted，不返回 granted:false，避免 DOWT 将其误判为明确拒绝并跳过授权。授权存在不等于定位服务开启或能取得位置。

错误与限制

其他涂鸦 scope 为 NOT_PLANNED；iOS 精确授权 scope 为 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

const state = await ty.authorizeStatus({ scope: "scope.userLocation" });

已实现（定位）回调 / Promise

`ty.authorize`

继承 ty 通用约定、安全模型和数据类型。

功能

请求前台定位授权。

请求字段

scope.userLocation；Android 额外支持 scope.userPreciseLocation。

返回字段

授权成功返回 {authorized, granted, denied, canAskAgain}；用户拒绝进入失败通道。不会请求后台定位。

错误与限制

PERMISSION_DENIED；其他 scope 为 NOT_PLANNED；iOS 精确授权 scope 为 NOT_SUPPORTED。

超时

SDK 62 秒（含授权交互）；位置采集本身最多 30 秒。

示例

ty.authorize({ scope: "scope.userLocation", success: onAuthorized, fail: handleFailure });

已实现（WGS84）回调 / Promise

`ty.map.getLocation`

继承 ty 通用约定、安全模型和数据类型。

功能

获取实际手机位置，不伪造设备安装位置。

请求字段

type 省略或 "wgs84"。

返回字段

{latitude, longitude, accuracy, altitude, speed, type:"wgs84"}；坐标为数值，精度/海拔/速度可为 null。前台授权后获取一次位置，定位采集最多 30 秒，完成/超时/页面关闭清理监听。

错误与限制

PERMISSION_DENIED, TIMEOUT, CANCELLED；非 WGS84 为 NOT_SUPPORTED。系统授权框由 OS 管理，页面关闭不能撤销已经显示的授权框。

超时

SDK 62 秒（含授权交互）；位置采集本身最多 30 秒。

示例

const position = await ty.map.getLocation({ type: "wgs84" });

NOT_SUPPORTED回调 / Promise

`ty.map.chooseLocation`

继承 ty 通用约定、安全模型和数据类型。

功能

地图选点具有业务意义，但当前 HeimLink 尚无原生地图选点界面。

请求字段

接受原调用配置，但目前不执行选点。

返回字段

明确失败，不用当前 GPS 坐标冒充用户选点，也不打开一个无法回传结果的外部地图后声称成功。

错误与限制

NOT_SUPPORTED，不是 NOT_PLANNED。

超时

SDK 15 秒。

示例

ty.map.chooseLocation({ fail: handleFailure });

页面与导航4

已实现（已注册页面）回调 / Promise

`ty.navigateTo`

继承 ty 通用约定、安全模型和数据类型。

功能

在当前设备的 Web App 页面栈中打开声明的路由。

请求字段

url：manifest 中的 route 名或对应文件路径，可附查询参数。

返回字段

{}；查询参数在目标页的 getLaunchOptionsSync().query 中返回。这里只支持 HeimLink 注册的页面，不提供涂鸦 Page/setData 或 webview:// 路由壳。

错误与限制

未知路由、外部 URL、父级跳转为 BAD_REQUEST；尝试覆盖 id/deviceId/route/tyParams 为 DEVICE_SCOPE_VIOLATION。

超时

SDK 15 秒。

示例

await ty.navigateTo({ url: "/settings?section=general" });

已实现回调 / Promise

`ty.navigateBack`

继承 ty 通用约定、安全模型和数据类型。

功能

返回当前设备页面栈中的前若干页。

请求字段

delta 默认为 1，必须为 1..100 整数且不超过当前设备栈深度。

返回字段

{}。不会把返回一页当成退出整个设备页面；根页应使用 exitMiniProgram。

错误与限制

超过栈深度或非法 delta 为 BAD_REQUEST。

超时

SDK 15 秒。

示例

await ty.navigateBack({ delta: 1 });

已实现回调 / Promise

`ty.exitMiniProgram`

继承 ty 通用约定、安全模型和数据类型。

功能

退出整个设备控制页面栈，回到宿主上一级。

请求字段

仅通用回调参数。

返回字段

{} 表示发起离开设备控制流程，不退出手机 App、不删除设备、不主动解绑。

错误与限制

不存在可返回的父设备页面时 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

ty.exitMiniProgram({ fail: handleFailure });

NOT_PLANNED同步

`ty.createWebviewContext`

继承 ty 通用约定、安全模型和数据类型。

功能

不提供涂鸦原生 Page 逻辑层对子 WebView 的上下文对象。

请求字段

原调用的 WebView 标识可传入。

返回字段

同步返回统一失败对象，不含 postMessage。当前页面使用 window.ty/window.rti 调用宿主；不得把 window.postMessage 回环当作跨层通信。

错误与限制

NOT_PLANNED。完整 App/Page/JSSDK 和嵌套 WebView 壳不在此兼容层内。

超时

同步，无 RPC 超时。

示例

const context = ty.createWebviewContext("webview-container");

系统交互6

已实现（平台限制）回调 / Promise

`ty.openSystemSettingPage`

继承 ty 通用约定、安全模型和数据类型。

功能

打开手机系统设置。

请求字段

Android scope：Settings（默认）、Settings-Bluetooth、Settings-WiFi、Settings-Location。

返回字段

成功 {}；Android 打开对应系统设置页；iOS 受平台限制只打开当前 App 的设置页，不使用私有设置 URL。

错误与限制

未支持的 Android 目标为 NOT_SUPPORTED；系统打开失败如实返回。

超时

SDK 15 秒。

示例

await ty.openSystemSettingPage({ scope: "Settings-Location" });

已实现回调 / Promise

`ty.openAppSystemSettingPage`

继承 ty 通用约定、安全模型和数据类型。

功能

打开 HeimLink 自身的系统权限设置页。

请求字段

可传原 scope；当前各 App 设置 scope 均落在同一个 App 设置入口，不承诺直达某个开关。

返回字段

{} 表示已请求打开设置页，不表示权限已变更。

错误与限制

系统打开失败如实返回。

超时

SDK 15 秒。

示例

await ty.openAppSystemSettingPage({ scope: "App-Settings" });

已实现回调 / Promise

`ty.showToast`

继承 ty 通用约定、安全模型和数据类型。

功能

显示宿主原生消息提示。

请求字段

title：1..500 字符；duration 默认 1500ms，范围 1..10000；icon 的 success/error 映射提示类型，其余为普通提示。

返回字段

{} 表示提示已提交，不等待消失；不承诺涂鸦精确视觉样式、图片或遮罩。

错误与限制

参数错误 BAD_REQUEST。

超时

SDK 15 秒。

示例

ty.showToast({ title: "Saved", icon: "success" });

已实现回调 / Promise

`ty.setClipboardData`

继承 ty 通用约定、安全模型和数据类型。

功能

将文本写入系统剪贴板。

请求字段

data 字符串，最多 1 Mi 字符，可为空。

返回字段

{}；不提供读取剪贴板能力。

错误与限制

参数错误 BAD_REQUEST；系统失败如实返回。

超时

SDK 15 秒。

示例

await ty.setClipboardData({ data: deviceId });

已实现回调 / Promise

`ty.vibrateShort`

继承 ty 通用约定、安全模型和数据类型。

功能

请求系统短触感反馈。

请求字段

type 为 light（默认）、medium、heavy。

返回字段

{}；设备硬件、系统触感设置及低电量策略可能使其无可感知反馈，不保证物理振动。

错误与限制

非法 type 为 BAD_REQUEST；原生模块缺失为 NOT_SUPPORTED。

超时

SDK 15 秒。

示例

ty.vibrateShort({ type: "light", fail: handleFailure });

已实现事件

`ty.onKeyboardHeightChange`

继承 ty 通用约定、安全模型和数据类型。

功能

订阅系统键盘显示/隐藏高度变化。

订阅签名

callback(event)；返回退订函数。

事件字段

{height:number}，逻辑像素；隐藏时为 0。来源为原生 keyboardDidShow/keyboardDidHide，不是安全区 inset；不提供逐帧动画或 willShow/willHide。

错误与限制

遵循平台键盘事件可用性，不初始回放。

超时

订阅无 RPC 超时；调用退订函数或卸载页面时清理。

示例

const off = ty.onKeyboardHeightChange(event => setHeight(event.height));

共享错误码

ty 的失败字段是 errorCode，rti 及 bridge 错误封套使用 code。错误码可用于分支判断；错误描述不是稳定标识。

code	含义
`NOT_CONNECTED`	设备未连接
`TIMEOUT`	调用超时（默认值见各接口文档）
`BLE_IO_ERROR`	BLE 读写/通信失败（兜底错误）
`BAD_REQUEST`	请求参数错误，或宿主未接入对应处理器
`UNAUTHORIZED`	会话已失效（WebView 卸载 / 会话已释放后再调用）
`DEVICE_SCOPE_VIOLATION`	越权访问绑定设备以外的设备
`VERSION_UNSUPPORTED`	版本不支持（`handshake` 协商失败时返回）
`NOT_PAIRED`	设备未完成配对 / SecureChannel 未建立
`DP_UNKNOWN`	`publishDps` 使用了当前认证品类不存在的 DP 名
`DP_READ_ONLY`	`publishDps` 尝试写只读 DP
`DP_TYPE_MISMATCH`	DP 的值类型与品类契约不一致
`DP_VALUE_INVALID`	DP 值超出范围，或 byte string / tuple 长度不合法
`NOT_PLANNED`	明确不计划在 HeimLink 实现的涂鸦平台能力，不代表临时故障
`NOT_SUPPORTED`	有业务意义，但当前版本、驱动、参数或平台不支持
`PERMISSION_DENIED`	所需系统权限未获准
`NETWORK_ERROR`	HTTP 传输失败；收到 4xx/5xx 响应本身不属于传输失败
`STORAGE_NOT_FOUND`	当前应用及设备范围内没有指定存储项
`CANCELLED`	操作被取消，如页面销毁时撤销挂起的原生请求
`INTERNAL`	宿主内部错误（兜底）

安全与作用域

window.ty 仍绑定当前设备：启动时发放本地不透明句柄，原生将其映射至当前会话，不能通过 payload、设备列表或 URL 查询参数改写作用域。该句柄不是涂鸦云身份，不能当作外部设备服务的身份凭据；本次不改变既有 rti 字段。

存储按应用和本地设备记录隔离，仅暴露页面自身写入的 JSON。页面初始化数据按挂载实例隔离并安全转义。设备状态与控制仍经已认证的设备会话；系统/存储/HTTP 不要求初始化 BLE。

HTTP 不启动入站端点，不自动附加宿主 token、密钥或账号信息；只发送调用者的参数和 headers，禁用默认凭据。生产限 HTTPS，development/preview 可用 HTTP；URL 不允许内嵌用户名密码。当前没有业务域名 allowlist，因此已授权运行的控制页面可以请求任意允许协议的地址，包括局域网地址；不应把此能力开放给未经审核的页面。

定位按系统权限获取真实手机位置，只请求前台授权；剪贴板只写不读。页面销毁清理事件、取消 HTTP 与位置采集。已出现的系统权限框和已经提交的设备写入不能通过销毁页面撤回。

NOT_PLANNED 不表示授权拒绝或临时故障。对当前不具备的地图选择及 OTA 状态查询返回 NOT_SUPPORTED，不能假装成功。详见兼容层限制。

兼容数据类型

ty.* RPC 采用同一个 call/result 封套，消息 method 与公开完整名字相同（例如 ty.request）。同步接口和事件订阅不发送 RPC。ty.systemInfoChange 更新同步系统快照；ty.storageChange 的 {revision, data} 更新整个隔离存储镜像，属于 SDK 内部维护事件，不是新增公开订阅方法。其他 ty 事件字段见逐接口文档。

ty 失败对象为 {success:false, errorCode:string, errorMsg:string, api:string, errMsg:string}；errorCode 是封套 error.code，errorMsg 是 error.message。新增分类包括 NOT_PLANNED、NOT_SUPPORTED、PERMISSION_DENIED、NETWORK_ERROR、STORAGE_NOT_FOUND、CANCELLED，含义见 ty 通用约定。这些字段不改变 rti 的 {code,message} 拒绝形态。

ty 数字 DP 采用 Record<string, string | number | boolean>；键为实际契约数字编号字符串，RAW 为 hex、数值按十进制 schema.scale 编码。下文 DP 名称/物理单位/Base64 规则仍专指 rti。