Skip to content

feat(audience): add Audience class with consent, tracking, and identity#2826

Merged
JCSanPedro merged 5 commits intomainfrom
feat/audience-3-sdk-class
Apr 8, 2026
Merged

feat(audience): add Audience class with consent, tracking, and identity#2826
JCSanPedro merged 5 commits intomainfrom
feat/audience-3-sdk-class

Conversation

@ImmutableJeffrey
Copy link
Copy Markdown
Contributor

@ImmutableJeffrey ImmutableJeffrey commented Apr 5, 2026

Summary

Adds the Audience class to @imtbl/audience (renamed from @imtbl/audience-sdk) — the web SDK for consent-aware event tracking and player identity.

import { Audience } from '@imtbl/audience';

const audience = Audience.init({
  publishableKey: 'pk_imtbl_...',
  environment: 'production',
  consent: 'anonymous',
});

audience.page();
audience.track('purchase', { item: 'sword', price: 9.99 });
audience.identify('user@example.com', 'email', { name: 'Jane' });
audience.setConsent('full');
audience.shutdown();

What's included

  • Audience.init() with track, page, identify, alias, setConsent, reset, flush, shutdown
  • Three-tier consent model: none (inert), anonymous (no PII), full (all events)
  • Auto-tracked session_start on new session, session_end on shutdown()
  • Attribution capture: UTM params, click IDs, referrer, landing page — cached per session
  • Uses core's createConsentManager, collectAttribution, and getOrCreateSession — no duplicated logic with pixel

De-duplication with #2830

  • Deleted local attribution.ts, cookie.ts — now imports from @imtbl/audience-core
  • Deleted custom ConsentController class — now uses core's createConsentManager (shared with pixel)
  • Deleted consent-transport.ts — core's httpSend handles the PUT
  • Collapsed web/ package into sdk/ per review feedback

Test plan

  • cd packages/audience/sdk && pnpm test — 46 tests pass
  • cd packages/audience/sdk && pnpm build — builds clean

🤖 Generated with Claude Code

@nx-cloud
Copy link
Copy Markdown

nx-cloud bot commented Apr 5, 2026

View your CI Pipeline Execution ↗ for commit e98f452

Command Status Duration Result
nx affected -t build,lint,test ✅ Succeeded 16s View ↗
nx run-many -p @imtbl/sdk,@imtbl/checkout-widge... ✅ Succeeded 2s View ↗

☁️ Nx Cloud last updated this comment at 2026-04-08 04:11:02 UTC

@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from d72536d to 2ed1923 Compare April 5, 2026 23:44
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from bfd4618 to 0960d7a Compare April 5, 2026 23:44
@ImmutableJeffrey ImmutableJeffrey changed the title feat(audience): add ImmutableWebSDK class with identity and session lifecycle feat(audience): add ImmutableWebSDK class with attribution and session lifecycle Apr 5, 2026
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from e4fe335 to a404b5e Compare April 6, 2026 11:41
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from c7592b3 to 6cc1921 Compare April 6, 2026 11:41
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from a404b5e to dae297d Compare April 6, 2026 15:05
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from 6cc1921 to a830608 Compare April 6, 2026 15:05
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from dae297d to b90f61a Compare April 6, 2026 15:27
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from a830608 to b5964c5 Compare April 6, 2026 15:27
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from b90f61a to 45ebb0b Compare April 6, 2026 23:04
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch 2 times, most recently from 16ecf2d to 82b1a90 Compare April 6, 2026 23:27
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch 2 times, most recently from ed3509e to 45967cd Compare April 6, 2026 23:38
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from 82b1a90 to 0375ff4 Compare April 6, 2026 23:38
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from 45967cd to f8e493a Compare April 7, 2026 01:10
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from 0375ff4 to 8fb34be Compare April 7, 2026 01:10
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from f8e493a to d7cbd5d Compare April 7, 2026 01:48
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from 8fb34be to 37bcb3d Compare April 7, 2026 01:48
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from d7cbd5d to af5828c Compare April 7, 2026 02:19
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from 37bcb3d to 7cccbb2 Compare April 7, 2026 02:19
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch from af5828c to 7ecb14c Compare April 7, 2026 02:34
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch 2 times, most recently from 0df2286 to ac5ad0d Compare April 7, 2026 03:28
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-2-web-scaffold branch 2 times, most recently from 9791814 to d7e6011 Compare April 7, 2026 03:37
@ImmutableJeffrey ImmutableJeffrey requested a review from a team as a code owner April 7, 2026 23:08
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch 2 times, most recently from 312c6c2 to 5d003f8 Compare April 7, 2026 23:14
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch 4 times, most recently from 4ca8371 to 70cccb1 Compare April 8, 2026 02:10
ImmutableJeffrey and others added 2 commits April 8, 2026 12:31
- Rename package to @imtbl/audience
- DebugLogger: opt-in console logging for events, flushes, consent
  changes, and warnings
- AudienceConfig: publishable key, environment, consent, debug, cookie
  domain, flush interval/size
- Config constants: library name/version, log prefix, consent source,
  session event names

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Audience.init() provides consent-aware event tracking for web:
- track(), page(), identify(), alias() with three-tier consent gating
- Uses core's createConsentManager (shared with pixel), collectAttribution,
  and getOrCreateSession — no duplicated logic
- session_start/session_end lifecycle with duration tracking
- Attribution capture (UTM, click IDs, referrer) on first page view
- setConsent() with queue cleanup on downgrade, session restart on upgrade
- reset() for player logout, flush() for manual send, shutdown() for cleanup

46 tests covering all public methods, consent transitions, and edge cases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@ImmutableJeffrey ImmutableJeffrey force-pushed the feat/audience-3-sdk-class branch from 70cccb1 to fcf6063 Compare April 8, 2026 02:35
@ImmutableJeffrey ImmutableJeffrey changed the title feat(audience): add ImmutableWebSDK class with attribution and session lifecycle feat(audience): add Audience class with consent, tracking, and identity Apr 8, 2026
@JCSanPedro JCSanPedro enabled auto-merge April 8, 2026 03:06
JCSanPedro
JCSanPedro previously approved these changes Apr 8, 2026
ImmutableJeffrey and others added 3 commits April 8, 2026 13:46
Both the SDK and pixel use these event names — they belong in
@imtbl/audience-core so both surfaces import from one place.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add destroyed flag so calling shutdown() twice (e.g. React strict mode
useEffect cleanup) doesn't queue duplicate session_end or decrement
liveInstances below the real count.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ngrade

Move the identify/alias queue purge from the SDK into core's
createConsentManager so both the SDK and pixel correctly remove
PII-linked messages on full→anonymous downgrade.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@JCSanPedro JCSanPedro added this pull request to the merge queue Apr 8, 2026
Merged via the queue into main with commit e502a61 Apr 8, 2026
7 checks passed
@JCSanPedro JCSanPedro deleted the feat/audience-3-sdk-class branch April 8, 2026 04:36
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.

5 participants