Emblem SDK

The official JavaScript SDK for integrating Emblem age verification into your website or application.

Installation

npm install @emblemapp/sdk

Or include via CDN:

<script src="https://sdk.emblemapp.com/v1/emblem.min.js"></script>

Quick Start

import EmblemSDK from '@emblemapp/sdk';

const emblem = new EmblemSDK({
  apiKey: 'pk_live_YOUR_API_KEY' // Get from my.emblemapp.com
});

// Simple age verification (uses default configuration)
async function verifyAge() {
  const session = await emblem.createVerificationSession({
    callbackUrl: 'https://mysite.com/age-verified'
  });
  window.location.href = session.landingUrl;
}

Configuration Selection

Publishers can create multiple named configurations in the Emblem dashboard (e.g., "eu-config", "texas-config") and select which one to use per verification request.

Option 1: Use Default Configuration

// No configuration parameter - uses publisher's default
const session = await emblem.createVerificationSession({
  callbackUrl: 'https://mysite.com/age-verified'
});

Option 2: Specify Configuration

// Publisher's logic determines which configuration to use
const userRegion = await detectUserRegion();
const configName = userRegion === 'EU' ? 'eu-config' : 'us-strict-config';

const session = await emblem.createVerificationSession({
  configuration: configName,
  callbackUrl: 'https://mysite.com/age-verified'
});

Option 3: Modal with Configuration

// Opens a modal using the same UI as the redirect page.
// Starts verification and then redirects; does not return a result.
emblem.showVerificationModal({
  configuration: 'texas-config',
  callbackUrl: 'https://mysite.com/age-verified',
  onClose: () => console.log('User closed modal'),
  onSuccess: (sessionId) => console.log('Verification started:', sessionId),
  onError: (error) => console.error('Error:', error)
});

Regional Configuration Examples

Simple Regional Selection

// Map regions to your dashboard configurations
const regionalConfigs = {
  'US': 'us-standard-config',
  'EU': 'eu-gdpr-config',
  'GB': 'uk-config',
  'CA': 'canada-config'
};

// Detect region and select configuration
const region = await getUserRegion();
const configName = regionalConfigs[region] || 'default-config';

const session = await emblem.createVerificationSession({
  configuration: configName,
  callbackUrl: 'https://mysite.com/age-verified'
});

Business Logic Based Selection

// Select configuration based on multiple factors
function selectConfiguration(state, contentType, userPreference) {
  if (state === 'TX' && contentType === 'adult') {
    return 'texas-strict-config'; // L2 verification required
  } else if (['CA', 'NY'].includes(state)) {
    return 'california-ny-config';
  } else if (userPreference === 'strict') {
    return 'us-strict-config';
  }
  return 'us-standard-config';
}

const configName = selectConfiguration(
  getUserState(),
  getContentType(),
  getUserPreference()
);

const session = await emblem.createVerificationSession({
  configuration: configName,
  callbackUrl: 'https://mysite.com/age-verified',
  metadata: { state, contentType } // Optional tracking
});

Age Gate Display

Show an age verification screen with two options:

await emblem.showAgeGate({
  configuration: 'eu-config', // Optional - uses default if not specified
  callbackUrl: 'https://mysite.com/age-verified',
  onVerifyNow: () => console.log('User clicked Verify Now'),
  onSignIn: () => console.log('User clicked Sign in with Emblem'),
  onClose: () => console.log('User closed age gate')
});

Handling Callbacks

After verification, handle the callback:

// On your callback page
const result = await emblem.handleCallback();

if (result && result.verified) {
  // User is verified, grant access
  console.log('User verified at level:', result.verificationLevel);
} else {
  // Verification failed or incomplete
  console.log('Verification not complete');
}

Configuration Management

1. Create Configurations: In your Emblem dashboard at my.emblemapp.com, create named configurations (e.g., "eu-config", "texas-config")
2. Set Provider & Options: Each configuration can have different providers and settings
3. Use in SDK: Pass the configuration name when creating sessions

Common Patterns

Default Fallback:

try {
  const session = await emblem.createVerificationSession({
    configuration: preferredConfig,
    callbackUrl: callbackUrl
  });
} catch (error) {
  if (error.message.includes('not found')) {
    // Fallback to default configuration
    const session = await emblem.createVerificationSession({
      callbackUrl: callbackUrl
    });
  }
}

A/B Testing:

const configName = Math.random() > 0.5 ? 'config-a' : 'config-b';
const session = await emblem.createVerificationSession({
  configuration: configName,
  callbackUrl: callbackUrl,
  metadata: { testGroup: configName }
});

API Reference

new EmblemSDK(options)

Creates a new SDK instance.

Parameters:

• apiKey (required): Your API key from my.emblemapp.com
• environment (optional): 'development' or 'production' (default: 'production')
• baseUrl (optional): Override the API base URL

createVerificationSession(options)

Creates a new verification session.

Parameters:

• callbackUrl (required): URL to redirect after verification
• configuration (optional): Named configuration to use
• display (optional): 'redirect', 'modal', or 'embedded'
• metadata (optional): Additional data to attach to session

Returns: Promise

showVerificationModal(options)

Shows verification in a modal popup.

Parameters:

• callbackUrl (required): URL to redirect after verification
• configuration (optional): Named configuration to use
• onClose (optional): Callback when modal is closed
• onSuccess (optional): Callback when session is created
• onError (optional): Callback on error

Returns: Promise

showAgeGate(options)

Shows age gate with "Verify Now" and "Sign in with Emblem" options.

Parameters:

• callbackUrl (required): URL to redirect after verification
• configuration (optional): Named configuration to use
• onVerifyNow (optional): Callback when user clicks Verify Now
• onSignIn (optional): Callback when user clicks Sign in
• onClose (optional): Callback when age gate is closed

handleCallback(url?)

Processes the verification callback.

Parameters:

• url (optional): URL to parse (defaults to current URL)

Returns: Promise<CallbackResult | null>

getSessionStatus(sessionId)

Gets the current status of a verification session.

Parameters:

• sessionId (required): The session ID to check

Returns: Promise

selectConfigurationByRegion(configMap)

Helper to select configuration based on user's region.

Parameters:

• configMap (required): Object mapping regions to configuration names

Returns: Promise

Error Handling

try {
  const session = await emblem.createVerificationSession({
    configuration: 'invalid-config',
    callbackUrl: 'https://mysite.com/callback'
  });
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('Configuration does not exist');
  } else if (error.message.includes('API key')) {
    console.error('Invalid API key');
  } else {
    console.error('Unexpected error:', error);
  }
}

Support

• Documentation: https://docs.emblemapp.com
• Dashboard: https://my.emblemapp.com
• Support: [email protected]