react-native-nitro-amplitude 0.1.0

package/src/experiment/types/exposure.ts

@@ -0,0 +1,107 @@
+/**
+ * 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_type": "$exposure",
+ *   "event_properties": {
+ *     "flag_key": "<flagKey>",
+ *     "variant": "<variant>",
+ *     "experiment_key": "<expKey>"
+ *   }
+ * }
+ * ```
+ *
+ * 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:
+ *
+ * ```
+ * analytics.track('$exposure', exposure)
+ * ```
+ */
+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;
+  /**
+   * (Optional) Flag, segment, and variant metadata produced as a result of
+   * evaluation for the user. Used for system purposes.
+   */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * 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 initialize experiment using the
+ * {@link Experiment.initializeWithAmplitudeAnalytics} function.
+ *
+ * If you're using a 3rd party analytics implementation then you'll need to
+ * implement the sending of the analytics event yourself. The implementation
+ * should result in the following event getting sent to amplitude:
+ *
+ * ```
+ * {
+ *   "event_type": "$exposure",
+ *   "event_properties": {
+ *     "flag_key": "<flagKey>",
+ *     "variant": "<variant>",
+ *     "experiment_key": "<expKey>"
+ *   }
+ * }
+ * ```
+ *
+ * For example, if you're using Segment for analytics:
+ *
+ * ```
+ * analytics.track('$exposure', exposure)
+ * ```
+ */
+export interface ExposureTrackingProvider {
+  /**
+   * Called when the {@link ExperimentClient} intends to track an exposure event;
+   * either when {@link ExperimentClient.variant} serves a variant (and
+   * {@link ExperimentConfig.automaticExposureTracking} is `true`) or if
+   * {@link ExperimentClient.exposure} is called.
+   *
+   * The implementation should result in the following event getting sent to
+   * amplitude:
+   *
+   * ```
+   * {
+   *   "event_type": "$exposure",
+   *   "event_properties": {
+   *     "flag_key": "<flagKey>",
+   *     "variant": "<variant>",
+   *     "experiment_key": "<expKey>"
+   *   }
+   * }
+   * ```
+   *
+   * For example, if you're using Segment for analytics:
+   *
+   * ```
+   * analytics.track('$exposure', exposure)
+   * ```
+   */
+  track(exposure: Exposure): void;
+}

package/src/experiment/types/logger.ts

@@ -0,0 +1,71 @@
+/**
+ * Log level enumeration for controlling logging verbosity.
+ * @category Logging
+ */
+export enum LogLevel {
+  /**
+   * Disable all logging
+   */
+  Disable = 0,
+  /**
+   * Error level logging - only critical errors
+   */
+  Error = 1,
+  /**
+   * Warning level logging - errors and warnings
+   */
+  Warn = 2,
+  /**
+   * Info level logging - errors, warnings, and informational messages
+   */
+  Info = 3,
+  /**
+   * Debug level logging - errors, warnings, info, and debug messages
+   */
+  Debug = 4,
+  /**
+   * Verbose level logging - all messages including verbose details
+   */
+  Verbose = 5,
+}
+
+/**
+ * Logger interface that can be implemented to provide custom logging.
+ * @category Logging
+ */
+export interface Logger {
+  /**
+   * Log an error message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  error(message?: any, ...optionalParams: any[]): void;
+
+  /**
+   * Log a warning message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  warn(message?: any, ...optionalParams: any[]): void;
+
+  /**
+   * Log an informational message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  info(message?: any, ...optionalParams: any[]): void;
+
+  /**
+   * Log a debug message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  debug(message?: any, ...optionalParams: any[]): void;
+
+  /**
+   * Log a verbose message
+   * @param message The message to log
+   * @param optionalParams Additional parameters to log
+   */
+  verbose(message?: any, ...optionalParams: any[]): void;
+}

package/src/experiment/types/source.ts

