# SDK JavaScript API 总览

> 选择正确的执行上下文，了解 API 域和返回类型，并查阅各项能力的完整参考。

Source: https://console.getchrovia.com/zh/docs/sdk-javascript-api

浏览器直接提供 `globalThis.chrovia`，不需要导入 SDK。通常在 **Provision 扩展的 Service Worker** 使用。按[开发入门](https://console.getchrovia.com/zh/docs/sdk-getting-started)和[插件安装指南](https://console.getchrovia.com/zh/docs/sdk-plugins)创建插件。

## API 域与参考

| API 域 | 能力 | 参考 |
| --- | --- | --- |
| `chrovia.prefs` | `extendedPrefs` | [EP 存储、get/set/remove、Profile 设置](https://console.getchrovia.com/zh/docs/sdk-extended-preferences) |
| `chrovia.network` | `networkIntercept` | [选项、请求解析、取消与 Worker 生命周期](https://console.getchrovia.com/zh/docs/sdk-network-intercept) |
| `chrovia.messaging` | `messaging` | [通道、发布订阅和启动回复](https://console.getchrovia.com/zh/docs/sdk-messaging) |
| `chrovia.ui` | `nativeDialog` | [Alert、confirm 和 notify](https://console.getchrovia.com/zh/docs/sdk-native-dialog) |
| `chrovia.process` | `processManagement` | [正常退出浏览器](https://console.getchrovia.com/zh/docs/sdk-process-management) |
| `chrovia.automation` | `automation` | [仅限 Window 的 DOM 工具和可信事件](https://console.getchrovia.com/zh/docs/sdk-automation) |
| `chrovia.passwords` | `passwords` | [仅限 Provision Worker 的密码存储](https://console.getchrovia.com/zh/docs/sdk-passwords) |
| `chrovia.instanceMetadata` | `instanceMetadata` | [运行时和公开元数据对象](https://console.getchrovia.com/zh/docs/sdk-instance-metadata) |
| `chrovia.license` | 无独立域能力 | [License 快照](https://console.getchrovia.com/zh/docs/sdk-license)和[租约集成](https://console.getchrovia.com/zh/docs/sdk-leases) |

不是每项能力都有 JavaScript 域。指纹、代理、外观、DNR、注入凭据等配置驱动功能见[完整能力索引](https://console.getchrovia.com/zh/docs/sdk-capabilities)。

## 执行上下文与可用性

能力未授予时，对应域返回 `undefined`。调用前检查根对象和域。对象存在不证明请求的所有操作都成功，也不证明在线租约正常。

默认网页、扩展标签页和 popup 没有根对象。popup 应通过 `chrome.runtime.sendMessage` 请求自己的 Worker 执行具体操作。[unrestrictedApi](https://console.getchrovia.com/zh/docs/sdk-unrestricted-api) 扩大开放范围，但不授予具体能力。`automation` 仅限 Window，`passwords` 即使在扩大开放后仍只对 Provision Service Worker 开放。

不要据此推断 Node.js、DedicatedWorker 或 SharedWorker 也支持这些 API。外部启动器负责启动浏览器及准备文件，它的 Node.js 全局对象不是浏览器的 `chrovia`。

## 返回值

`prefs`、`passwords`、`ui`、`license` 方法返回 Promise，需要处理拒绝并查阅各方法的无操作或失败行为。`messaging.on/emit/off`、`network.intercept/stopIntercepting`、`process.exit` 返回 `undefined`。尤其是 await `intercept()` 不会确认浏览器端就绪，但拦截回调本身可以返回 Promise。

`instanceMetadata` 是数据对象，不是方法或 Promise。自动化方法是同步的，输入无效时可能抛错。

## 生命周期与状态

在 Service Worker 脚本执行时注册监听和拦截，不要只在 `onInstalled` 中注册。空闲 Worker 可能停止，并在之后重启；JS 全局状态不会保留。进程级消息和唯一网络会话需要插件之间协调所有权。

prefs 和消息使用兼容 JSON 的值。不要把秘密记录到日志或交给页面可访问的数据。写入 Promise 正常解析不代表通用的持久化或授权保证。修改 `internal` 前先了解 [EP 签名](https://console.getchrovia.com/zh/docs/sdk-signed-extended-prefs)。