feat: add trackEvent for custom pipeline events by talissoncosta · Pull Request #384 · Flagsmith/flagsmith-js-client

talissoncosta · 2026-03-17T18:50:58Z

Summary

Add trackEvent(eventName, metadata?) public method to send custom events through the evaluation analytics pipeline (v1/analytics/batch)
Events are sent immediately with the current identity (or null if anonymous) — no buffering
Pipeline-only: requires evaluationAnalyticsConfig; no-op otherwise
Add PipelineEventType enum (FLAG_EVALUATION, CUSTOM_EVENT) to replace magic strings, exported from index.ts for consumer access
Unify event building into shared buildAnalyticEvent method for both flag evaluations and custom events
Rename sdkMetadata → getEventMetadata, reuse currentTraitsSnapshot across event types
Make pipeline analytics properties private
Uses Record<string, unknown> instead of Record<string, any> for metadata, enforcing type narrowing on consumers

Test plan

Unit tests (8 new): correct event shape, no-op guards (no config, empty name), null identity when anonymous, identity after identify, flush on flushInterval === 0, no deduplication, null identity after logout
All 84 tests pass (no regressions)
Manual E2E validation with Angular playground app + local echo server

Zaimwa9

Thanks for picking this up. 2 main comments:

One related to the identifying behavior of the custom events and the risk of loosing them (or relevant non-identified context)
Some comments to avoid code repetition

Additionally, i'll work now on removing the trimPipelineBuffer as described here as I think it can definitely get improved

flagsmith-core.ts

Zaimwa9 · 2026-03-23T09:36:30Z

flagsmith-core.ts

        }
    }

