feat(sdk): emit keyword classifications in ctxTargetingKeyValues() - #317
Open
pierluc-codes wants to merge 3 commits into
Open
feat(sdk): emit keyword classifications in ctxTargetingKeyValues()#317pierluc-codes wants to merge 3 commits into
pierluc-codes wants to merge 3 commits into
Conversation
Follow-up to #313, which rendered keyword classifications but left the page prose describing a categories-only response. Update the vanilla ctx_segments demos (both the default and nocookies copies): - Intro now covers both classification methods (taxonomy categories and free-form keywords), not just categories. - Response-shape section leads with the ContextualSegmentsResponse signature block, then a Field/Description table per classification kind (categories, keywords) instead of the cramped inline shape. - Add a note that ctxTargetingKeyValues() derives GAM key-values from classifications.categories only; the keywords array is not part of the map. The SDK ContextualSegmentsResponse type and ctxTargetingKeyValues() keyword handling remain unchanged, tracked separately in PRODUCT-3852. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The contextual segments API returns keyword classifications in classifications.keywords alongside classifications.categories, but ctxTargetingKeyValues() only emitted category ids grouped by taxonomy. Emit keywords as GAM targeting key-values too. By default they are emitted under the key "ctx_kw"; a new options argument lets callers rename the key (keywordKey), cap the count (maxKeywords, default 10), or opt out entirely (keywordKey: ""). Keyword values are ordered by prominence (most prominent first) and sanitized to GAM's value rules: lowercased, reserved characters stripped, and truncated to the 40-character value limit, which keeps output within GAM's 61,440-char ad-request URL budget. Add the ContextualKeyword type and keywords field on ContextualClassifications, and unit tests for default emission, key rename, opt-out, prominence sort, maxKeywords cap, sanitization, case-insensitive dedupe, and empty-key omission. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reflect the default-on keyword emission in the README and the vanilla ctxSegments demos: - README: add keywords to the ContextualSegmentsResponse shape, describe the classifications container, and document the default ctx_kw key plus the keywordKey/maxKeywords options and opt-out. - demos: rewrite the GAM key-values section to describe default keyword emission (previously stated keywords were not emitted), and add an example of the default map returned by ctxTargetingKeyValues(). Example category ids and keywords are kept consistent with IAB Content Taxonomy 3.1 (Business/Advertising/Technology). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
pierluc-codes
force-pushed
the
feat/ctx-keyword-key-values
branch
from
August 14, 2026 16:25
7a411b7 to
4f22af1
Compare
mosherBT
self-requested a review
August 14, 2026 17:40
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The contextual segments API returns keyword classifications in
classifications.keywordsalongsideclassifications.categories, butctxTargetingKeyValues()only emitted category ids grouped by taxonomy, so keyword signals had no path into an ad server. This adds keywords to the targeting key-values so publishers can activate them in GAM. Tracked in PRODUCT-3852.What Changed
lib/edge/contextual_segments.ts:ctxTargetingKeyValues()now also emits keyword classifications. They are emitted by default under the keyctx_kw. A newoptionsargument ({ keywordKey?, maxKeywords? }) lets callers rename the key, cap the count (default 10), or opt out (keywordKey: "").prominence(most prominent first) and sanitized to GAM's value rules: lowercased, reserved characters stripped, and truncated to the 40-char value limit. Sorting + cap + per-value limit keep output within GAM's 61,440-char ad-request URL budget.ContextualKeywordtype andkeywordsfield onContextualClassifications;ctxTargetingKeyValues()on the SDK accepts the newoptionsarg.ctx_segmentsdemos (both copies) updated to document defaultctx_kwemission and the options. Example ids/keywords are consistent with IAB Content Taxonomy 3.1 (Business/Advertising/Technology).Notes
Behavior change (default-on): existing callers of
ctxTargetingKeyValues()will start receiving actx_kwkey whenever the response carries keywords. Pass{ keywordKey: "" }to opt out. Not source-breaking (signature is backward-compatible), but the emitted map changes.The
keywordKeyvalue must match a free-form (dynamic) custom targeting key configured in GAM.Breaking change
Requires release