@@ -0,0 +1,52 @@
+/**
+ * Determines the primary source of variants before falling back.
+ *
+ * @category Source
+ */
+export enum Source {
+  /**
+   * The default way to source variants within your application. Before the
+   * assignments are fetched, `getVariant(s)` will fallback to local storage
+   * first, then `initialVariants` if local storage is empty. This option
+   * effectively falls back to an assignment fetched previously.
+   */
+  LocalStorage = "localStorage",
+
+  /**
+   * This bootstrap option is used primarily for servers-side rendering using an
+   * Experiment server SDK. This bootstrap option always prefers the config
+   * `initialVariants` over data in local storage, even if variants are fetched
+   * successfully and stored locally.
+   */
+  InitialVariants = "initialVariants",
+}
+
+/**
+ * Indicates from which source the variant() function determines the variant
+ *
+ * @category Source
+ */
+export enum VariantSource {
+  LocalStorage = "storage",
+  InitialVariants = "initial",
+  SecondaryLocalStorage = "secondary-storage",
+  SecondaryInitialVariants = "secondary-initial",
+  FallbackInline = "fallback-inline",
+  FallbackConfig = "fallback-config",
+  LocalEvaluation = "local-evaluation",
+}
+
+/**
+ * Returns true if the VariantSource is one of the fallbacks (inline or config)
+ *
+ * @param source a {@link VariantSource}
+ * @returns true if source is {@link VariantSource.FallbackInline} or {@link VariantSource.FallbackConfig}
+ */
+export const isFallback = (source: VariantSource | undefined): boolean => {
+  return (
+    !source ||
+    source === VariantSource.FallbackInline ||
+    source === VariantSource.FallbackConfig ||
+    source === VariantSource.SecondaryInitialVariants
+  );
+};

package/src/experiment/types/storage.ts

@@ -0,0 +1,6 @@
+export interface Storage {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  reset?(): Promise<void>;
+}

package/src/experiment/types/transport.ts

@@ -0,0 +1,14 @@
+export interface SimpleResponse {
+  status: number;
+  body: string;
+}
+
+export interface HttpClient {
+  request(
+    requestUrl: string,
+    method: string,
+    headers: Record<string, string>,
+    data: string | null,
+    timeoutMillis?: number,
+  ): Promise<SimpleResponse>;
+}

package/src/experiment/types/user.ts

@@ -0,0 +1,132 @@
+/**
+ * Defines a user context for evaluation.
+ * `device_id` and `user_id` are used for identity resolution.
+ * All other predefined fields and user properties are used for
+ * rule based user targeting.
+ * @category Types
+ */
+export type ExperimentUser = {
+  /**
+   * Device ID for associating with an identity in Amplitude
+   */
+  device_id?: string;
+
+  /**
+   * User ID for associating with an identity in Amplitude
+   */
+  user_id?: string;
+
+  /**
+   * Predefined field, can be manually provided
+   */
+  country?: string;
+
+  /**
+   * Predefined field, can be manually provided
+   */
+  city?: string;
+
+  /**
+   * Predefined field, can be manually provided
+   */
+  region?: string;
+
+  /**
+   * Predefined field, can be manually provided
+   */
+  dma?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  language?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  platform?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  version?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  os?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  device_model?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  device_brand?: string;
+
+  /**
+   * Predefined field, auto populated via a ExperimentUserProvider
+   * or can be manually provided
+   */
+  device_manufacturer?: string;
+
+  /**
+   * Predefined field, can be manually provided
+   */
+  carrier?: string;
+
+  /**
+   * Predefined field, auto populated, can be manually overridden
+   */
+  library?: string;
+
+  /**
+   * Predefined field, can be manually provided
+   */
+  ip_address?: string;
+
+  /**
+   * Custom user properties
+   */
+  user_properties?: {
+    [propertyName: string]:
+      | string
+      | number
+      | boolean
+      | (string | number | boolean)[];
+  };
+
+  groups?: {
+    [groupType: string]: string[];
+  };
+
+  group_properties?: {
+    [groupType: string]: {
+      [groupName: string]: {
+        [propertyName: string]:
+          | string
+          | number
+          | boolean
+          | (string | number | boolean)[];
+      };
+    };
+  };
+};
+
+/**
+ * An ExperimentUserProvider injects information into the {@link ExperimentUser}
+ * object before sending a request to the server. This can be used to pass
+ * identity (deviceId and userId), or other platform specific context.
+ * @category Provider
+ */
+export interface ExperimentUserProvider {
+  getUser(): Promise<ExperimentUser>;
+}

package/src/experiment/types/variant.ts