+    private buildCustomEvent(eventName: string, identityIdentifier: string | null, metadata?: Record<string, unknown>, timestamp?: number): IPipelineEvent {


We should extract the whole logic from here :

and be able to use the buildCustomEvent with both FLAG_EVALUATION and CUSTOM_EVENT

Including using get sdkMetadata for the above. NIT: As it also includes the page_url we could rename it into something like getEventMetadata and also rename buildCustomEvent into buildAnalyticEvent

Same with currentTraitsSnapshot that could replace my previous inline ternary

Makes sense, both build the same IPipelineEvent shape. I'll consolidate into a single shared method that takes event_type as a parameter.

Agreed — getEventMetadata and buildAnalyticEvent are more accurate now that they serve both event types. I'll also reuse currentTraitsSnapshot in the flag evaluation path to replace the inline ternary.

flagsmith-core.ts

Zaimwa9

Thanks for the changes. Ready to approve after rebase + one nit

Zaimwa9 · 2026-03-24T09:25:58Z

types.d.ts

+     * Requires `evaluationAnalyticsConfig` to be set; no-op otherwise.
+     * Events are sent with the current identity (or null if anonymous).
+     * @experimental Internal use only — API may change without notice.
+     * @hidden


just missing the internal tag here too

Thanks @Zaimwa9
Fixed in: 2849346

Add trackEvent(eventName, metadata?) to the public type definitions, allowing custom events to be sent through the evaluation analytics pipeline. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add trackEvent method that sends custom_event through the analytics pipeline batch endpoint. Events tracked before identify() are buffered in pendingCustomEvents and drained once identity is set, preserving original timestamps. Pending events are cleared on logout. Includes helper methods (getPageUrl, currentTraitsSnapshot, sdkMetadata, buildCustomEvent) to keep the implementation clean. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Cover custom event shape, no-op without config, no-op with empty name, queue-before-identify with drain, immediate flush when flushInterval is 0, no deduplication, timestamp preservation, cleanup on logout, and pending buffer maxBuffer cap. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… trackEvent Use the stricter Record<string, unknown> for user-provided metadata, which forces consumers to narrow values before using them. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace string literals 'flag_evaluation' and 'custom_event' with PipelineEventType.FLAG_EVALUATION and PipelineEventType.CUSTOM_EVENT to avoid magic strings and ensure type safety. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Replace 'custom_event' string literals with PipelineEventType.CUSTOM_EVENT in test assertions and helpers - Export PipelineEventType from index.ts for consumer access - Add test for identify → logout → track cycle to verify state resets Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Mark evaluationAnalyticsUrl, evaluationAnalyticsMaxBuffer, pipelineEvents, pipelineAnalyticsInterval, isPipelineFlushing, pipelineRecordedKeys, and pendingCustomEvents as private to prevent external access. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Custom events are now sent immediately with the current identity (or null if anonymous), instead of being buffered until identify() is called. This prevents events from being silently lost when identify() is never called and supports anonymous tracking use cases (e.g. public pages, pre-login). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Extract shared buildAnalyticEvent method that handles both FLAG_EVALUATION and CUSTOM_EVENT types, replacing the separate buildCustomEvent and inline event construction in recordPipelineEvent. Rename sdkMetadata to getEventMetadata (includes page_url, not just SDK info) and reuse currentTraitsSnapshot in the flag evaluation path. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

Zaimwa9 · 2026-03-24T17:10:34Z

@talissoncosta Sorry just missing the latest code from feat/send-evaluation-data-to-analytics-pipeline that removed the trimPipelineBuffer (to remove the callsites in this branch) and integrated into flushPipelineAnalytics

Remove trimPipelineBuffer, aligning with parent branch (36066b2). Add buffer overflow flush condition to trackEvent, matching the approach in recordPipelineEvent. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

talissoncosta · 2026-03-25T11:27:56Z

Thanks for flagging that @Zaimwa9
Fixed it in: ca2ed55

talissoncosta marked this pull request as ready for review March 17, 2026 20:35

talissoncosta requested a review from a team as a code owner March 17, 2026 20:35

talissoncosta requested review from kyle-ssg and removed request for a team March 17, 2026 20:35

talissoncosta linked an issue Mar 19, 2026 that may be closed by this pull request

Track evaluation analytics custom events Flagsmith/flagsmith#6875

Closed

Zaimwa9 self-requested a review March 23, 2026 08:04

Zaimwa9 self-assigned this Mar 23, 2026

Zaimwa9 requested changes Mar 23, 2026

View reviewed changes

talissoncosta requested a review from Zaimwa9 March 23, 2026 14:12

Zaimwa9 reviewed Mar 24, 2026

View reviewed changes

talissoncosta and others added 9 commits March 24, 2026 09:23

feat: add trackEvent to IFlagsmith interface

803634c

Add trackEvent(eventName, metadata?) to the public type definitions, allowing custom events to be sent through the evaluation analytics pipeline. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

refactor: replace Record<string, any> with Record<string, unknown> in…

6041894

… trackEvent Use the stricter Record<string, unknown> for user-provided metadata, which forces consumers to narrow values before using them. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

talissoncosta force-pushed the feat/track-event-custom-pipeline branch from ffa2f7f to 3879f71 Compare March 24, 2026 12:26

fix: add missing @internal tag to trackEvent JSDoc

2849346

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

talissoncosta requested a review from Zaimwa9 March 24, 2026 12:31

talissoncosta force-pushed the feat/track-event-custom-pipeline branch from 2efe60e to ca2ed55 Compare March 24, 2026 17:19

Zaimwa9 approved these changes Mar 25, 2026

View reviewed changes

talissoncosta merged commit 0e819eb into feat/send-evaluation-data-to-analytics-pipeline Mar 25, 2026
3 checks passed

talissoncosta deleted the feat/track-event-custom-pipeline branch March 25, 2026 16:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add trackEvent for custom pipeline events#384

feat: add trackEvent for custom pipeline events#384
talissoncosta merged 11 commits intofeat/send-evaluation-data-to-analytics-pipelinefrom
feat/track-event-custom-pipeline

talissoncosta commented Mar 17, 2026 •

edited

Loading

Uh oh!

Zaimwa9 left a comment

Uh oh!

Uh oh!

Uh oh!

Zaimwa9 Mar 23, 2026

Uh oh!

Zaimwa9 Mar 23, 2026

Uh oh!

talissoncosta Mar 23, 2026 •

edited

Loading

Uh oh!

talissoncosta Mar 23, 2026

Uh oh!

Uh oh!

Zaimwa9 left a comment

Uh oh!

Zaimwa9 Mar 24, 2026

Uh oh!

talissoncosta Mar 24, 2026

Uh oh!

Zaimwa9 commented Mar 24, 2026 •

edited

Loading

Uh oh!

talissoncosta commented Mar 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

talissoncosta commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Zaimwa9 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Zaimwa9 Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Zaimwa9 Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

talissoncosta Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

talissoncosta Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Zaimwa9 left a comment

Choose a reason for hiding this comment

Uh oh!

Zaimwa9 Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

talissoncosta Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Zaimwa9 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

talissoncosta commented Mar 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

talissoncosta commented Mar 17, 2026 •

edited

Loading

talissoncosta Mar 23, 2026 •

edited

Loading

Zaimwa9 commented Mar 24, 2026 •

edited

Loading