# Browser SDK · Ageseal docs

Canonical URL: https://ageseal.eu/docs/sdk

> Options, results and reasons of Ageseal.check, browser support, feature detection, the CSP line and how to pin a version with Subresource Integrity.

Status: Test mode.

One global, one method. The SDK is a small script served from the Ageseal CDN. It has no dependencies, sets no cookies and writes nothing to storage.

> **Planned: Test mode.** The released SDK (version 0.2.0) starts a check through the verification API and asks the wallet. With a test key it completes against test credentials. Live keys resolve `unavailable` until production issuers are added.

## Install

`index.html`:

```html
<script src="https://cdn.ageseal.eu/v1/ageseal.js" defer></script>
```

The script defines `Ageseal` on `window`. Add it to the pages that run a check, not to every page of your site.

## Ageseal.check

Starts one age check and resolves with its outcome. Call it from a click or tap, because browsers only open the wallet picker after a user gesture.

`signature`:

```js
const result = await Ageseal.check({ key: "pk_test_9fK2", over: 18 });
// { result: "pass" | "fail" | "unavailable", token?: string, reason?: string }
```

### Options

| Option | Type | Description |
| --- | --- | --- |
| `key` | string | Your publishable key, `pk_test_` or `pk_live_`. It is safe to put in the page. Never use a secret key here. |
| `over` | `18` | The age threshold. Only 18 is supported. |

Invalid options reject the promise with a `TypeError` that says which option is wrong. Fix these while developing; they are not a runtime outcome to handle.

### Result

| Field | Type | Description |
| --- | --- | --- |
| `result` | `"pass"`, `"fail"` or `"unavailable"` | `pass`: the visitor is over the threshold. `fail`: they are not. `unavailable`: no answer was possible, see `reason`. |
| `token` | string | Present when `result` is `pass` or `fail`. A signed token your server verifies. Send it to your server and never trust `result` on its own. |
| `reason` | string | Present when `result` is `unavailable`. Why the check could not run. |

> **Careful.** The result object lives in the visitor browser, so it can be changed there. Only the token, verified on your server, proves anything.

### Reasons

| Reason | Status | Meaning |
| --- | --- | --- |
| `no_wallet` | Available | The browser does not expose the Digital Credentials API. |
| `preview` | Available | The site is not live yet, so no check was started. Go live in the dashboard first. |
| `cancelled` | Available | The visitor closed the picker, declined in the wallet, or the wallet could not answer. |
| `error` | Available | Something else failed. The result also carries a `code`, for example `network` when Ageseal could not be reached, or the error code the API returned. |

The planned reason names are not final. Treat any reason you do not know as "send the visitor to the fallback check".

### Version

`Ageseal.version` is a string with the SDK release, for example in a support request.

## Browser support

The SDK needs the W3C Digital Credentials API. Support today:

| Browser | Support |
| --- | --- |
| Chrome 141 and later | Shipped. Same device on Android, and from a desktop through a QR code and the phone. |
| Safari 26 and later | Shipped, for the ISO mdoc format only. That is the format the EU age verification app uses. |
| Firefox | Not shipped. A QR code fallback is planned. |

### Feature detection

The SDK asks the browser what it supports and never makes a credential request to find out. It checks for `DigitalCredential` and `navigator.credentials.get`, and, where the browser offers `DigitalCredential.userAgentAllowsProtocol`, whether the OpenID4VP and ISO mdoc protocols are allowed. You can run the same test yourself before you show an age gate button:

`detect.js`:

```js
function canAskWallet() {
  return "DigitalCredential" in window && typeof navigator.credentials?.get === "function";
}

if (!canAskWallet()) {
  showFallback("no_wallet"); // go straight to your other check
}
```

The home page has a "Check this browser" button that shows the result of this test for the browser you are using. Nothing is sent anywhere.

## Content Security Policy

If your site sets a CSP, allow the script host. The preview SDK makes no requests, so nothing else is needed today.

`Content-Security-Policy`:

```sh
script-src https://cdn.ageseal.eu
```

> **Planned.** Planned: once the API is live, the SDK calls https://api.ageseal.eu, so `connect-src` will need that host too.

## Versions and pinning

The CDN serves three kinds of address:

| Address | What it is | Use |
| --- | --- | --- |
| `/v1/ageseal.js` | The newest 1.x release. Before 1.0 it follows the newest release. | Default. Updates reach visitors within about a minute. |
| `/latest/ageseal.js` | The newest release of any major version. | Trying new versions in testing. |
| `/v0.2.0/ageseal.js` | One exact release. The file never changes. | Pin it with Subresource Integrity when you need a fixed build. |

Every release is listed with its date, size and integrity hash in [versions.json](https://cdn.ageseal.eu/versions.json). To pin, copy the hash of the version you tested:

`pinned.html`:

```html
<script src="https://cdn.ageseal.eu/v0.2.0/ageseal.js"
        integrity="sha384-/K34VRTB24P7c0OPc3ujFKOC0WlTY5Xw4GDnya8ZTvkCUDLLmcYjSK+sW8Zu7KH7"
        crossorigin="anonymous" defer></script>
```

Do not add an integrity attribute to `/v1/` or `/latest/`. Those files move, and the hash would stop matching. A pinned version means you update by hand, so check the release list from time to time.

```sh
curl -s https://cdn.ageseal.eu/versions.json
```

TypeScript types are published next to each build, for example `https://cdn.ageseal.eu/v0.2.0/ageseal.d.ts`.

Docs: [Overview](https://ageseal.eu/docs), [Quickstart](https://ageseal.eu/docs/quickstart), [Browser SDK](https://ageseal.eu/docs/sdk), [Verify tokens](https://ageseal.eu/docs/verify), [HTTP API](https://ageseal.eu/docs/api), [Fallback](https://ageseal.eu/docs/fallback), [Testing and going live](https://ageseal.eu/docs/testing), [Privacy and security](https://ageseal.eu/docs/privacy-security).
