Age gate JavaScript SDK, developer Integration Guide

This article covers how to integrate the SDK, what each public method does, and how to configure everything from the dashboard without touching your code again.

Installation

No npm package or build step required. Drop this snippet before the closing </body> tag on every page where you want the age gate to run:

<script
  src="https://cdn.agecheck.pro/dist/min/v1/Verify.js"
  data-verifier-id="v_YOUR_VERIFIER_ID"
  data-mode="auto"
  async>
</script>

That’s it for the basic integration. The SDK self-initializes, reads your dashboard configuration, detects the visitor’s geolocation, and shows the verification modal when required. The async attribute ensures it never blocks page rendering.

If you need to control initialization yourself — for example, inside a React useEffect or after some condition is met — omit data-mode="auto" and call AgeCheck.init() manually:

// Manual initialization
window.addEventListener('DOMContentLoaded', () => {
  AgeCheck.init({
    verifierId: 'v_YOUR_VERIFIER_ID'
  });
});

The SDK is exposed on window.AgeCheck automatically once the script loads.

Verification methods

The SDK supports four verification methods. The active method is set in the dashboard — you never need to change your integration code to switch between them.

Self-Consent is the simplest option: the user checks a box confirming they meet the minimum age and clicks a button. No camera, no documents. Completes in under five seconds. Suitable for content sites where a basic age declaration satisfies your legal obligations.

Face-AI uses AWS Rekognition to estimate the user’s age range from a live camera feed. The SDK guides the user through liveness challenges (smile, blink, head turn) to block photos and pre-recorded videos. Takes around 30 to 45 seconds.

Document-AI scans a government-issued ID (driving licence, passport, national ID) with OCR to extract an exact date of birth. Accepts documents from any country in multiple languages. Takes 60 to 90 seconds.

Verify-AI combines all three: Face-AI for liveness, Document-AI for the document, then a biometric face-matching step that compares the live face against the photo on the document (similarity threshold: ≥92%). The most thorough method, completing in 90 to 120 seconds. Required for sectors with KYC or AML obligations.

For any camera-based method, the SDK automatically detects desktop environments without a camera and shows a QR code. The user scans it with their phone, completes verification there, and the desktop session is updated in real time over WebSocket — no configuration required.

DOM events

The SDK communicates verification outcomes by dispatching custom events on window. Listen for them anywhere in your JavaScript:

// User passed age verification
window.addEventListener('agecheck:verified', (event) => {
  const { token, method, ageRange, timestamp } = event.detail;
  // token  — signed JWT for server-side validation
  // method — which method was used ('self-consent', 'face-ai', etc.)
  // ageRange — estimated age bracket returned by the AI method
  // timestamp — Unix ms when verification completed
});

// User is under the minimum age
window.addEventListener('agecheck:failed', (event) => {
  const { method, reason } = event.detail;
});

// A technical error occurred during verification
window.addEventListener('agecheck:error', (event) => {
  const { code, message } = event.detail;
});

// User closed the modal without completing verification
window.addEventListener('agecheck:dismissed', () => {
  // event.detail is empty — gate is still active
});

The token in agecheck:verified is a signed JWT. For any endpoint where the verified age status has a legal implication — gated content, checkout flows, account creation — validate it server-side. Never rely on client-side state alone for access control.

Public methods

Once window.AgeCheck is available, these methods are accessible from any script on the page.

`AgeCheck.init(config?)`

Initializes the SDK. Called automatically in auto mode; call it manually otherwise. Accepts an optional config object that overrides the dashboard settings for this session.

AgeCheck.init({
  verifierId: 'v_YOUR_VERIFIER_ID' // required if not set via data attribute
});

`AgeCheck.isVerified()`

Returns true if the current user has a valid, non-expired verification token stored locally. Use this to conditionally skip showing gated content without waiting for an event.

if (AgeCheck.isVerified()) {
  showProtectedContent();
} else {
  showAgeGate();
}

The check looks at both the in-memory state and the token stored in the cookie / localStorage, so it works correctly on repeat visits without re-triggering the modal.

`AgeCheck.isReady()`

Returns true once the SDK has finished initializing and is ready to respond to user interactions. Useful if you need to call other methods immediately after the script loads.

// Poll until the SDK is ready, then check verification
const interval = setInterval(() => {
  if (AgeCheck.isReady()) {
    clearInterval(interval);
    if (!AgeCheck.isVerified()) AgeCheck.show();
  }
}, 100);

`AgeCheck.show()`

Programmatically opens the verification modal. Useful when you want to trigger verification on a specific user action rather than on page load.