@@ -0,0 +1,36 @@
+/**
+ * @category Types
+ */
+export type Variant = {
+  /**
+   * The key of the variant.
+   */
+  key?: string;
+  /**
+   * The value of the variant.
+   */
+  value?: string;
+
+  /**
+   * The attached payload, if any.
+   */
+  payload?: any;
+
+  /**
+   * The experiment key. Used to distinguish two experiments associated with the same flag.
+   */
+  expKey?: string;
+
+  /**
+   * Flag, segment, and variant metadata produced as a result of
+   * evaluation for the user. Used for system purposes.
+   */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * @category Types
+ */
+export type Variants = {
+  [key: string]: Variant;
+};

package/src/experiment/util/backoff.ts

@@ -0,0 +1,67 @@
+import { safeGlobal } from "@amplitude/experiment-core";
+
+export class Backoff {
+  private readonly attempts: number;
+  private readonly min: number;
+  private readonly max: number;
+  private readonly scalar: number;
+
+  private started = false;
+  private done = false;
+
+  private timeoutHandle: ReturnType<typeof safeGlobal.setTimeout> | undefined;
+
+  public constructor(
+    attempts: number,
+    min: number,
+    max: number,
+    scalar: number,
+  ) {
+    this.attempts = attempts;
+    this.min = min;
+    this.max = max;
+    this.scalar = scalar;
+  }
+
+  public start(fn: () => Promise<void>): void {
+    if (!this.started) {
+      this.started = true;
+    } else {
+      throw Error("Backoff already started");
+    }
+    this.backoff(fn, 0, this.min);
+  }
+
+  public cancel(): void {
+    this.done = true;
+    if (this.timeoutHandle != null) {
+      safeGlobal.clearTimeout(this.timeoutHandle);
+      this.timeoutHandle = undefined;
+    }
+  }
+
+  private backoff(
+    fn: () => Promise<void>,
+    attempt: number,
+    delay: number,
+  ): void {
+    if (this.done) {
+      return;
+    }
+    this.timeoutHandle = safeGlobal.setTimeout(async () => {
+      try {
+        this.timeoutHandle = undefined;
+        await fn();
+        this.done = true;
+      } catch (e) {
+        const nextAttempt = attempt + 1;
+        if (!this.done && nextAttempt < this.attempts) {
+          const nextDelay = Math.min(delay * this.scalar, this.max);
+          this.backoff(fn, nextAttempt, nextDelay);
+        } else {
+          this.done = true;
+        }
+      }
+    }, delay);
+  }
+}

package/src/experiment/util/base64.ts

@@ -0,0 +1,20 @@
+import * as base64 from "base64-js";
+
+export const stringToUtf8Array = (s: string): number[] => {
+  const utf8 = unescape(encodeURIComponent(s));
+  const arr = [];
+  for (let i = 0; i < utf8.length; i++) {
+    arr.push(utf8.charCodeAt(i));
+  }
+  return arr;
+};
+
+export const urlSafeBase64Encode = (s: string): string => {
+  const base64encoded = base64.fromByteArray(
+    new Uint8Array(stringToUtf8Array(s)),
+  );
+  return base64encoded
+    .replace(/[=]/g, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+};

package/src/experiment/util/convert.ts

@@ -0,0 +1,78 @@
+import { EvaluationVariant } from "@amplitude/experiment-core";
+
+import { ExperimentUser } from "../types/user";
+import { Variant } from "../types/variant";
+
+export const convertUserToContext = (
+  user: ExperimentUser | undefined,
+): Record<string, unknown> => {
+  if (!user) {
+    return {};
+  }
+  const contextUser: ExperimentUser = { ...user };
+  const context: Record<string, unknown> = { user: contextUser };
+  const groups: Record<string, Record<string, unknown>> = {};
+  if (!user.groups) {
+    return context;
+  }
+  for (const groupType of Object.keys(user.groups)) {
+    const groupNames: string[] = user.groups[groupType] ?? [];
+    if (groupNames.length > 0 && groupNames[0]) {
+      const groupName = groupNames[0];
+      const groupNameMap: Record<string, unknown> = {
+        group_name: groupName,
+      };
+      // Check for group properties
+      const groupProperties = user.group_properties?.[groupType]?.[groupName];
+      if (groupProperties && Object.keys(groupProperties).length > 0) {
+        groupNameMap["group_properties"] = groupProperties;
+      }
+      groups[groupType] = groupNameMap;
+    }
+  }
+  if (Object.keys(groups).length > 0) {
+    context["groups"] = groups;
+  }
+  delete contextUser.groups;
+  delete contextUser.group_properties;
+  return context;
+};
+
+export const convertVariant = (
+  value: string | Variant | undefined,
+): Variant => {
+  if (value === null || value === undefined) {
+    return {};
+  }
+  if (typeof value === "string") {
+    return {
+      key: value,
+      value: value,
+    };
+  } else {
+    return value;
+  }
+};
+
+export const convertEvaluationVariantToVariant = (
+  evaluationVariant: EvaluationVariant,
+): Variant => {
+  if (!evaluationVariant) {
+    return {};
+  }
+  let experimentKey: string | undefined;
+  if (evaluationVariant.metadata) {
+    const metadataExperimentKey = evaluationVariant.metadata["experimentKey"];
+    if (typeof metadataExperimentKey === "string") {
+      experimentKey = metadataExperimentKey;
+    }
+  }
+  const variant: Variant = {};
+  if (evaluationVariant.key) variant.key = evaluationVariant.key;
+  if (evaluationVariant.value)
+    variant.value = evaluationVariant.value as string;
+  if (evaluationVariant.payload) variant.payload = evaluationVariant.payload;
+  if (experimentKey) variant.expKey = experimentKey;
+  if (evaluationVariant.metadata) variant.metadata = evaluationVariant.metadata;
+  return variant;
+};

package/src/experiment/util/index.ts

@@ -0,0 +1,23 @@
+import { EvaluationFlag } from "@amplitude/experiment-core";
+
+export const isNullOrUndefined = (value: unknown): boolean => {
+  return value === null || value === undefined;
+};
+
+export const isNullUndefinedOrEmpty = (value: unknown): boolean => {
+  if (isNullOrUndefined(value)) return true;
+  if (value === null || typeof value !== "object") return false;
+  return Object.keys(value).length === 0;
+};
+
+export const isLocalEvaluationMode = (
+  flag: EvaluationFlag | undefined,
+): boolean => {
+  return flag?.metadata?.evaluationMode === "local";
+};
+
+export const isRemoteEvaluationMode = (
+  flag: EvaluationFlag | undefined,
+): boolean => {
+  return flag?.metadata?.evaluationMode === "remote";
+};

package/src/experiment/util/platform.ts

@@ -0,0 +1,9 @@
+import { Platform } from "react-native";
+
+export const isWeb = (): boolean => {
+  return Platform.OS === "web";
+};
+
+export const isNative = (): boolean => {
+  return !isWeb();
+};

package/src/experiment/util/randomstring.ts

@@ -0,0 +1,12 @@
+const CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+export const randomString = (
+  length: number,
+  alphabet: string = CHARS,
+): string => {
+  let str = "";
+  for (let i = 0; i < length; ++i) {
+    str += alphabet.charAt(Math.floor(Math.random() * alphabet.length));
+  }
+  return str;
+};

package/src/experiment/util/userSessionExposureTracker.ts

@@ -0,0 +1,47 @@
+import { Exposure, ExposureTrackingProvider } from "../types/exposure";
+import { ExperimentUser } from "../types/user";
+
+interface Identity {
+  userId?: string;
+  deviceId?: string;
+}
+
+/**
+ * A wrapper for an exposure tracking provider which only sends one exposure event per
+ * flag, per variant, per user session. When the user identity (userId or deviceId) changes,
+ * the tracking cache is reset to ensure exposures are tracked for the new user session.
+ */
+export class UserSessionExposureTracker {
+  private readonly exposureTrackingProvider: ExposureTrackingProvider;
+  private tracked: Record<string, string | undefined> = {};
+  private identity: Identity = {};
+
+  constructor(exposureTrackingProvider: ExposureTrackingProvider) {
+    this.exposureTrackingProvider = exposureTrackingProvider;
+  }
+
+  track(exposure: Exposure, user?: ExperimentUser): void {
+    const newIdentity: Identity = {
+      userId: user?.user_id,
+      deviceId: user?.device_id,
+    };
+
+    if (!this.identityEquals(this.identity, newIdentity)) {
+      this.tracked = {};
+    }
+    this.identity = newIdentity;
+
+    const hasTrackedFlag = exposure.flag_key in this.tracked;
+    const trackedVariant = this.tracked[exposure.flag_key];
+    if (hasTrackedFlag && trackedVariant === exposure.variant) {
+      return;
+    }
+
+    this.tracked[exposure.flag_key] = exposure.variant;
+    this.exposureTrackingProvider.track(exposure);
+  }
+
+  private identityEquals(id1: Identity, id2: Identity): boolean {
+    return id1.userId === id2.userId && id1.deviceId === id2.deviceId;
+  }
+}