feat(rokt): fire early selectPlacements preselect call on configured pageviews

[alexs-mparticle]

Summary

Adds an early, speculative selectPlacements call ("preselect") that fires on a configured pageview before the customer reaches the page a placement is actually needed on, so Rokt's backend can warm its fingerprint-matching cache ahead of time.

• Config (kits/rokt/src/preselectionConfig.ts): a hardcoded list (to move to a server-delivered kit setting later) of entries keyed by accountId + trigger pathname, each naming the targetPageIdentifier to pre-select for and the attributeKeys required to fire. pathname (where the call fires) and targetPageIdentifier (the page being pre-selected for) are deliberately separate fields — conflating them was the root cause of a prior production incident where a speculative call resolved against the wrong page.
• Trigger (kits/rokt/src/preselection.ts, wired into Rokt-Kit.ts#process): on every pageview, maybeFirePreselect looks up a matching config entry, then requires a valid user identifier, and all of the entry's attributeKeys present on the pageview event or in userAttributes. Any missing key logs a PRESELECT_MISSED diagnostic and the call does not fire — partial attribute sets are never sent.
• Dedup: a successful fire is cached in localStorage (activePreselectStorage.ts) for 60s keyed by account + pathname; a repeat pageview with unchanged attributes within that window is skipped (PRESELECT_SKIPPED) rather than re-fired.
• Queueing: if the Rokt launcher isn't attached yet, the dispatch is queued (PRESELECT_QUEUED) instead of dropped, and flushed once the launcher attaches. initRoktLauncher calls attachKit before flushing the queue, not after, so a same-page live selectPlacements call (e.g. a partner's own placement request) always gets its call started first and can't be pre-empted by our own warm-up request.
• Wire contract: the dispatch sets preselect: true, identifier: <targetPageIdentifier>, and omitUrl: true as top-level selectPlacements options (not inside attributes) — this is what the launcher reads to emit the rokt-is-pre-selection header that keeps speculative traffic out of real placement counts. cacheMatchKeys is passed as the entry's attributeKeys array on both the preselect call and the later live call from the same config entry, so the live call can match against the warmed cache.
• Isolation from RoktManager: the preselect path calls selectPlacements directly — no passback ID capture, no identify-on-mismatch, and no customer-facing SelectPlacements analytics event is logged for it, so it's invisible to the rest of the SDK and to the customer's own event stream.

PRESELECTION_CONFIG currently has one entry (a pilot account, triggering on /checkout, pre-selecting a prod.rokt.conf placement) to validate the mechanism end-to-end; more entries get added as additional partners onboard.

Test plan

• npx vitest run — full suite passing, including dedicated preselect coverage in kits/rokt/test/src/tests.spec.ts (queueing/flush, identity gating, missing-attribute handling, dedup TTL, diagnostic codes, cacheMatchKeys shape on both preselect and live calls)
• npm run build — builds cleanly

[cursor]

PR Summary

Medium Risk
Changes when and how selectPlacements runs and which attributes/keys are sent, with localStorage dedupe and hardcoded partner config—incorrect config or launcher contract could affect placement timing or caching behavior.

Overview
Adds Rokt placement preselection: on matching pageviews, the kit can fire an early selectPlacements with preselect: true (when the launcher sets enablePreselection) to warm Rokt’s backend path before the normal placement call.

Matching is driven by a new hardcoded PRESELECTION_CONFIG (account ID + pathname → target page identifier + attribute keys). Attributes are taken from the pageview event first, then user attributes; dispatch requires a valid user identity and skips duplicate fires within a 60s localStorage window when attributes are unchanged. Attempts before the kit/launcher is ready are queued and flushed after attach.

selectPlacements now optionally sends cacheMatchKeys (from the same config, keyed by identifier) when preselection is enabled, and does not emit the customer-facing selectPlacements mParticle event for preselect dispatches. New placement diagnostics cover preselect fired/missed/queued/skipped outcomes. djb2 and LS_NAMESPACE_KEY are centralized in shared modules for reuse.

^{Reviewed by Cursor Bugbot for commit ce2ca98. Bugbot is set up for automated code reviews on this repo. Configure here.}

[crisryantan]

Reviewed against our follow-ups, The sticky-attribute fix you found is the right catch and was the thing I would most have expected to bite.

Three below. The first two mean that as written a fired preselect would pre-select the page it fired from and go out untagged, which together is the February shape.

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7823837. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rmi22186]

nit: string