SDK Events

The SDK notifies you about key stages of visit verification. You can subscribe to events to redirect users after verification, send data to analytics, or handle errors.

Available Events

Event	Data	Description
ready	—	SDK has completed verification — fingerprint collected, verdict received, challenge (if required) completed. Safe to proceed
fraud-detected	{ verdict: Verdict }	Visit classified as fraud
challenge-shown	—	Challenge displayed to the user
challenge-complete	{ passed: boolean }	Challenge finished. passed — whether the user passed (true) or not (false)
error	unknown	An error occurred during SDK operation. The handler receives the error directly, not wrapped in an object

Verdict Object

Field	Type	Description
fraud	boolean	true if the visit is considered fraudulent
reasons	string[]	Reasons — names of triggered rules
traffic_back	boolean?	Whether to redirect the user (traffic back)
challenge	boolean?	Whether to show a challenge
challenge_design	string?	Challenge template identifier

How to Subscribe

Add a handler via window.adsafee.push(). You can subscribe before the SDK loads — handlers will be called automatically once the SDK initializes:

(window.adsafee = window.adsafee || []).push({
  on: 'ready',
  handler: function() {
    console.log('Verification complete');
  }
});

One-time Subscription

Use once instead of on — the handler will fire once and be removed:

(window.adsafee = window.adsafee || []).push({
  once: 'fraud-detected',
  handler: function(data) {
    console.log('Fraud detected', data.verdict);
  }
});

Unsubscribe

Pass the same function that was used when subscribing:

function onError(err) {
  console.error(err);
}

// Subscribe
(window.adsafee = window.adsafee || []).push({
  on: 'error',
  handler: onError
});

// Unsubscribe
window.adsafee.push({
  off: 'error',
  handler: onError
});

Event Order

1. SDK loads and collects visit data
2. Sends data for verification and receives a verdict
3. If the visit is classified as fraud — fraud-detected fires
4. If a challenge is required — challenge-shown fires, then after completion — challenge-complete
5. When all verification is complete — ready fires
6. On error at any stage — error fires

Steps 3 and 4 only occur when applicable. The ready event always fires — even if there was no fraud or challenge.

When to use ready

Subscribe to ready to perform an action after full verification — for example, redirect the user or unlock content.

Errors do not block execution

The error event reports problems but does not stop the SDK. The ready event will fire regardless — both after a successful verification and after an error.

Examples

Redirect after verification

(window.adsafee = window.adsafee || []).push({
  once: 'ready',
  handler: function() {
    window.location.href = '/thank-you';
  }
});

Send fraud data to analytics

(window.adsafee = window.adsafee || []).push({
  on: 'fraud-detected',
  handler: function(data) {
    gtag('event', 'fraud_detected', {
      reasons: data.verdict.reasons.join(', ')
    });
  }
});

Track challenge results

(window.adsafee = window.adsafee || []).push({
  on: 'challenge-complete',
  handler: function(data) {
    console.log(data.passed ? 'Challenge passed' : 'Challenge failed');
  }
});

Error monitoring

(window.adsafee = window.adsafee || []).push({
  on: 'error',
  handler: function(err) {
    Sentry.captureException(err);
  }
});

What's next

• Set up challenge — when and how to enable interactive verification
• Handle fraudulent traffic — flag, redirect, or block
• Metrics reference — all metrics, including Challenge Total and Challenge Pass