Download and verify an extension through the SDK

Retrieve a published Chromium package, verify its size and SHA-256 through the SDK helper, and configure manifest defaults before installation.

Separate obtaining a package from configuring it

The SDKs provide extension-release lookup and download helpers. Downloading a package does not activate it, choose its permissions, or populate an API key. Use the configuration helpers below to add manifest defaults before installation, or configure the extension through its popup.

The SDK selects the Chromium extension internally; no extension ID is needed. Use browser to select a supported browser (currently "chromium"). The public download page remains the ordinary starting point for visitors.

Use an explicit destination

import os
from easycaptcha.backends.urllib import UrllibClient

with UrllibClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
    package = client.download_extension()
    package.save("easycaptcha-extension.zip")

The helper obtains release metadata and checks downloaded bytes against its declared size and SHA-256. Choose your own local path rather than treating the remote filename as a trusted path. Unpack the verified package according to the installation instructions.

If you need a specific version, use the documented version option instead of assuming latest remains unchanged between evaluation runs. Record both the requested version and the release metadata returned.

Add manifest defaults with the SDK

Python’s configure_settings returns a new package; it works with downloads from both synchronous and asynchronous clients:

import os
from easycaptcha.backends.urllib import UrllibClient

with UrllibClient() as client:
    package = client.download_extension()
    configured = package.configure_settings({
        "apikey": os.environ["EASYCAPTCHA_API_KEY"],
        "enabled": True,
        "burst": False,
        "fast": False,
    })
    configured.save("easycaptcha-configured.zip")

JavaScript’s configureExtension is available on every transport client:

import { writeFile } from "node:fs/promises";
import { FetchClient } from "@easycaptcha-to/sdk/fetch";

const client = new FetchClient();
const extension = await client.downloadExtension();
const configured = await client.configureExtension(extension, {
  apikey: process.env.EASYCAPTCHA_API_KEY,
  enabled: true,
  burst: false,
  fast: false,
});
await writeFile("easycaptcha-configured.zip", configured.data);

All four fields are optional. Helpers merge the supplied fields into existing easycaptcha_settings, reject unsupported names or invalid types, and preserve other manifest fields and asset contents. They leave the downloaded bytes intact and return a new ZIP. Extract that ZIP and load its directory into Chromium.

Release metadata, including size and SHA-256, still describes the original verified download; the configured ZIP has different bytes. Keep packages with embedded API keys private and use a dedicated key for each installation. Saved popup settings override these defaults in an existing browser profile. To add a manifest-only developer_tag, extract the configured ZIP and edit easycaptcha_settings in its root manifest.json before loading the extension. The SDK configuration helpers currently accept only the four fields above. See manifest configuration for field defaults and reload behavior.

Handle artifact and API failures independently

The release lookup and package download are separate network operations. A signed download URL can expire; do not permanently store it as though it were the stable package identifier. Retain the release ID and obtain fresh metadata when the contract requires it.

A size or digest mismatch is an integrity failure, not a reason to ignore verification and install anyway. Keep the failed metadata for diagnosis without exposing credentials or temporary signed links in public logs.

Configure a dedicated browser workflow

Install into an appropriate Chromium profile, open the popup, and choose the free or paid setup for that installation. Use a separately revocable paid key when account credit is needed. The extension supplies recognition assistance and does not submit your whole form.

Persistent profile setup explains how settings survive runs. Release integrity provides an evaluation record, and extension versus API helps choose whether package installation belongs in your integration at all.