Skip to content

Add GAM cohort attribution for Trusted Server traffic - #1028

Open
aram356 wants to merge 17 commits into
mainfrom
docs/gam-ts-cohort-attribution-spec
Open

Add GAM cohort attribution for Trusted Server traffic#1028
aram356 wants to merge 17 commits into
mainfrom
docs/gam-ts-cohort-attribution-spec

Conversation

@aram356

@aram356 aram356 commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Add a default-off gam_attribution_enabled GPT option that applies fixed page-level ts=true targeting to eligible publisher documents whose rewritten head is emitted by Trusted Server, allowing GAM to describe treatment delivery while the production/control path remains unmarked.
  • Apply targeting before publisher GPT initialization through the early bootstrap, with an exact document.currentScript attribute-gated TSJS fallback that fails closed and isolates setConfig failures.
  • Preserve auction behavior, consent, the slot-level ts_initial lifecycle, and publisher/Prebid targeting while documenting the collision audit, reporting contract, rollout, monitoring limits, and drain-safe rollback sequence.

Changes

File Change
crates/trusted-server-cli/tests/config_env_overlay.rs Verify the GAM attribution environment override is applied when the corresponding TOML leaf exists.
crates/trusted-server-core/src/creative_opportunities.rs Characterize that operator-provided slot-level ts targeting remains forwarded unchanged.
crates/trusted-server-core/src/html_processor.rs Add integration-provided attributes to publisher TSJS tags and cover enabled, disabled, and source-order behavior.
crates/trusted-server-core/src/integrations/gpt.rs Add the default-off setting and drive both inline activation and fallback authorization from the parsed GPT configuration.
crates/trusted-server-core/src/integrations/gpt_bootstrap.js Queue page-level ts=true before the existing adInit guard and isolate attribution failures from later GPT commands.
crates/trusted-server-core/src/integrations/registry.rs Add and test the integration hook that supplies trusted static attributes for publisher bundle tags.
crates/trusted-server-core/src/publisher.rs Cover streaming-head attribution semantics and operator-targeting preservation.
crates/trusted-server-core/src/tsjs.rs Render trusted static attributes on publisher TSJS tags without changing generic or creative tag output.
crates/trusted-server-integration-tests/browser/tests/shared/script-injection.spec.ts Verify attribution metadata is absent from the default-off integration fixture.
crates/trusted-server-integration-tests/fixtures/configs/trusted-server.integration.toml Keep the new configuration leaf explicit and disabled in integration tests.
crates/trusted-server-js/lib/src/integrations/gpt/index.ts Add the executing-script-gated bundle fallback for page-level GAM targeting.
crates/trusted-server-js/lib/test/integrations/gpt/ad_init.test.ts Verify SPA cleanup does not clear the page-level ts key.
crates/trusted-server-js/lib/test/integrations/gpt/gpt_bootstrap.test.ts Exercise activation ordering, disabled behavior, unavailable or throwing setConfig, and bootstrap continuity.
crates/trusted-server-js/lib/test/integrations/gpt/index.test.ts Cover exact fallback authorization, fail-closed cases, duplicate-ID decoys, cloned tags, and error isolation.
crates/trusted-server-js/lib/test/integrations/prebid/index.test.ts Characterize publisher and Prebid-generated ts targeting across refreshes.
docs/guide/integrations/gpt.md Document configuration, environment-overlay requirements, attribution semantics, collision checks, reporting, rollout, and rollback.
docs/superpowers/plans/2026-07-15-gam-ts-cohort-attribution.md Add the reviewed implementation and verification plan.
docs/superpowers/specs/2026-07-15-gam-ts-cohort-attribution-design.md Finalize the fixed marker contract, streaming meaning, reporting scope, and operational safeguards.
trusted-server.example.toml Add the explicit default-off setting and environment-overlay guidance.

Launch gates

This PR completes the repository implementation. Starting the cohort remains gated on target-network GAM provisioning, cross-system collision and privacy/CSP audits, a paired-report dry run, and router-controlled treatment validation described in the design.

GAM results are descriptive delivery attribution, not causal treatment-effect estimates.

Closes

Closes #1027

Test plan

  • cargo test-fastly && cargo test-axum
  • cargo clippy-fastly && cargo clippy-axum
  • cargo fmt --all -- --check
  • JS tests: cd crates/trusted-server-js/lib && npx vitest run (44 files, 847 tests)
  • JS format: cd crates/trusted-server-js/lib && npm run format
  • Docs format: cd docs && npm run format
  • WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
  • Manual testing via fastly compute serve: confirmed the inline flag, activation attribute, GPT page targeting, and decoded cust_params containing ts=true on a real GAM request
  • Other: Cloudflare and Spin adapter tests/clippy, cross-adapter parity, native CLI tests, and Next.js/WordPress browser integration suites

Checklist

  • Changes follow CLAUDE.md conventions
  • No unwrap() added to production code
  • Logging follows project conventions; no direct stdout/stderr logging was added
  • New code has tests
  • No secrets or credentials committed

@aram356 aram356 added documentation Improvements or additions to documentation and removed documentation Improvements or additions to documentation labels Aug 13, 2026
@aram356 aram356 linked an issue Aug 13, 2026 that may be closed by this pull request
7 tasks
@prk-Jr prk-Jr changed the title Add GAM ts cohort attribution design spec Add GAM cohort attribution for Trusted Server traffic Aug 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

GAM attribution for Trusted Server A/B traffic (page-delivery marker)

3 participants