feat: support expeirment key on variant and exposure event (#72)

Author: bgiori

packages/experiment-browser/src/experimentClient.ts

@@ -400,6 +400,7 @@ export class ExperimentClient implements Client {
       variants[key] = {
         value: json[key].key,
         payload: json[key].payload,
+        expKey: json[key].expKey,
       };
     }
     this.debug('[Experiment] Received variants: ', variants);
@@ -518,6 +519,7 @@ export class ExperimentClient implements Client {
       this.exposureTrackingProvider?.track({
         flag_key: key,
         variant: variant.value,
+        experiment_key: variant.expKey,
       });
       this.analyticsProvider?.setUserProperty?.(event);
       this.analyticsProvider?.track(event);

packages/experiment-browser/src/types/exposure.ts

@@ -1,21 +1,23 @@
 /**
- * Improved exposure event for tracking exposures to Amplitude Experiment.
+ * Event object for tracking exposures to Amplitude Experiment.
  *
  * This object contains all the required information to send an `$exposure`
- * event through any SDK or CDP to experiment. The resulting exposure event
- * must follow the following definition:
+ * event through any SDK or CDP to experiment.
+ *
+ * The resulting exposure event must follow the following definition:
  * ```
  * {
  *   "event_type": "$exposure",
  *   "event_properties": {
  *     "flag_key": "<flagKey>",
- *     "variant": "<variant>"
+ *     "variant": "<variant>",
+ *     "experiment_key": "<expKey>"
  *   }
  * }
  * ```
  *
- * Where `<flagKey>` and `<variant>` are the {@link flag_key} and
- * {@link variant} variant` members on this type.
+ * Where `<flagKey>`, `<variant>`, and `<expKey>` are the {@link flag_key},
+ * {@link variant}, and {@link experiment_key} variant members on this type:
  *
  * For example, if you're using Segment for analytics:
  *
@@ -24,17 +26,28 @@
  * ```
  */
 export type Exposure = {
+  /**
+   * (Required) The key for the flag the user was exposed to.
+   */
   flag_key: string;
+  /**
+   * (Optional) The variant the user was exposed to. If null or missing, the
+   * event will not be persisted, and will unset the user property.
+   */
   variant?: string;
+  /**
+   * (Optional) The experiment key used to differentiate between multiple
+   * experiments associated with the same flag.
+   */
+  experiment_key?: string;
 };
 
 /**
  * Interface for enabling tracking {@link Exposure}s through the
  * {@link ExperimentClient}.
  *
  * If you're using the Amplitude Analytics SDK for tracking you do not need
- * to implement this interface. Simply upgrade your analytics SDK version to
- * 2.36.0+ and initialize experiment using the
+ * to implement this interface. Simply initialize experiment using the
  * {@link Experiment.initializeWithAmplitudeAnalytics} function.
  *
  * If you're using a 3rd party analytics implementation then you'll need to
@@ -46,7 +59,8 @@ export type Exposure = {
  *   "event_type": "$exposure",
  *   "event_properties": {
  *     "flag_key": "<flagKey>",
- *     "variant": "<variant>"
+ *     "variant": "<variant>",
+ *     "experiment_key": "<expKey>"
  *   }
  * }
  * ```
@@ -72,7 +86,8 @@ export interface ExposureTrackingProvider {
    *   "event_type": "$exposure",
    *   "event_properties": {
    *     "flag_key": "<flagKey>",
-   *     "variant": "<variant>"
+   *     "variant": "<variant>",
+   *     "experiment_key": "<expKey>"
    *   }
    * }
    * ```

packages/experiment-browser/src/types/variant.ts

@@ -12,6 +12,11 @@ export type Variant = {
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   payload?: any;
+
+  /**
+   * The experiment key. Used to distinguish two experiments associated with the same flag.
+   */
+  expKey?: string;
 };
 
 /**

packages/experiment-browser/test/client.test.ts

@@ -5,7 +5,7 @@ import { HttpClient, SimpleResponse } from 'src/types/transport';
 import { ExperimentClient } from '../src/experimentClient';
 import { ExperimentAnalyticsProvider } from '../src/types/analytics';
 import { FetchOptions } from '../src/types/client';
-import { ExposureTrackingProvider } from '../src/types/exposure';
+import { Exposure, ExposureTrackingProvider } from '../src/types/exposure';
 import { ExperimentUserProvider } from '../src/types/provider';
 import { Source } from '../src/types/source';
 import { ExperimentUser } from '../src/types/user';
@@ -429,3 +429,19 @@ test('ExperimentClient.fetch with not exist flagKeys in fetch options', async ()
   const variant = client.all();
   expect(variant).toEqual({});
 });
+
+test('ExperimentClient.variant experiment key passed from variant to exposure', async () => {
+  let didTrack = false;
+  const client = new ExperimentClient(LOCAL_TEST_API, {
+    exposureTrackingProvider: {
+      track: (exposure: Exposure) => {
+        expect(exposure.experiment_key).toEqual('expKey');
+        didTrack = true;
+      },
+    },
+    source: Source.InitialVariants,
+    initialVariants: { flagKey: { value: 'value', expKey: 'expKey' } },
+  });
+  client.variant('flagKey');
+  expect(didTrack).toEqual(true);
+});