Emblem SDK Integration Guide

Quick Start

<!-- Include the SDK -->
<script src="https://sdk.emblemapp.com/emblem-sdk.js"></script>

<!-- Initialize and show age gate -->
<script>
  const emblem = new EmblemSDK({
    apiKey: 'pk_live_your_api_key'
  });
  
  // Show age gate with two options
  await emblem.showAgeGate({
    configuration: 'us-config',  // Your named configuration
    callbackUrl: window.location.href
  });
</script>

Key Features

Two-Option Age Gate

"Verify Now" for new users, "Sign in with Emblem" for returning users

Passkey Authentication

Secure, passwordless authentication for returning users

Privacy Layer

All verifications route through Emblem (never direct to provider)

Regional Compliance

Multiple configurations for different jurisdictions

Mobile-First Design

Optimized for touch devices with proper sizing

Account Creation

Optional account creation after verification

Complete Integration Examples

1. Basic Age Gate Implementation

Show the age verification UI with automatic handling:

// Show age gate with both verification options
await emblem.showAgeGate({
  configuration: 'us-config',
  callbackUrl: window.location.href,
  onVerifyNow: () => {
    console.log('User starting new verification');
  },
  onSignIn: () => {
    console.log('User attempting passkey sign-in');
  }
});

2. Regional Configuration Selection

Automatically select configuration based on user location:

// Define your configuration mapping
const configMap = {
  'US': 'us-config',
  'TX': 'us-strict-config',  // Texas-specific
  'CA': 'ca-config',
  'GB': 'eu-config',
  'DE': 'eu-config',
  'FR': 'eu-config'
};

// Auto-select configuration
const configuration = await emblem.selectConfigurationByRegion(configMap);

// Use selected configuration
await emblem.showAgeGate({
  configuration,
  callbackUrl: window.location.href
});

3. Handle Verification Callback

Process the result when users return from verification:

// Check for callback on page load
const result = await emblem.handleCallback();

if (result && result.verified) {
  // User successfully verified
  console.log('Verification level:', result.verificationLevel);
  
  // Account creation will be offered automatically
  // Continue to age-gated content
  window.location.href = '/members-only';
} else if (result && !result.verified) {
  // Verification failed or expired
  console.log('Verification failed');
  
  // Show age gate again
  await emblem.showAgeGate({
    configuration: 'us-config',
    callbackUrl: window.location.href
  });
}

4. Passkey Authentication for Returning Users

Users who click "Sign in with Emblem" will use passkeys:

// This happens automatically when using showAgeGate()
// But you can also trigger it directly:
try {
  const result = await emblem.authenticateWithPasskey();
  
  if (result.status === 'verified') {
    // User authenticated successfully
    window.location.href = '/welcome-back';
  } else if (result.status === 'insufficient_level') {
    // User needs higher verification level
    // Upgrade prompt will show automatically
  }
} catch (error) {
  console.error('Passkey authentication failed');
}

Mobile Optimization

The SDK is designed mobile-first with:

Touch-friendly buttons (minimum 44x44px)
Readable text (minimum 16px)
Responsive layouts that adapt to screen size
Smooth animations and transitions
Bottom sheet style on mobile devices

Note: Test your integration on actual mobile devices or using browser developer tools in mobile mode to ensure the best user experience.

API Reference

Core Methods

showAgeGate(options)

Display the age verification UI with "Verify Now" and "Sign in with Emblem" options.

configuration (string, required) - Named configuration to use
callbackUrl (string, required) - URL to redirect after verification
onVerifyNow (function) - Called when user clicks "Verify Now"
onSignIn (function) - Called when user clicks "Sign in with Emblem"
onClose (function) - Called if user closes the age gate

createVerificationSession(options)

Programmatically create a verification session.

configuration (string, required) - Named configuration to use
callbackUrl (string, required) - URL to redirect after verification
display (string) - 'redirect' to redirect immediately
metadata (object) - Optional metadata

handleCallback(url)

Process verification callback and offer account creation.

authenticateWithPasskey()

Trigger passkey authentication for returning users.

selectConfigurationByRegion(configMap)

Helper to select configuration based on detected region.

Best Practices

Always use showAgeGate() for the complete user experience
Test on mobile devices - most users will be on mobile
Handle callbacks on every page where users might return
Use meaningful configuration names (e.g., 'us-18-plus', 'eu-gdpr')
Implement region detection for automatic configuration selection
Monitor verification rates in your dashboard
Keep the integration simple - let the SDK handle the complexity

Important: Never bypass the Emblem privacy layer by redirecting users directly to verification providers. All flows must go through Emblem to maintain user privacy.

Support

For additional support and documentation:

Dashboard: my.emblemapp.com
Documentation: docs.emblemapp.com
Support: support@emblemapp.com