# SDK developer quickstart

> Launch an isolated Chrovia browser instance, create a Provision extension, and call your first kernel JavaScript API.

Source: https://console.getchrovia.com/en/docs/sdk-getting-started

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](https://console.getchrovia.com/en/docs/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:

```text
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](https://console.getchrovia.com/en/docs/sdk-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:

```text
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:

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

Create `background.js`:

```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

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

### macOS Terminal

```sh
./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:

```js
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](https://console.getchrovia.com/en/download). 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](https://console.getchrovia.com/en/docs/sdk-capabilities). It links the License, lease, EP, Provision, plugin installation, and individual capability guides.

## Studio installation

To test SDK capabilities and run interactive Gallery demos in a local environment, see [Install Chrovia Studio on macOS](https://console.getchrovia.com/en/docs/studio-install-macos).