feat: client-side local evaluation and core evaluation package (#81)

Author: bgiori

examples/react-app/amplitude-integration/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "dependencies": {
-    "@amplitude/analytics-browser": "^1.5.4",
+    "@amplitude/analytics-browser": "^1.12.1",
     "@amplitude/experiment-js-client": "^1.5.6",
     "@types/node": "^16.11.29",
     "@types/react": "^18.0.7",

package.json

@@ -31,7 +31,7 @@
     "eslint-plugin-jest": "^27.2.1",
     "eslint-plugin-prettier": "^3.1.4",
     "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
+    "jest-environment-jsdom": "^29.6.4",
     "lerna": "^6.6.1",
     "node-fetch": "^2.6.0",
     "prettier": "^2.0.5",

packages/experiment-browser/package.json

@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@amplitude/analytics-connector": "^1.5.0",
+    "@amplitude/experiment-core": "^0.6.0",
     "@amplitude/ua-parser-js": "^0.7.31",
     "base64-js": "1.5.1",
     "unfetch": "4.1.0"

packages/experiment-browser/rollup.config.js

@@ -71,7 +71,11 @@ const configs = [
       entryFileNames: 'experiment.esm.js',
       format: 'esm',
     }),
-    external: ['@amplitude/ua-parser-js', '@amplitude/analytics-connector'],
+    external: [
+      '@amplitude/ua-parser-js',
+      '@amplitude/analytics-connector',
+      '@amplitude/experiment-core',
+    ],
   },
 
   // modern build for field "es2015" - not ie, esm, es2015 syntax
@@ -81,7 +85,11 @@ const configs = [
       entryFileNames: 'experiment.es2015.js',
       format: 'esm',
     }),
-    external: ['@amplitude/ua-parser-js', '@amplitude/analytics-connector'],
+    external: [
+      '@amplitude/ua-parser-js',
+      '@amplitude/analytics-connector',
+      '@amplitude/experiment-core',
+    ],
   },
 ];
 

packages/experiment-browser/src/config.ts

@@ -43,10 +43,22 @@ export interface ExperimentConfig {
   source?: Source;
 
   /**
-   * The server endpoint from which to request variants.
+   * The domain from which to request variants using remote evaluation.
    */
   serverUrl?: string;
 
+  /**
+   * The domain to request flag configurations used in local evaluation from.
+   */
+  flagsServerUrl?: string;
+
+  /**
+   * The amplitude data center to fetch flags and variants from. If set,
+   * automatically sets the {@link serverUrl} and {@link flagsServerUrl}
+   * configurations.
+   */
+  serverZone?: string;
+
   /**
    * The request timeout, in milliseconds, when fetching variants.
    */
@@ -65,6 +77,21 @@ export interface ExperimentConfig {
    */
   automaticExposureTracking?: boolean;
 
+  /**
+   * Enable or disable local evaluation flag configuration polling on `start()`.
+   */
+  pollOnStart?: boolean;
+
+  /**
+   * Explicitly enable or disable calling {@link fetch()} on {@link start()}:
+   *
+   *  - `true`:      fetch will always be called on start.
+   *  - `false`:     fetch will never be called on start.
+   *  - `undefined`: the SDK will determine whether to call fetch based on the
+   *                 flags returned in the result.
+   */
+  fetchOnStart?: boolean;
+
   /**
    * This config only matters if you are using the amplitude analytics SDK
    * integration initialized by calling
@@ -120,9 +147,13 @@ export interface ExperimentConfig {
  | **initialVariants**         | `null`                 |
  | **source** | `Source.LocalStorage` |
  | **serverUrl**    | `"https://api.lab.amplitude.com"` |
+ | **flagsServerUrl**    | `"https://flag.lab.amplitude.com"` |
+ | **serverZone**    | `"US"` |
  | **assignmentTimeoutMillis**    | `10000` |
  | **retryFailedAssignment**    | `true` |
  | **automaticExposureTracking** | `true` |
+ | **pollOnStart** | `true` |
+ | **fetchOnStart** | `undefined` |
  | **automaticFetchOnAmplitudeIdentityChange** | `false` |
  | **userProvider**    | `null` |
  | **analyticsProvider**    | `null` |
@@ -138,9 +169,13 @@ export const Defaults: ExperimentConfig = {
   initialVariants: {},
   source: Source.LocalStorage,
   serverUrl: 'https://api.lab.amplitude.com',
+  flagsServerUrl: 'https://flag.lab.amplitude.com',
+  serverZone: 'US',
   fetchTimeoutMillis: 10000,
   retryFetchOnFailure: true,
   automaticExposureTracking: true,
+  pollOnStart: true,
+  fetchOnStart: undefined,
   automaticFetchOnAmplitudeIdentityChange: false,
   userProvider: null,
   analyticsProvider: null,