Skip to content

feat(audience): add trackConversion for pixel/CAPI dedup - #2932

Merged
JCSanPedro merged 2 commits into
mainfrom
sdk-719-conversion-event-id
Jul 29, 2026
Merged

JCSanPedro merged 2 commits into
mainfrom
sdk-719-conversion-event-id

Conversation

@JCSanPedro

Copy link
Copy Markdown
Contributor

Summary

Adds a conversion event id primitive to @imtbl/audience so a browser pixel event and its server-side Conversions API (CAPI) counterpart can be deduplicated on a shared id. Today Game Page fires browser pixels client-side and postbacks fires CAPI events server-side for the same sign_up, with no common id, so ad networks double-count the conversion.

This is piece 1 of 3 (SDK-719). Follow-ups: SDK-720 (Play fires vendor pixels with the shared id) and SDK-721 (postbacks reads the shared id + event-name mapping).

Changes

  • Audience.trackConversion(event, properties?) - behaves like track(), and additionally: classifies the visit's network from the session-cached first-touch attribution (the same signals that drive server-side attribution), mints a shared id for dedup-capable networks (Meta, TikTok, Reddit), stamps it onto the event under the reserved _imtbl_conversion_id / _imtbl_conversion_network properties, and returns { eventId, network }. The caller passes eventId to the browser pixel (e.g. Meta fbq('track', 'CompleteRegistration', {}, { eventID })).
  • Audience.getAttributionNetwork() instance method - classifies from the client's cached snapshot so client- and server-side attribution agree even after the landing URL's query params are gone.
  • Standalone getAttributionNetwork(attribution?) - retained and made optional-arg: classifies from a passed snapshot, else falls back to the live URL, for consumers that have a pixel but no SDK instance.
  • Reserved property contract in sdk/src/conversion.ts (_imtbl_conversion_id, _imtbl_conversion_network, DEDUP_CAPABLE_NETWORKS). These are a cross-service contract with the postbacks builders (SDK-721).

Breaking change

Removes isPaidMeta / isPaidTikTok / isPaidGoogle / isPaidReddit / isPaidX. The only consumer is Game Page (Play), which we control and which is updated in SDK-720 to use getAttributionNetwork().

Test plan

  • packages/audience/core unit tests pass (attribution classification, snapshot + live-URL paths)
  • packages/audience/sdk unit tests pass (trackConversion id minting, reserved props, consent gating, instance getAttributionNetwork)
  • Typecheck passes (incl. sdk.test-d.ts compile-time assertions)
  • Validated end-to-end once SDK-720 (Play) consumes the prerelease alpha build

Add a conversion event id primitive so a browser pixel event and its
server-side Conversions API counterpart can be deduplicated on a shared id.

- Add `Audience.trackConversion()`: classifies the visit's network from the
  session-cached first-touch attribution, mints a shared id for dedup-capable
  networks (Meta, TikTok, Reddit), stamps it onto the event under the reserved
  `_imtbl_conversion_id` / `_imtbl_conversion_network` properties, and returns
  `{ eventId, network }` for the caller to pass to the browser pixel.
- Add `Audience.getAttributionNetwork()` instance method (classifies from the
  cached snapshot) and keep a standalone `getAttributionNetwork(attribution?)`
  that falls back to the live URL for consumers without an SDK instance.
- Remove the `isPaid*` helpers in favour of the single network classifier.

BREAKING CHANGE: `isPaidMeta`/`isPaidTikTok`/`isPaidGoogle`/`isPaidReddit`/
`isPaidX` are removed; use `getAttributionNetwork()` instead.
@github-actions

Copy link
Copy Markdown

✅ Pixel Bundle Size — @imtbl/pixel

Metric Size Delta vs main
Gzipped 6968 bytes (6.80 KB) 0 bytes
Raw (minified) 19325 bytes 0 bytes

Budget: 10.00 KB gzipped (warn at 8.00 KB)

@github-actions

Copy link
Copy Markdown

✅ Audience Bundle Size — @imtbl/audience

Metric Size Delta vs main (e8f6eba)
Gzipped 11636 bytes (11.36 KB) +400 bytes
Raw (minified) 32650 bytes +1259 bytes

Budget: 24.00 KB gzipped (warn at 20.00 KB)

@nx-cloud

nx-cloud Bot commented Jul 29, 2026 •

Copy link
Copy Markdown

View your CI Pipeline Execution ↗ for commit 821bdac

Command Status Duration Result
nx release publish --tag alpha ✅ Succeeded 48s View ↗
nx run-many -p @imtbl/sdk,@imtbl/checkout-widge... ✅ Succeeded 1m 7s View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗


☁️ Nx Cloud last updated this comment at 2026-07-29 01:26:23 UTC

…or Nx 23

Nx 23 removed the top-level `release.releaseTagPattern` property (it moved to
the nested `release.releaseTag` object), which broke `nx release version` and
blocked all SDK publishes. Nest the pattern so releases work again.
@JCSanPedro
JCSanPedro marked this pull request as ready for review July 29, 2026 01:34
@JCSanPedro
JCSanPedro requested review from a team as code owners July 29, 2026 01:34
Comment thread nx.json
"releaseTagPattern": "{version}",
"releaseTag": {
"pattern": "{version}"
},

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixes pre release publish

@JCSanPedro
JCSanPedro merged commit 416cfe2 into main Jul 29, 2026
9 checks passed
@JCSanPedro
JCSanPedro deleted the sdk-719-conversion-event-id branch July 29, 2026 02:35

This branch was previously deployed

1 inactive deployment
npm-publish — bfee00cf Deployed Jul 29, 2026 by JCSanPedro via Publish Workflow #2218
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants