feat: add user properties to analytics events like exposure (#11)

Author: bgiori

packages/browser/src/integration/amplitude.ts

@@ -9,6 +9,7 @@ type AmplitudeInstance = {
   options?: AmplitudeOptions;
   _ua?: AmplitudeUAParser;
   logEvent(eventName: string, properties: Record<string, string>): void;
+  setUserProperties(userProperties: Record<string, unknown>): void;
 };
 
 type AmplitudeOptions = {
@@ -77,6 +78,9 @@ export class AmplitudeAnalyticsProvider implements ExperimentAnalyticsProvider {
   }
 
   track(event: ExperimentAnalyticsEvent): void {
+    if (event.userProperties) {
+      this.amplitudeInstance.setUserProperties(event.userProperties);
+    }
     this.amplitudeInstance.logEvent(event.name, event.properties);
   }
 }

packages/browser/src/types/analytics.ts

@@ -16,11 +16,18 @@ export interface ExperimentAnalyticsEvent {
   name: string;
 
   /**
-   * Properties for the analytics event. Should be passed as the event
+   * Event properties for the analytics event. Should be passed as the event
    * properties to the analytics implementation provided by the
    * {@link ExperimentAnalyticsProvider}.
    */
   properties: Record<string, string>;
+
+  /**
+   * Custom user properties from the {@link ExperimentUser} stored by the
+   * {@link ExperimentClient}. Also includes merged properties provided by the
+   * {@link ExperimentUserProvider}.
+   */
+  userProperties?: Record<string, unknown>;
 }
 
 /**
@@ -30,6 +37,7 @@ export interface ExperimentAnalyticsEvent {
 export class ExposureEvent implements ExperimentAnalyticsEvent {
   name = '[Experiment] Exposure';
   properties: Record<string, string>;
+  userProperties?: Record<string, unknown>;
 
   /**
    * The user exposed to the flag/experiment variant.
@@ -53,5 +61,8 @@ export class ExposureEvent implements ExperimentAnalyticsEvent {
       key: key,
       variant: variant.value,
     };
+    this.userProperties = {
+      [`[Experiment] ${key}`]: variant.value,
+    };
   }
 }

packages/browser/test/client.test.ts

@@ -220,8 +220,8 @@ test('ExperimentClient.fetch, with config user provider, success', async () => {
  */
 class TestAnalyticsProvider implements ExperimentAnalyticsProvider {
   public didTrack = false;
-  public block: (ExposureEvent) => void;
-  public constructor(block: (ExposureEvent) => void) {
+  public block: (event: ExperimentAnalyticsEvent) => void;
+  public constructor(block: (event: ExperimentAnalyticsEvent) => void) {
     this.block = block;
   }
   track(event: ExperimentAnalyticsEvent): void {
@@ -273,3 +273,25 @@ test('ExperimentClient.variant, with analytics provider, exposure not tracked on
   client.variant(initialKey);
   client.variant(unknownKey);
 });
+
+/**
+ * Configure a client with an analytics provider which checks that
+ * user_properties from the ExperimentUser object are passed through the event
+ * to the analytics provider.
+ */
+test('ExperimentClient.variant, with analytics provider, user properties tracked', async () => {
+  const analyticsProvider = new TestAnalyticsProvider(
+    (event: ExperimentAnalyticsEvent) => {
+      expect(event.userProperties).toEqual({
+        [`[Experiment] ${serverKey}`]: serverVariant.value,
+      });
+    },
+  );
+  const client = new ExperimentClient(API_KEY, {
+    debug: true,
+    analyticsProvider: analyticsProvider,
+  });
+  await client.fetch(testUser);
+  client.variant(serverKey);
+  expect(analyticsProvider.didTrack).toEqual(true);
+});