The agecheck.pro JavaScript SDK makes it straightforward to add age verification to any web application. Whether you’re building a static site, a CMS-based platform, or a complex single-page application, the SDK provides a consistent API for triggering, handling, and responding to age verification events.

Installation and Initial Setup

The SDK is distributed as a single script tag no npm package or build step required for basic integration. Add the following to your HTML before the closing </body> tag, replacing YOUR_DOMAIN_KEY with the key from your agecheck.pro dashboard:

For applications using a module bundler, the SDK is also available via CDN import or as a CommonJS/ESM module. The initialization accepts a configuration object with the following optional parameters:

  • method: "self-consent" | "face-ai" | "document-ai" | "verify-ai" — defaults to the method configured in your dashboard.
  • locale: BCP 47 language tag (e.g., "es", "fr", "de") for UI localization.
  • theme: "light" | "dark" | custom CSS token overrides.
  • containerId: ID of a DOM element to render the widget inline (omit for modal overlay mode).
  • tokenTTL: session token lifetime in days (default: 30, max: 365).

Handling verification events

The SDK fires custom DOM events on the window object, which your application can listen to and respond to. The primary events are:

Event nameWhen firedEvent detail payload
agecheck:verifiedVerification passed{ token, method, ageRange, timestamp }
agecheck:failedVerification failed (underage){ method, reason }
agecheck:errorTechnical error during verification{ code, message }
agecheck:dismissedUser closed the widget without completing{}

Token validation on the server side

Once the SDK emits an agecheck:verified event, your application receives a signed JWT token. For secure server-side gating of content or API endpoints, you should validate this token server-side rather than trusting client-side state alone. The token can be validated against the agecheck.pro token verification endpoint:

  • Endpoint: POST https://api.agecheck.pro/v1/tokens/verify
  • Body: { "token": "<jwt_string>" }
  • Response: { "valid": true, "method": "face-ai", "ageRange": "25-34", "expiresAt": "..." }

This validation step is especially important for content delivery, subscription gating, and any endpoint where the user’s verified age status carries a legal implication.

QR Code Desktop-to-Mobile Handoff

For verification methods that require a camera (Face-AI, Document-AI, Verify-AI), the SDK automatically detects desktop environments and displays a QR code. The mobile device completes the verification and the result is synchronised to the desktop session via WebSocket in real time. No extra configuration is required—this behaviour is built in.

Error handling and fallback strategies

Robust integrations handle edge cases gracefully. Recommended patterns include:

  1. Listen for agecheck:error and display a retry button or offer an alternative verification method.
  2. For users in regions where AI methods are restricted, configure a fallback to Self-Consent via the dashboard’s geo-targeting rules.
  3. Use the tokenTTL parameter to balance security (shorter TTL) against friction for returning users (longer TTL).