Skip to content

Document GPT diagnostics attribution and correlation evidence - #1025

Open
prk-Jr wants to merge 1 commit into
mainfrom
1014-gpt-diagnostics-doc-completeness
Open

Document GPT diagnostics attribution and correlation evidence#1025
prk-Jr wants to merge 1 commit into
mainfrom
1014-gpt-diagnostics-doc-completeness

Conversation

@prk-Jr

@prk-Jr prk-Jr commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Complete the public GPT Runtime Diagnostics guide against the behavior merged in Attribute GPT renders to Trusted Server on observed evidence #997, so an operator can interpret request-path, delivery, replacement, and attribution evidence rather than only open the console.
  • Document the one server-side effect of enabling the integration that the guide never mentioned: the per-auction hb_auction_id correlation token published into window.tsjs.bids, and the targeting boundary that keeps it out of the GAM ad request.
  • Remove a stale claim carried over from the pre-Attribute GPT renders to Trusted Server on observed evidence #997 implementation ("No creative-provenance or auction attribution claims") and make the diagnostics guide reachable from the GPT integration page.

Changes

File Change
docs/guide/integrations/gpt-diagnostics.md New "Auction correlation token" section (token format, per-auction minting, not EC-derived, not a GAM targeting key, absent without winning bids); badge content and delivery-label table; creative-bridge failure table with the bridge condition that triggers each category; Ad Manager identifier normalization (positive whole numbers, eight-ID list cap); adInit refresh scoped context alongside Prebid's; three new troubleshooting entries for unattributed/competing refreshes, candidate_unconfirmed delivery, and missing correlation evidence (all eight attribution reasons); exact ?ts_console=1 activation and ?ts_console=0 deactivation examples
docs/guide/integrations/gpt.md Link the diagnostics guide from "Ads Not Rendering" troubleshooting and from "Next Steps"
docs/guide/integrations-overview.md Replace the stale "no attribution claims" bullet with the delivery-evidence, request-path, and Ad Manager identifier capabilities, keeping the evidence boundary explicit

Closes

Closes #1014

Test plan

  • Docs format: cd docs && npm run format
  • Docs lint: cd docs && npm run lint
  • Docs build: cd docs && npm run build (VitePress build succeeds; #auction-correlation-token anchor and sidebar/integration links resolve in the built output)
  • cargo fmt --all -- --check
  • JS format: cd crates/trusted-server-js/lib && npm run format
  • cargo test-fastly && cargo test-axum — not run: no Rust source changed
  • cargo clippy-fastly && cargo clippy-axum — not run: no Rust source changed
  • JS tests: cd crates/trusted-server-js/lib && npx vitest run — not run: no JS source changed
  • Other: every documented value traced back to source — request paths, opportunities, delivery states, response classes, creative failures, and attribution reasons against crates/trusted-server-js/lib/src/core/types.ts and .../gpt_diagnostics/store.ts; token minting and gating against crates/trusted-server-core/src/publisher.rs; targeting keys against crates/trusted-server-js/lib/src/integrations/gpt/index.ts; badge labels against .../gpt_diagnostics/badges.ts; identifier caps against .../gpt_diagnostics/observer.ts

Checklist

  • Changes follow CLAUDE.md conventions
  • No unwrap() in production code — use expect("should ...") (documentation only; no code changed)
  • Uses tracing macros (not println!) (documentation only; no code changed)
  • New code has tests (documentation only; no code changed)
  • No secrets or credentials committed — examples use publisher.example.com and a fictional token value

Complete the public guide against the behavior merged in #997. Cover the
per-auction hb_auction_id correlation token and the targeting boundary that
keeps it out of the ad request, badge delivery labels, creative-bridge failure
triggers, Ad Manager identifier normalization, and the adInit refresh context.

Add troubleshooting for unattributed and competing refreshes, unconfirmed
candidate delivery, and missing correlation evidence. Link the guide from the
GPT integration page, use the exact ts_console=1 activation example, and drop
the integrations overview claim that diagnostics make no attribution claims.
@prk-Jr prk-Jr self-assigned this Aug 13, 2026
@aram356 aram356 added this to the 202608 milestone Aug 13, 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.

Document GPT request and delivery traceability in VitePress

2 participants