document.getElementById('buy-button').addEventListener('click', async () => {
  if (!AgeCheck.isVerified()) {
    await AgeCheck.show();
    // Verification outcome arrives via window events above
  } else {
    proceedToCheckout();
  }
});

`AgeCheck.restartVerification(newType?)`

Clears the current verification state and restarts the flow from scratch. Optionally accepts a method string to switch the active method for this restart only.

// Restart with the same method
AgeCheck.restartVerification();

// Restart with a different method (overrides dashboard setting for this session)
AgeCheck.restartVerification('document-ai');

This is the right call when handling a camera_denied error and you want to offer Self-Consent as a fallback:

window.addEventListener('agecheck:error', (event) => {
  if (event.detail.code === 'CAMERA_DENIED') {
    AgeCheck.restartVerification('self-consent');
  }
});

`AgeCheck.clearVerification()`

Removes the stored verification token from cookies and localStorage, returning true on success. After calling this, isVerified() returns false and the next page load will trigger the gate again.

// Example: "Log out" button that also clears age verification
document.getElementById('logout').addEventListener('click', () => {
  AgeCheck.clearVerification();
  redirectToLogin();
});

`AgeCheck.getStatus()`

Returns a snapshot object with the SDK’s current internal state — useful for debugging.

console.log(AgeCheck.getStatus());
// {
//   version: '1.6',
//   state: 'verified',          // 'idle' | 'initializing' | 'ready' | 'verified' | 'destroyed'
//   config: {
//     verifierId: 'v_xxxxx',
//     verificationType: 'face-ai',
//     debug: false
//   },
//   currentModule: { ... },
//   managers: { ui: 'result', storage: { ... } }
// }

`AgeCheck.getConfig()`

Returns the active configuration object, including both the values passed to init() and the settings loaded from the dashboard.

`AgeCheck.getStorageInfo()`

Returns details about the current token stored locally: whether it exists, its expiry, and which storage mechanisms (cookie, localStorage) are available in the browser.

const info = AgeCheck.getStorageInfo();
// {
//   enabled: true,
//   hasVerification: true,
//   ttlDays: 30,
//   available: { cookie: true, localStorage: true },
//   verificationData: { ... }
// }

`AgeCheck.getVersion()`

Returns the SDK version string.

javascript

console.log(AgeCheck.getVersion()); // '1.6'

`AgeCheck.cleanup()`

Destroys the SDK instance, removes all UI, cancels ongoing verifications, and nullifies internal state. Useful in single-page applications when unmounting a component that hosted the age gate.

Dashboard configuration

All the settings that matter for your integration live in the AgeCheck.pro dashboard at app.agecheck.pro. Changes apply instantly to every page using your Verifier ID — no redeployment needed.

Creating a Verifier

Each domain you want to protect needs its own Verifier. From the dashboard:

Go to Websites → Add New
Enter your domain (e.g. example.com)
Verify ownership via a DNS TXT record or a small file placed on your server — the dashboard walks you through both options
Copy the generated Verifier ID (format: v_xxxxxxxx)

You can create multiple Verifiers for the same account — each with its own configuration. This lets you run different methods or minimum ages on different domains from a single account.

Verification method

Under Settings → Verification Type, pick from the four methods described earlier. This is the method the SDK will use unless restartVerification() overrides it per-session. You can change it at any time and all active sessions will pick it up on the next initialization.

Minimum age

Set the age threshold under Settings → Minimum Age. The SDK compares the verified age against this value and dispatches either agecheck:verified or agecheck:failed accordingly. Default is 18.

Token TTL (Session Persistence)

Under Settings → Persistence, set how many days a verified user’s token remains valid. The token is stored in an HTTP-only cookie (primary) and localStorage (fallback). Default is 30 days; the range is 1 to 90 days.

A shorter TTL means users verify more often — higher friction, higher assurance. A longer TTL reduces friction for repeat visitors and lowers your monthly verification count for high-traffic sites.

Geo-Targeting rules

Under Settings → Geo-Targeting, you can define different behaviour per country or region. Common uses:

Apply a stricter method (e.g. Document-AI) in specific jurisdictions while using Self-Consent everywhere else
Set a higher minimum age for regions with different legal requirements
Exempt regions where age verification would create compliance problems rather than solve them

Rules are evaluated against the visitor’s IP geolocation at initialization time. If no rule matches, the default method and minimum age apply.

Debug mode

Enable Debug Mode in the dashboard (or pass data-debug="true" on the script tag) to get detailed SDK logs in the browser console:

