Paywalls

Features

Overview

The Paywalls Analytics Adapter emits VAI (Validated Actor Inventory) classification on each Prebid auction. VAI helps publishers distinguish human traffic and AI agents from non-human automation (sharing/preview bots, search crawlers, AI training scrapers, etc.), enabling them to segment and analyze performance by traffic class (yield, fill, viewability, buyer outcomes) in their existing analytics stack (GA4, GTM / dataLayer, or a custom callback).

Two key-value pairs are emitted per auction:

Key Example Description
vai_vat HUMAN Validated Actor Type — HUMAN, AI_AGENT, SHARING, or OTHER
vai_act ACT-1 Actor Confidence Tier — ACT-1, ACT-2, or ACT-3

If VAI is unavailable, both values are UNKNOWN.

The companion Paywalls RTD Provider injects VAI into ORTB2 and GAM targeting. The analytics adapter independently reads the same window.__PW_VAI__ global and routes classification to your analytics tool of choice.

Prerequisites

Load vai.js before Prebid.js initializes so that window.__PW_VAI__ is populated when auctions run:

<script src="/pw/vai.js"></script>
<script src="prebid.js"></script>

The adapter does not inject vai.js itself. See VAI Documentation for setup details.

Build

gulp build --modules=paywallsAnalyticsAdapter

Or with the recommended RTD provider:

gulp build --modules=rtdModule,paywallsRtdProvider,paywallsAnalyticsAdapter

Analytics Options

Name Type Scope Description Default
provider String Required Must be 'paywalls' —
options.output String Optional Output mode: 'gtag', 'dataLayer', or 'callback' 'callback'
options.samplingRate Number Optional Fraction of page views that emit analytics (0.0–1.0) 1.0
options.callback Function Optional Called with the metrics object when output is 'callback' null

Example Configuration

gtag (Google Analytics 4)
pbjs.enableAnalytics([{
  provider: 'paywalls',
  options: {
    output: 'gtag'
  }
}]);

Fires a GA4 event via the global gtag() function:

gtag('event', 'vai_auction', { vai_vat: 'HUMAN', vai_act: 'ACT-1' });
dataLayer (Google Tag Manager)
pbjs.enableAnalytics([{
  provider: 'paywalls',
  options: {
    output: 'dataLayer'
  }
}]);

Pushes to the GTM dataLayer array:

window.dataLayer.push({
  event: 'vai_auction',
  vai_vat: 'HUMAN',
  vai_act: 'ACT-1'
});

In GTM, create a Custom Event trigger on vai_auction to route the data to any tag.

callback (Custom Function)
pbjs.enableAnalytics([{
  provider: 'paywalls',
  options: {
    output: 'callback',
    callback: function (metrics) {
      console.log(metrics);
      // { vai_vat: 'HUMAN', vai_act: 'ACT-1' }
    }
  }
}]);

Sampling

Set samplingRate to control cost. The decision is made once per page load — all auctions on that page either emit or don’t.

pbjs.enableAnalytics([{
  provider: 'paywalls',
  options: {
    samplingRate: 0.1  // emit on ~10% of page views
  }
}]);

Privacy

VAI does not collect, store, or transmit user IDs, cookies, fingerprints, or PII. Classification is based on aggregate session-level behavioral signals processed entirely in the browser.

Registration

For questions or integration help, contact engineering@paywalls.net.

Further Reading