feat: unset user properties when variant evaluates to none

Author: curtisliu

packages/browser-demo/src/experiment.js

@@ -21,6 +21,10 @@ const config = {
       payload: {},
     }
   },
+  analyticsProvider: {
+    track: (event) => { console.log('Tracked: ' + JSON.stringify(event))},
+    unset: (event) => { console.log('Unset: ' + JSON.stringify(event))}
+  }
 }
 
 const experiment = Experiment.initialize(

packages/browser/src/experimentClient.ts

@@ -8,13 +8,14 @@ import { version as PACKAGE_VERSION } from '../package.json';
 import { ExperimentConfig, Defaults, Source } from './config';
 import { LocalStorage } from './storage/localStorage';
 import { FetchHttpClient } from './transport/http';
-import { ExposureEvent } from './types/analytics';
+import { exposureEvent, isFallback, VariantSource } from './types/analytics';
 import { Client } from './types/client';
 import { ExperimentUserProvider } from './types/provider';
 import { Storage } from './types/storage';
 import { HttpClient } from './types/transport';
 import { ExperimentUser } from './types/user';
 import { Variant, Variants } from './types/variant';
+import { isNullOrUndefined } from './util';
 import { Backoff } from './util/backoff';
 import { urlSafeBase64Encode } from './util/base64';
 import { randomString } from './util/randomstring';
@@ -114,37 +115,122 @@ export class ExperimentClient implements Client {
    * Access the variant from {@link Source}, falling back  on the given
    * fallback, then the configured fallbackVariant.
    *
-   * If an {@link ExperimentAnalyticsProvider} is configured, this function will
-   * call the provider with an {@link ExposureEvent}. The exposure event does
-   * not count towards your event volume within Amplitude.
+   * If an {@link ExperimentAnalyticsProvider} is configured and trackExposure is
+   * true, this function will call the provider with an {@link ExposureEvent}.
+   * The exposure event does not count towards your event volume within Amplitude.
    *
    * @param key The key to get the variant for.
    * @param fallback The highest priority fallback.
+   * @param trackExposure Sends a track event via the configured {@link ExperimentAnalyticsProvider}
    * @see ExperimentConfig
    * @see ExperimentAnalyticsProvider
    */
-  public variant(key: string, fallback?: string | Variant): Variant {
+  public variant(
+    key: string,
+    fallback?: string | Variant,
+    trackExposure = true,
+  ): Variant {
     if (!this.apiKey) {
       return { value: undefined };
     }
-    const sourceVariant = this.sourceVariants()[key];
-    if (sourceVariant?.value) {
-      this.config.analyticsProvider?.track(
-        new ExposureEvent(
-          this.addContext(this.getUser()),
-          key,
-          this.convertVariant(sourceVariant),
-        ),
-      );
+    const { source, variant } = this.variantAndSource(key, fallback);
+
+    if (trackExposure) {
+      if (isFallback(source) || !variant?.value) {
+        // fallbacks indicate not being allocated into an experiment, so
+        // we can unset the property
+        this.config.analyticsProvider?.unset(
+          exposureEvent(this.addContext(this.getUser()), key, variant, source),
+        );
+      } else {
+        if (variant?.value) {
+          // only track when there's a value for a non fallback variant
+          this.config.analyticsProvider?.track(
+            exposureEvent(
+              this.addContext(this.getUser()),
+              key,
+              variant,
+              source,
+            ),
+          );
+        }
+      }
+    }
+
+    this.debug(`[Experiment] variant for ${key} is ${variant.value}`);
+    return variant;
+  }
+
+  private variantAndSource(
+    key: string,
+    fallback: string | Variant,
+  ): {
+    variant: Variant;
+    source: VariantSource;
+  } {
+    if (this.config.source === Source.InitialVariants) {
+      // for source = InitialVariants, fallback order goes:
+      // 1. InitialFlags
+      // 2. Local Storage
+      // 3. Function fallback
+      // 4. Config fallback
+
+      const sourceVariant = this.sourceVariants()[key];
+      if (!isNullOrUndefined(sourceVariant)) {
+        return {
+          variant: this.convertVariant(sourceVariant),
+          source: VariantSource.INITIAL_VARIANTS,
+        };
+      }
+      const secondaryVariant = this.secondaryVariants()[key];
+      if (!isNullOrUndefined(secondaryVariant)) {
+        return {
+          variant: this.convertVariant(secondaryVariant),
+          source: VariantSource.SECONDARY_LOCAL_STORAGE,
+        };
+      }
+      if (!isNullOrUndefined(fallback)) {
+        return {
+          variant: this.convertVariant(fallback),
+          source: VariantSource.FALLBACK_INLINE,
+        };
+      }
+      return {
+        variant: this.convertVariant(this.config.fallbackVariant),
+        source: VariantSource.FALLBACK_CONFIG,
+      };
+    } else {
+      // for source = LocalStorage, fallback order goes:
+      // 1. Local Storage
+      // 2. Function fallback
+      // 3. InitialFlags
+      // 4. Config fallback
+
+      const sourceVariant = this.sourceVariants()[key];
+      if (!isNullOrUndefined(sourceVariant)) {
+        return {
+          variant: this.convertVariant(sourceVariant),
+          source: VariantSource.LOCAL_STORAGE,
+        };
+      }
+      if (!isNullOrUndefined(fallback)) {
+        return {
+          variant: this.convertVariant(fallback),
+          source: VariantSource.FALLBACK_INLINE,
+        };
+      }
+      const secondaryVariant = this.secondaryVariants()[key];
+      if (!isNullOrUndefined(secondaryVariant)) {
+        return {
+          variant: this.convertVariant(secondaryVariant),
+          source: VariantSource.SECONDARY_INITIAL_VARIANTS,
+        };
+      }
+      return {
+        variant: this.convertVariant(this.config.fallbackVariant),
+        source: VariantSource.FALLBACK_CONFIG,
+      };
     }
-    const variant =
-      sourceVariant ??
-      fallback ??
-      this.secondaryVariants()[key] ??
-      this.config.fallbackVariant;
-    const converted = this.convertVariant(variant);
-    this.debug(`[Experiment] variant for ${key} is ${converted.value}`);
-    return converted;
   }
 
   /**

packages/browser/src/integration/amplitude.ts

@@ -4,12 +4,24 @@ import {
   ExperimentAnalyticsProvider,
 } from '../types/provider';
 import { ExperimentUser } from '../types/user';
+import { safeGlobal } from '../util/global';
+
+declare global {
+  // eslint-disable-next-line no-var, @typescript-eslint/no-explicit-any
+  var amplitude: any;
+}
+
+type AmplitudeIdentify = {
+  set(property: string, value: unknown): void;
+  unset(property: string): void;
+};
 
 type AmplitudeInstance = {
   options?: AmplitudeOptions;
   _ua?: AmplitudeUAParser;
   logEvent(eventName: string, properties: Record<string, string>): void;
   setUserProperties(userProperties: Record<string, unknown>): void;
+  identify(identify: AmplitudeIdentify): void;
 };
 
 type AmplitudeOptions = {
@@ -78,9 +90,17 @@ export class AmplitudeAnalyticsProvider implements ExperimentAnalyticsProvider {
   }
 
   track(event: ExperimentAnalyticsEvent): void {
-    if (event.userProperties) {
-      this.amplitudeInstance.setUserProperties(event.userProperties);
-    }
+    // if the variant has a value, set the user property and log an event
+    this.amplitudeInstance.setUserProperties({
+      [event.userProperty]: event.variant?.value,
+    });
     this.amplitudeInstance.logEvent(event.name, event.properties);
   }
+
+  unset(event: ExperimentAnalyticsEvent): void {
+    // if the variant does not have a value, unset the user property
+    this.amplitudeInstance.identify(
+      new safeGlobal.amplitude.Identify().unset(event.userProperty),
+    );
+  }
 }

packages/browser/src/types/analytics.ts

@@ -26,41 +26,70 @@ export interface ExperimentAnalyticsEvent {
    * User properties to identify with the user prior to sending the event.
    */
   userProperties?: Record<string, unknown>;
-}
-
-/**
- * Event for tracking a user's exposure to a variant. This event will not count
- * towards your analytics event volume.
- */
-export class ExposureEvent implements ExperimentAnalyticsEvent {
-  name = '[Experiment] Exposure';
-  properties: Record<string, string>;
-  userProperties?: Record<string, unknown>;
 
   /**
    * The user exposed to the flag/experiment variant.
    */
-  public user: ExperimentUser;
+  user: ExperimentUser;
 
   /**
    * The key of the flag/experiment that the user has been exposed to.
    */
-  public key: string;
+  key: string;
 
   /**
    * The variant of the flag/experiment that the user has been exposed to.
    */
-  public variant: Variant;
+  variant: Variant;
+
+  /**
+   * The user property for the flag/experiment (auto-generated from the key)
+   */
+  userProperty: string;
+}
 
-  public constructor(user: ExperimentUser, key: string, variant: Variant) {
-    this.key = key;
-    this.variant = variant;
-    this.properties = {
-      key: key,
-      variant: variant.value,
-    };
-    this.userProperties = {
-      [`[Experiment] ${key}`]: variant.value,
-    };
-  }
+/**
+ * Event for tracking a user's exposure to a variant. This event will not count
+ * towards your analytics event volume.
+ */
+export const exposureEvent = (
+  user: ExperimentUser,
+  key: string,
+  variant: Variant,
+  source: VariantSource,
+): ExperimentAnalyticsEvent => {
+  const name = '[Experiment] Exposure';
+  const value = variant?.value;
+  const userProperty = `[Experiment] ${key}`;
+  return {
+    name,
+    user,
+    key,
+    variant,
+    userProperty,
+    properties: {
+      key,
+      variant: value,
+      source,
+    },
+    userProperties: {
+      [userProperty]: value,
+    },
+  };
+};
+
+export enum VariantSource {
+  LOCAL_STORAGE = 'storage',
+  INITIAL_VARIANTS = 'initial',
+  SECONDARY_LOCAL_STORAGE = 'secondary-storage',
+  SECONDARY_INITIAL_VARIANTS = 'secondary-initial',
+  FALLBACK_INLINE = 'fallback-inline',
+  FALLBACK_CONFIG = 'fallback-config',
 }
+
+export const isFallback = (source: VariantSource): boolean => {
+  return (
+    source === VariantSource.FALLBACK_INLINE ||
+    source === VariantSource.FALLBACK_CONFIG
+  );
+};

packages/browser/src/types/client.ts

@@ -8,7 +8,11 @@ import { Variant, Variants } from './variant';
  */
 export interface Client {
   fetch(user?: ExperimentUser): Promise<Client>;
-  variant(key: string, fallback?: string | Variant): Variant;
+  variant(
+    key: string,
+    fallback?: string | Variant,
+    trackExposure?: boolean,
+  ): Variant;
   all(): Variants;
   getUser(): ExperimentUser;
   setUser(user: ExperimentUser): void;

packages/browser/src/types/provider.ts

@@ -18,4 +18,5 @@ export interface ExperimentUserProvider {
  */
 export interface ExperimentAnalyticsProvider {
   track(event: ExperimentAnalyticsEvent): void;
+  unset(event: ExperimentAnalyticsEvent): void;
 }

packages/browser/src/util/index.ts

@@ -0,0 +1,3 @@
+export const isNullOrUndefined = (value: unknown): boolean => {
+  return value === null || value === undefined;
+};