SDK developer quickstart

Chrovia SDK is a Chromium-based browser runtime with additional configuration and JavaScript APIs. The chrovia object is built into the browser; it is not an npm package to import into your website or Node.js application.

Your application launches the browser and prepares its files. A Chrovia License authorizes capabilities. Extended Preferences configures the instance. Provision extensions run your privileged browser-side logic.

1. Prepare the browser and License

Follow Download and install a trial License to obtain the browser archive and an issued License. For this quickstart, select Extended Preferences (extendedPrefs). Keep the shipped Chrovia Infra extension, which handles online authorization for licenses that require it.

Extract the complete browser archive. Do not modify the signed License to add capabilities: request a License with the capabilities you need instead.

2. Choose an instance directory

Create a dedicated directory for your browser instance and place the issued file there with the exact name Chrovia License, without a file extension:

sdk-profile/
  Chrovia License

Pass its absolute path through --user-data-dir. This directory holds the instance's browser data, including cookies and saved passwords. Use different directories for independent instances.

The browser first looks for Chrovia License in the user-data directory. Only when it is absent does it use the file in the Provision root. An existing invalid License does not fall back to the Provision copy.

If your License includes signedExtendedPrefs, also install a correctly signed Extended Preferences file before launching. For a simple unsigned configuration experiment, request a License without that capability; do not remove it from an already-issued License. See Extended Preferences.

3. Add a Provision extension

For the standard Chrovia distribution, the Provision root is the Chrovia directory beside the executable on Windows, or Chrovia.app/Contents/Chrovia on macOS. Custom distributions can use a different branded directory name.

Add a new directory under Extensions, leaving the existing files and extensions intact:

Chrovia/
  manifest.json
  Extensions/
    chrovia-infra/
    sdk-example/
      manifest.json
      background.js

The root manifest.json contains package metadata. The manifest.json inside sdk-example is a Chrome extension manifest. Create it with:

{
  "manifest_version": 3,
  "name": "SDK Example",
  "version": "1.0.0",
  "background": {
    "service_worker": "background.js"
  }
}

Create background.js:

const prefs = globalThis.chrovia?.prefs;

async function runExample() {
  if (!prefs) {
    console.error('SDK Example: extendedPrefs is unavailable');
    return;
  }

  await prefs.set('sdk_example.message', 'Hello from Chrovia SDK');
  console.log(await prefs.get('sdk_example.message'));
}

runExample().catch(console.error);

No Chrome manifest permission named extendedPrefs is needed: it is a License entitlement, not an extension permission. Standard chrome.* APIs and extension fetches still have their own manifest requirements.

The browser automatically loads plugins from immediate subdirectories of Extensions at startup. Keep the directory name unchanged when updating a plugin. You do not need Load unpacked.

4. Launch and inspect

Fully quit the test instance before launching with new files or startup arguments. Adjust these paths to match your installation.

Windows PowerShell

& 'C:\SDK\Chrome-bin\chrovia.exe' --user-data-dir='C:\SDK\sdk-profile' --show-component-extension-options

macOS Terminal

./Chrovia.app/Contents/MacOS/Chrovia \
  --user-data-dir="$HOME/chrovia-sdk-profile" \
  --show-component-extension-options

Open chrome://extensions, enable Developer mode, find SDK Example, and inspect its Service Worker. In that console, run:

await chrovia.prefs.get('sdk_example.message')

The expected value is Hello from Chrovia SDK. The inspection flag makes component extensions visible for debugging; it is not required for normal operation. A License and configuration that disable DevTools must not be used for this debugging walkthrough.

Where your code runs matters

By default, chrovia is available in Provision extension Service Workers, not ordinary web pages, extension popups, or extension tabs. A popup should use chrome.runtime.sendMessage to ask its Service Worker to perform a specific operation.

The unrestrictedApi entitlement broadens API exposure to page contexts, but does not grant individual capabilities. It is not needed for this quickstart. The passwords API remains restricted to Provision Service Workers even with unrestrictedApi.

Service Workers can stop when idle and restart later. Register listeners and interception logic when the worker script runs, not only in chrome.runtime.onInstalled. Do not rely on global variables surviving worker restarts.

Development loop and troubleshooting

1. Edit your extension and copy its built JavaScript into the Provision directory of the browser you actually launch.
2. Fully quit that browser instance and relaunch it.
3. Inspect the extension Service Worker, not the console of a web page or popup.

If chrovia is missing, check the execution context and Provision location. If only chrovia.prefs is missing, check the License's extendedPrefs capability. If the API exists but reads return undefined, check the key, installed License, and Extended Preferences signature. An object being present is not proof that online lease authorization is healthy.

For working capability demonstrations, use Chrovia Studio from Downloads. Some Studio page demos request unrestrictedApi; do not assume that page access is the default SDK integration model.

Continue with the SDK documentation and capability index. It links the License, lease, EP, Provision, plugin installation, and individual capability guides.