SDK JavaScript API overview
Choose the correct execution context, identify API domains and return types, and open each capability's full reference.
The browser provides globalThis.chrovia; there is no SDK import. Normally use it from a Provision extension Service Worker. Follow the quickstart and plugin installation guide to create one.
Domains and references
| Domain | Entitlement | Reference |
|---|---|---|
chrovia.prefs | extendedPrefs | EP storage, get/set/remove, Profile settings |
chrovia.network | networkIntercept | Options, parsed requests, cancellation and worker lifecycle |
chrovia.messaging | messaging | Channels, publish/subscribe and startup replies |
chrovia.ui | nativeDialog | Alert, confirm and notify |
chrovia.process | processManagement | Graceful browser exit |
chrovia.automation | automation | Window-only DOM helpers and trusted events |
chrovia.passwords | passwords | Provision Service Worker-only saved-password store |
chrovia.instanceMetadata | instanceMetadata | Runtime and public metadata object |
chrovia.license | No separate domain entitlement | License snapshot and lease integration |
Not every capability has a JavaScript domain. Fingerprint, proxy, appearance, DNR, injected credentials, and other configuration-driven features are documented in the complete capability index.
Execution context and availability
An absent domain returns undefined when its capability is not granted. Check the root and domain before calling. A valid object is not proof that every requested operation succeeded or that online leasing is healthy.
By default, pages, extension tabs, and popups do not receive the root object. Use chrome.runtime.sendMessage from a popup to its own worker for specific operations. unrestrictedApi broadens exposure but grants no individual capability. automation is Window-only; passwords remains Provision Service Worker-only even with unrestricted exposure.
Do not infer that these APIs run in Node.js, DedicatedWorker, or SharedWorker. External launchers start the browser and prepare its files; their Node.js globals are not the browser's chrovia object.
Return values
prefs, passwords, ui, and license methods return Promises. Handle rejection and consult each method's no-op/failure behavior. messaging.on/emit/off, network.intercept/stopIntercepting, and process.exit return undefined. In particular, awaiting intercept() does not acknowledge browser-side readiness. The interception callback itself may return a Promise.
instanceMetadata is a data object, not a method or Promise. Automation methods are synchronous and can throw for invalid input.
Lifecycle and state
Register event listeners and interception handlers when the Service Worker script runs, not only in onInstalled. Idle workers can stop and restart, losing JS globals. Process-wide messaging and the single network session require coordinated ownership across plugins.
Use JSON-compatible values for prefs and messages. Keep secrets out of logs and page-accessible data. A resolved write Promise is not a universal durability or authorization guarantee. Review EP signing before writing inside internal.