postMessage Events

The verification widget communicates with your page through the Window postMessage API. Listen for these events to track the verification lifecycle and respond to user actions.

Origin Validation

Always validate event.origin before processing any message. Only trust messages from https://ageevidence.com. Ignoring this check exposes your application to cross-origin message spoofing.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://ageevidence.com') return;

  // Safe to process event.data
});

Event Reference

All events follow the shape { type: string, data: object }. The type field identifies the event, and data contains the payload.

Event	When	Payload
`ae:ready`	Widget loaded and ready to use	`{}`
`ae:started`	User started the verification flow	`{ level: string }`
`ae:complete`	Verification submitted successfully	`{ verificationId: string, status: string }`
`ae:error`	An error occurred during verification	`{ error: string, code?: string }`
`ae:cancel`	User cancelled the verification	`{}`

Event Details

ae:ready

Fired once when the widget has fully loaded and is ready to interact with. Use this event to show or enable your verification UI.

ae:started

Fired when the user begins the verification process (e.g. clicks "Start Verification"). The level field contains the verification level being performed.

ae:complete

Fired when the user has completed all verification steps and the submission has been sent. The verificationId is the internal reference. The status is typically pending (awaiting admin review) but may be approvedfor age_only auto-decisions.

After receiving this event, poll the status from your backend using the secret key. See the Status Polling guide.

ae:error

Fired when a recoverable or fatal error occurs. The error field contains a human-readable message. The optional code field provides a machine-readable error identifier.

ae:cancel

Fired when the user explicitly cancels the verification process. You may choose to close the widget, show an alternative flow, or prompt the user to try again.

Complete Example

window.addEventListener('message', (event) => {
  // Only trust messages from AgeEvidence
  if (event.origin !== 'https://ageevidence.com') return;

  const { type, data } = event.data;

  switch (type) {
    case 'ae:ready':
      console.log('Widget loaded');
      document.getElementById('loading-spinner')?.remove();
      break;

    case 'ae:started':
      console.log('Verification started:', data.level);
      break;

    case 'ae:complete':
      console.log('Submitted:', data.verificationId, data.status);
      // Poll from your backend (uses secret key)
      fetch(`/api/check-verification?id=${data.verificationId}`)
        .then(r => r.json())
        .then(result => {
          if (result.verified) {
            window.location.href = '/dashboard';
          }
        });
      break;

    case 'ae:error':
      console.error('Error:', data.error, data.code);
      showErrorMessage(data.error);
      break;

    case 'ae:cancel':
      console.log('User cancelled');
      document.getElementById('ae-verification')?.remove();
      break;
  }
});