[AgeCheck] SDK initialized v1.6
[AgeCheck] Verifier: v_xxxxx
[AgeCheck] Verification type: face-ai
[AgeCheck] Opening modal...
[AgeCheck] WebSocket connected
[AgeCheck] Face detected: confidence 97%
[AgeCheck] Liveness challenge: smile — completed
[AgeCheck] Verification complete
[AgeCheck] Token saved to cookie + localStorage

Do not leave debug mode on in production — it exposes internal state in the console.

A practical integration example

Putting it all together: an e-commerce page that gates a checkout flow, with a camera-permission fallback.

<button id="checkout-btn" disabled>Verify age to continue</button>

<script
  src="https://cdn.agecheck.pro/dist/min/v1/Verify.js"
  data-verifier-id="v_YOUR_VERIFIER_ID"
  data-mode="auto"
  async>
</script>

<script>
  // On page load, check if the user is already verified
  window.addEventListener('DOMContentLoaded', () => {
    if (AgeCheck.isVerified()) {
      enableCheckout();
    }
  });

  // Verification passed — unlock checkout
  window.addEventListener('agecheck:verified', () => {
    enableCheckout();
  });

  // Underage — keep the button disabled and show a message
  window.addEventListener('agecheck:failed', () => {
    document.getElementById('checkout-btn').textContent = 'Not available in your region';
  });

  // Camera denied — fall back to self-consent
  window.addEventListener('agecheck:error', (e) => {
    if (e.detail.code === 'CAMERA_DENIED') {
      AgeCheck.restartVerification('self-consent');
    }
  });

  function enableCheckout() {
    const btn = document.getElementById('checkout-btn');
    btn.disabled = false;
    btn.textContent = 'Proceed to checkout';
    btn.addEventListener('click', () => window.location.href = '/checkout');
  }
</script>

The same pattern applies to video players, registration forms, gated articles, or anything else that requires a verified age before access.

Framework notes

The SDK works in any JavaScript environment without modification.

React / Next.js — load the script inside a useEffect with an empty dependency array, or add the <script> tag to _document.js. Call AgeCheck.init() after the component mounts.

Vue — load inside mounted() lifecycle hook, or add the tag to your index.html.

WordPress — paste the snippet in Appearance → Theme Editor → footer.php, just before </body>.

Shopify — add it under Settings → Checkout → Additional Scripts, or in your theme’s theme.liquid before </body>.

The SDK does not interfere with search engine crawlers. Googlebot skips the modal entirely, so your content remains fully indexable. The async loading means it has no effect on Core Web Vitals.

Age gate javaScript SDK complete integration guide

Installation

Verification methods

DOM events

Public methods

`AgeCheck.init(config?)`

`AgeCheck.isVerified()`

`AgeCheck.isReady()`

`AgeCheck.show()`

`AgeCheck.restartVerification(newType?)`

`AgeCheck.clearVerification()`

`AgeCheck.getStatus()`

`AgeCheck.getConfig()`

`AgeCheck.getStorageInfo()`

`AgeCheck.getVersion()`

`AgeCheck.cleanup()`

Dashboard configuration

Creating a Verifier

Verification method

Minimum age

Token TTL (Session Persistence)

Geo-Targeting rules

Debug mode

A practical integration example

Framework notes

Zero PII, zero risk.
Start verifying today.

Age gate javaScript SDK complete integration guide

Installation

Verification methods

DOM events

Public methods

AgeCheck.init(config?)

AgeCheck.isVerified()

AgeCheck.isReady()

AgeCheck.show()

AgeCheck.restartVerification(newType?)

AgeCheck.clearVerification()

AgeCheck.getStatus()

AgeCheck.getConfig()

AgeCheck.getStorageInfo()

AgeCheck.getVersion()

AgeCheck.cleanup()

Dashboard configuration

Creating a Verifier

Verification method

Minimum age

Token TTL (Session Persistence)

Geo-Targeting rules

Debug mode

A practical integration example

Framework notes

Zero PII, zero risk.Start verifying today.

`AgeCheck.init(config?)`

`AgeCheck.isVerified()`

`AgeCheck.isReady()`

`AgeCheck.show()`

`AgeCheck.restartVerification(newType?)`

`AgeCheck.clearVerification()`

`AgeCheck.getStatus()`

`AgeCheck.getConfig()`

`AgeCheck.getStorageInfo()`

`AgeCheck.getVersion()`

`AgeCheck.cleanup()`

Zero PII, zero risk.
Start verifying today.