SDK Extended Preferences

Extended Preferences is a JSON file named exactly Extended Preferences, without .json, in the directory passed to --user-data-dir. It is separate from Chromium's ordinary Preferences file and from Chrovia License.

Start with the SDK developer quickstart if you do not yet have a browser instance and Provision extension.

Document layout

Browser configuration belongs under the top-level internal object. Application-owned data can live alongside it. signature, when required, is a separate top-level object, not a child of internal.

This is a complete unsigned example for a License that grants extendedPrefs and instanceAppearance but does not grant signedExtendedPrefs:

{
  "internal": {
    "instance_appearance": {
      "label": "SDK Example",
      "background_color": "#059669",
      "foreground_color": "#FFFFFF"
    }
  },
  "sdk_example": {
    "message": "Hello from Chrovia SDK",
    "counter": 0
  }
}

Write the file before launching. Each kernel feature still requires its own License capability: adding instance_appearance does not grant instanceAppearance. Treat kernel configuration as startup configuration unless a feature explicitly supports live updates; writing JSON through the API is not a universal hot-reload mechanism.

Provision defaults versus instance data

You may distribute an initial Extended Preferences in the Provision root, alongside its manifest.json and Extensions directory.

On first startup, if the user-data directory has no Extended Preferences, the browser copies the Provision file there and loads the instance copy. An existing instance file is never overwritten. Changing the Provision seed therefore does not update existing instances. If copying fails, the browser logs a warning and continues as if the file were missing.

The copied file must also meet your License's signed-configuration requirements.

JavaScript get, set, and remove

Requires extendedPrefs and an allowed execution context, normally a Provision Service Worker.

Keys are dotted paths from the document root. Include internal. when accessing kernel configuration:

async function readAndWritePrefs() {
  const prefs = globalThis.chrovia?.prefs;
  if (!prefs) {
    throw new Error('extendedPrefs is unavailable');
  }

  const label = await prefs.get('internal.instance_appearance.label');
  await prefs.set('sdk_example.message', 'Updated by the extension');
  const message = await prefs.get('sdk_example.message');
  await prefs.remove('sdk_example.counter');
  console.log({ label, message });
}

readAndWritePrefs().catch(console.error);

Use JSON-compatible values. set() rejects with DataCloneError if the value cannot be converted to a storable value; catch the rejection and correct the input. These methods are not transactions, and a read followed by a write is not an atomic increment. A resolved write Promise is not proof that data has been saved to disk or authorization is valid: unavailable preferences and failed verification can make writes no-ops.

Signed configuration

When the License grants signedExtendedPrefs, a valid signed file is required. Without that capability, the browser does not require an Extended Preferences signature, but still validates the License.

Obtain a complete signed file compatible with your License from your configuration provider. Do not construct or edit its signature object. Before changing protected settings, arrange to receive a replacement file; the browser does not provide a signing command or API.

Keep mutable application data outside internal, as with sdk_example. For signed files, changing internal through an editor or prefs.set() can make the file unusable on the next launch; obtain a replacement signed file instead.

If required verification fails, the browser blocks all Extended Preferences reads and writes, including unsigned application fields. get() can return undefined, while set() and remove() can resolve without changing anything. Do not interpret these return values as a signature-validation API.

Set the download directory

internal.profile_prefs accepts a small allowlist of Chromium Profile preferences. It requires extendedPrefs; it is not a general Chrome policy or Local State API.

The current supported keys are download.default_directory and savefile.default_directory. For a Windows instance, this fragment sets both independently:

{
  "internal": {
    "profile_prefs": {
      "download.default_directory": "C:\\SDK\\downloads\\instance-01",
      "savefile.default_directory": "C:\\SDK\\downloads\\instance-01"
    }
  }
}

Merge this section into your configuration before obtaining a signed file if required. Use machine-absolute paths appropriate for the host OS; relative paths and paths containing .. are rejected. Create the directory in your launcher if it must exist before a download.

Prefer a dedicated subdirectory, as in the example. On first setup, choosing exactly the Desktop directory—or exactly the home directory on Linux—can cause the browser to use its default download directory instead. A subdirectory does not have this exact-path exception. Verify the destination with a test download.

These directory settings apply at startup and remain saved for the profile. They do not lock the Settings UI, do not disable the download prompt, and do not automatically revert when the Extended Preferences entry is removed. Unsupported keys are skipped and logged. The two directory values are not automatically mirrored.

For the dedicated signature-enforcement capability, see Signed Extended Preferences. To configure other kernel sections, use the complete capability index.