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
verdict	Verdict	Public visit verdict received
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
traffic_signals	TrafficSignal[]	Public classification signals for the visit
traffic_back	boolean?	Whether to redirect the user (traffic back)
challenge	boolean?	Whether to show a challenge
challenge_design	string?	Challenge template identifier

TrafficSignal Object

Field	Type	Description
scope	"givt" | "sivt" | "context"	Signal type: general invalid traffic, suspicious invalid traffic, or rule context
name	string	Public signal name, for example known_crawler, click_rate_limit, device_spoofing, hosting_like, proxy_like
confidence	"low" | "medium" | "high"	Signal confidence

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: 'verdict',
  handler: function(verdict) {
    console.log('Verdict received', verdict.traffic_signals);
  }
});

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. verdict fires with public traffic signals
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

Challenge events only occur when applicable. The ready event always fires — even if there were no signals 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 traffic signals to analytics

(window.adsafee = window.adsafee || []).push({
  on: 'verdict',
  handler: function(verdict) {
    gtag('event', 'adsafee_verdict', {
      signals: verdict.traffic_signals
        .map(function(signal) {
          return signal.scope + '/' + signal.name + '/' + signal.confidence;
        })
        .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