Paywalls Modules: VAI RTD Provider and Analytics Adapter#14541
Paywalls Modules: VAI RTD Provider and Analytics Adapter#14541paywalls-mike wants to merge 27 commits intoprebid:masterfrom
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dc9bc90910
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
- Register RTD submodule 'paywalls' with init, getBidRequestData, getTargetingData - ORTB2 split: site.ext.vai (iss, aud, dom, kid, assertion_jws) + user.ext.vai (vat, act) - Dynamic vai.js injection via loadExternalScript with poll/hook/timeout - Graceful degradation: never blocks the auction - 22 unit tests covering all acceptance criteria - Added to approvedLoadExternalScriptPaths whitelist
- paywallsRtdProvider_example.html: E2E test with 5 assertions (ORTB2 site/user enrichment, GAM targeting, timing budget, VAI load) - mock-vai.js: local VAI mock for self-contained testing - Supports ?real mode (real vai.js from worker) and ?degrade mode (verifies graceful degradation with unreachable script)
- Overview, build instructions, configuration parameters - ORTB2 split placement: site.ext.vai (provenance) + user.ext.vai (classification) - GAM targeting keys (vai_vat, vai_act) - Activity Controls, privacy section, how-it-works - Testing instructions for unit and integration tests
- Publisher-hosted is preferred (same-origin, no CORS, dom claim match) - Paywalls-hosted uses paywalls.net (not cdn.paywalls.net) - Clarify CDN/server integration vs reverse proxy
- Correct activity name: loadExternalScript (not fetchBids) - Update example default to false (realistic scenario) - Editorial refinements
- Fix broken VAI URL in RTD provider links section (docs.publishers → docs/publishers) - Normalize all VAI URLs to https://docs.paywalls.net/publishers/vai - Align RTD provider heading structure with analytics adapter (# Overview) - Clarify params.waitForIt vs top-level waitForIt distinction - Document __PW_VAI_HOOK__, exp checking, and localStorage key in How It Works
There was a problem hiding this comment.
Pull request overview
Adds Paywalls modules to integrate VAI (Validated Actor Inventory) into Prebid.js auctions, enriching ORTB2/GAM targeting via an RTD provider and emitting per-auction classification via an analytics adapter.
Changes:
- Introduces
paywallsRtdProviderRTD submodule to load VAI and mergesite.ext.vai/user.ext.vaiinto ORTB2 plusvai_vat/vai_actinto GAM targeting. - Introduces
paywallsAnalyticsAdapterto emitvai_vat/vai_actper auction viagtag,dataLayer, or callback (with sampling + de-dup). - Adds module docs, unit tests, integration example pages + mock VAI script, and updates the ESLint allowlist for
loadExternalScriptusage.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
modules/paywallsRtdProvider.js |
New RTD provider implementing VAI discovery/loading and ORTB2 + targeting enrichment. |
modules/paywallsRtdProvider.md |
Documentation for RTD config, ORTB2 output, GAM targeting, and activity controls. |
modules/paywallsAnalyticsAdapter.js |
New analytics adapter emitting VAI classification per auction to publisher analytics destinations. |
modules/paywallsAnalyticsAdapter.md |
Documentation for analytics adapter config, output modes, sampling, and privacy notes. |
test/spec/modules/paywallsRtdProvider_spec.js |
Unit tests for VAI payload detection, ORTB2 merge behavior, targeting, and timeouts. |
test/spec/modules/paywallsAnalyticsAdapter_spec.js |
Unit tests for classification reading, emission modes, sampling, and de-dup behavior. |
plugins/eslint/approvedLoadExternalScriptPaths.js |
Approves the two new modules for loadExternalScript. |
integrationExamples/gpt/paywallsRtdProvider_example.html |
E2E example page for RTD provider behavior (including degrade/real modes). |
integrationExamples/gpt/paywallsAnalyticsAdapter_example.html |
E2E example page for analytics emission behavior (including degrade/real modes). |
integrationExamples/gpt/mock-vai.js |
Mock VAI script used by integration examples to simulate vai.js. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
paywalls-mike
force-pushed
the
agent/paywalls-rtd-provider
branch
from
dc9bc90 to
c2e15ae
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c2e15aea5d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
Addressed automated review feedback in commit de4cf00. Implemented fixes:
Regression coverage added for these behaviors. Validation run locally:
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: de4cf00754
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
paywalls-mike
force-pushed
the
agent/paywalls-rtd-provider
branch
from
de4cf00 to
12b1099
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 12b1099de4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
Companion docs PR: prebid/prebid.github.io#6457 |
- P1: Store late VAI hook payloads for subsequent auctions (was dropping permanently after timeout) - Fix waitForIt=0 treated as falsy (use typeof check instead of ||) - Clean up timers and hook in resolve() to avoid leaking globals - Preserve existing __PW_VAI_HOOK__ instead of clobbering - Fix ensureVai skipping injection when __PW_VAI__ is truthy but invalid - Clamp samplingRate to [0,1] with warning - Use Object.create(null) for emittedAuctions map - Fix init() JSDoc to match actual behavior (caches, not injects) - Add regression tests for all bug fixes
paywalls-mike
force-pushed
the
agent/paywalls-rtd-provider
branch
from
12b1099 to
d145be8
Compare
- buildOrtb2 now uses 3-scope structure:
site.ext.vai: { iss, dom }
user.ext.vai: { iss, vat, act, mstk, jws }
imp[].ext.vai: { pvtk } (when available)
- Removed aud, kid, assertion_jws from ORTB2 injection
- iss uses bare domain (paywalls.net)
- mergeOrtb2Fragments enriches adUnit.ortb2Imp with pvtk
- paywallsRtdProvider.md: rewritten ORTB2 Output section (3 scopes)
- paywallsAnalyticsAdapter.md: updated scope refs, assertion_jws→jws
- Tests: updated MOCK_VAI fixture, buildOrtb2 assertions, added pvtk tests
- 27 RTD tests pass, 33 analytics tests pass, lint clean
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b0763949ee
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aa286d0043
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e6bce50f69
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…-clean on delivery
|
Tread carefully! This PR adds 30 linter errors (possibly disabled through directives):
|
Coverage Report for CI Build 24470513340Warning Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes. Coverage increased (+0.006%) to 96.386%Details
Uncovered Changes
Coverage RegressionsNo coverage regressions found. Coverage Stats
💛 - Coveralls |
… site.ext.vai.jws reference
- Rename params.waitForIt to params.timeout to avoid collision with RTD framework's Boolean waitForIt (reviewer feedback)
- Fix integration example: site.ext.vai only has {iss, dom}, jws lives on user.ext.vai
- Update docs and tests to match
Remove loadExternalScript-based vai.js injection from both modules. Publishers now load vai.js via a standard script tag before Prebid initializes. Both modules read window.__PW_VAI__ directly. RTD Provider: - Remove loadExternalScript, getStorageManager, polling/hook/timeout - getBidRequestData reads window.__PW_VAI__ synchronously - Place VAI data under site.ext.data.vai / user.ext.data.vai (FPD convention) - imp[].ext.vai unchanged (not first-party data) - 22 tests rewritten and passing Analytics Adapter: - Remove loadExternalScript, ensureVai(), scriptUrl config - getVaiClassification reads window.__PW_VAI__ directly - 29 tests rewritten and passing Integration Examples: - Both example pages load vai.js via script tag - Support ?real (production), ?degrade (no vai.js), default (mock) - Remove scriptUrl/waitForIt/auctionDelay from configs
…AI signals Update documentation to reflect the correct ORTB2 data structure: - site.ext.vai -> site.ext.data.vai - user.ext.vai -> user.ext.data.vai - imp[].ext.vai unchanged (imp-level extensions are correct as-is) Per ORTB2 convention, arbitrary/custom values belong in ext.data rather than directly in ext. The code already uses ext.data; this aligns the docs.
|
Whoa there partner! This project is migrating to typescript. Consider changing the new JS files to TS, with well-defined types for what interacts with the prebid public API (for example: bid params and configuration). Thanks!
|
The paywalls RTD provider and analytics adapter no longer call loadExternalScript, so remove both entries from approvedLoadExternalScriptPaths.
|
Whoa there partner! This project is migrating to typescript. Consider changing the new JS files to TS, with well-defined types for what interacts with the prebid public API (for example: bid params and configuration). Thanks!
|
|
@codex can you check if the public interface is strongly typed and if not please show how to type the public interface: | |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b84f0e25b0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| function getBidRequestData(reqBidsConfigObj, callback, rtdConfig, userConsent) { | ||
| const vai = getVaiPayload(); | ||
| if (vai) { | ||
| mergeOrtb2Fragments(reqBidsConfigObj, vai); | ||
| } else { |
There was a problem hiding this comment.
This path never reads rtdConfig.params and immediately attempts enrichment from window.__PW_VAI__, so the advertised public settings (params.scriptUrl, params.timeout) have no runtime effect. In deployments where VAI arrives after auction start, publishers can set these knobs and still get no ORTB2 enrichment because the callback is effectively unconditional. Please either implement the param-driven load/wait behavior here (with a typed params shape) or remove these fields from the public interface.
Useful? React with 👍 / 👎.
| adapterConfig.output = options.output || 'callback'; | ||
| const rawRate = typeof options.samplingRate === 'number' ? options.samplingRate : 1.0; | ||
| adapterConfig.samplingRate = Math.max(0, Math.min(1, rawRate)); |
There was a problem hiding this comment.
options.scriptUrl from analytics config
enableAnalytics parses output, samplingRate, and callback only, so options.scriptUrl in the documented/public interface is currently a no-op. If integrators rely on that field to configure VAI loading, the adapter still reads only the window global and emits UNKNOWN, which is a functional mismatch with the interface contract. Please either implement script URL handling here or drop the option and define a typed options interface so unsupported keys are explicit.
Useful? React with 👍 / 👎.
|
Whoa there partner! This project is migrating to typescript. Consider changing the new JS files to TS, with well-defined types for what interacts with the prebid public API (for example: bid params and configuration). Thanks!
|
|
looks like your md file is out of date |
|
Whoa there partner! This project is migrating to typescript. Consider changing the new JS files to TS, with well-defined types for what interacts with the prebid public API (for example: bid params and configuration). Thanks!
|
|
Whoa there partner! This project is migrating to typescript. Consider changing the new JS files to TS, with well-defined types for what interacts with the prebid public API (for example: bid params and configuration). Thanks!
|
Type of issue
New module (RTD Provider + Analytics Adapter)
Description
Adds two new Paywalls modules that integrate VAI (Validated Actor Inventory) into Prebid.js:
Paywalls RTD Provider (
paywallsRtdProvider.js) — Automates VAI loading, timing, and signal injection into the bid stream:site.ext.vai(domain provenance + signed assertion) anduser.ext.vai(actor classification)vai_vatandvai_actkey-value pairs per ad unitPaywalls Analytics Adapter (
paywallsAnalyticsAdapter.js) — Emits VAI classification (vat,act) per auction to the publisher's analytics pipeline (GA4gtag, GTMdataLayer, or custom callback), enabling publishers to segment performance by traffic class in their existing reporting stack.What is VAI?
VAI classifies page impressions by actor type (human, AI agent, sharing/preview bot, other) and confidence tier (ACT-1 through ACT-3), producing a cryptographically signed JWS assertion that SSPs and DSPs can independently verify. No user identifiers, PII, cookies, or fingerprints are involved — classification is based on aggregate session-level behavioral signals processed entirely in the browser.
ORTB2 placement
Test Results
Lint
Unit Tests
Coverage
All metrics exceed the 80% threshold.
Files Changed
modules/paywallsRtdProvider.jsmodules/paywallsRtdProvider.mdmodules/paywallsAnalyticsAdapter.jsmodules/paywallsAnalyticsAdapter.mdtest/spec/modules/paywallsRtdProvider_spec.jstest/spec/modules/paywallsAnalyticsAdapter_spec.jsintegrationExamples/gpt/paywallsRtdProvider_example.htmlintegrationExamples/gpt/paywallsAnalyticsAdapter_example.htmlintegrationExamples/gpt/mock-vai.jsExternal Script Loading
None. Publishers must coordinate the deployment of the vai.js tag prior to enabling these prebid.js modules
Privacy
Steps to reproduce / test
Platform details
Other information