|
3 | 3 | [](https://github.com/Eppo-exp/js-client-sdk/actions/workflows/lint-test-sdk.yml) |
4 | 4 | [](https://www.jsdelivr.com/package/npm/@eppo/js-client-sdk) |
5 | 5 |
|
6 | | -[Eppo](https://www.geteppo.com/) is a modular flagging and experimentation analysis tool. Eppo's Javascript SDK is built to make assignments for single user client applications that run in a web browser. Before proceeding you'll need an Eppo account. |
| 6 | +## Getting Started |
7 | 7 |
|
8 | | -## Features |
| 8 | +Refer to our [SDK documentation](https://docs.geteppo.com/sdks/client-sdks/javascript) for how to install and use the SDK. |
9 | 9 |
|
10 | | -- Feature gates |
11 | | -- Kill switches |
12 | | -- Progressive rollouts |
13 | | -- A/B/n experiments |
14 | | -- Mutually exclusive experiments (Layers) |
15 | | -- Global holdouts |
16 | | -- Dynamic configuration |
| 10 | +### Publishing Releases |
17 | 11 |
|
18 | | -## Installation |
| 12 | +When publishing releases, the following rules apply: |
19 | 13 |
|
20 | | -```bash |
21 | | -npm install @eppo/js-client-sdk |
22 | | -``` |
| 14 | +- **Standard Release**: |
| 15 | + - Create a release with tag format `vX.Y.Z` (e.g., `v4.3.5`) |
| 16 | + - Keep "Set as latest release" checked |
| 17 | + - Package will be published to NPM with the `latest` tag |
23 | 18 |
|
24 | | -## Quick start |
| 19 | +- **Pre-release**: |
| 20 | + - Create a release with tag format `vX.Y.Z-label.N` (e.g., `v4.3.5-alpha.1`) |
| 21 | + - Check the "Set as pre-release" option |
| 22 | + - Package will be published to NPM with the pre-release label as its tag (e.g., `alpha.1`) |
25 | 23 |
|
26 | | -Begin by initializing a singleton instance of Eppo's client. Once initialized, the client can be used to make assignments anywhere in your app. |
27 | | - |
28 | | -#### Initialize once |
29 | | - |
30 | | -```javascript |
31 | | -import { init } from "@eppo/js-client-sdk"; |
32 | | - |
33 | | -await init({ apiKey: "<SDK-KEY-FROM-DASHBOARD>" }); |
34 | | -``` |
35 | | - |
36 | | -#### Assign anywhere |
37 | | - |
38 | | -```javascript |
39 | | -import * as EppoSdk from "@eppo/js-client-sdk"; |
40 | | - |
41 | | -const eppoClient = EppoSdk.getInstance(); |
42 | | -const user = getCurrentUser(); |
43 | | - |
44 | | -const variation = eppoClient.getBooleanAssignment('show-new-feature', user.id, { |
45 | | - 'country': user.country, |
46 | | - 'device': user.device, |
47 | | -}, false); |
48 | | -``` |
49 | | - |
50 | | -## Assignment functions |
51 | | - |
52 | | -Every Eppo flag has a return type that is set once on creation in the dashboard. Once a flag is created, assignments in code should be made using the corresponding typed function: |
53 | | - |
54 | | -```javascript |
55 | | -getBooleanAssignment(...) |
56 | | -getNumericAssignment(...) |
57 | | -getIntegerAssignment(...) |
58 | | -getStringAssignment(...) |
59 | | -getJSONAssignment(...) |
60 | | -``` |
61 | | - |
62 | | -Each function has the same signature, but returns the type in the function name. For booleans use `getBooleanAssignment`, which has the following signature: |
63 | | - |
64 | | -```javascript |
65 | | -getBooleanAssignment: ( |
66 | | - flagKey: string, |
67 | | - subjectKey: string, |
68 | | - subjectAttributes: Record<string, any>, |
69 | | - defaultValue: string, |
70 | | -) => boolean |
71 | | - ``` |
72 | | - |
73 | | -## Initialization options |
74 | | - |
75 | | -The `init` function accepts the following optional configuration arguments. |
76 | | - |
77 | | -| Option | Type | Description | Default | |
78 | | -| ------ | ----- | ----- | ----- | |
79 | | -| **`assignmentLogger`** | [IAssignmentLogger](https://github.com/Eppo-exp/js-client-sdk-common/blob/75c2ea1d91101d579138d07d46fca4c6ea4aafaf/src/assignment-logger.ts#L55-L62) | A callback that sends each assignment to your data warehouse. Required only for experiment analysis. See [example](#assignment-logger) below. | `null` | |
80 | | -| **`requestTimeoutMs`** | number | Timeout in milliseconds for HTTPS requests for the experiment configurations. | `5000` | |
81 | | -| **`numInitialRequestRetries`** | number | Number of _additional_ times the initial configurations request will be attempted if it fails. This is the request typically synchronously waited (via `await`) for completion. A small wait will be done between requests. | `1` | |
82 | | -| **`pollAfterSuccessfulInitialization`** | boolean | Poll for new configurations (every 30 seconds) after successfully requesting the initial configurations. | `false` | |
83 | | -| **`pollAfterFailedInitialization`** | boolean | Poll for new configurations even if the initial configurations request failed. | `false` | |
84 | | -| **`throwOnFailedInitialization`** | boolean | Throw an error (reject the promise) if unable to fetch initial configurations during initialization. | `true` | |
85 | | -| **`numPollRequestRetries`** | number | If polling for updated configurations after initialization, the number of additional times a request will be attempted before giving up. Subsequent attempts are done using an exponential backoff. | `7` | |
86 | | - |
87 | | -## Off-line initialization |
88 | | - |
89 | | -The SDK supports off-line initialization if you want to initialize the SDK with a configuration from your server SDK or other external process. In this mode the SDK will not attempt to fetch a configuration from Eppo's CDN, instead only using the provided values. |
90 | | - |
91 | | -This function is synchronous and ready to handle assignments after it returns. |
92 | | - |
93 | | -```javascript |
94 | | -import { offlineInit, Flag, ObfuscatedFlag } from "@eppo/js-client-sdk"; |
95 | | - |
96 | | -// configuration from your server SDK |
97 | | -const configurationJsonString: string = getConfigurationFromServer(); |
98 | | -// The configuration will be not-obfuscated from your server SDK. If you have obfuscated flag values, you can use the `ObfuscatedFlag` type. |
99 | | -const flagsConfiguration: Record<string, Flag | ObfuscatedFlag> = JSON.parse(configurationJsonString); |
100 | | - |
101 | | -offlineInit({ |
102 | | - flagsConfiguration, |
103 | | - // If you have obfuscated flag values, you can use the `ObfuscatedFlag` type. |
104 | | - isObfuscated: true, |
105 | | - }); |
106 | | -``` |
107 | | - |
108 | | -The `offlineInit` function accepts the following optional configuration arguments. |
109 | | - |
110 | | -| Option | Type | Description | Default | |
111 | | -| ------ | ----- | ----- | ----- | |
112 | | -| **`assignmentLogger`** | [IAssignmentLogger](https://github.com/Eppo-exp/js-client-sdk-common/blob/75c2ea1d91101d579138d07d46fca4c6ea4aafaf/src/assignment-logger.ts#L55-L62) | A callback that sends each assignment to your data warehouse. Required only for experiment analysis. See [example](#assignment-logger) below. | `null` | |
113 | | -| **`flagsConfiguration`** | Record<string, Flag \| ObfuscatedFlag> | The flags configuration to use for the SDK. | `null` | |
114 | | -| **`isObfuscated`** | boolean | Whether the flag values are obfuscated. | `false` | |
115 | | -| **`throwOnFailedInitialization`** | boolean | Throw an error if an error occurs during initialization. | `true` | |
116 | | - |
117 | | -## Assignment logger |
118 | | - |
119 | | -To use the Eppo SDK for experiments that require analysis, pass in a callback logging function to the `init` function on SDK initialization. The SDK invokes the callback to capture assignment data whenever a variation is assigned. The assignment data is needed in the warehouse to perform analysis. |
120 | | - |
121 | | -The code below illustrates an example implementation of a logging callback using [Segment](https://segment.com/), but you can use any system you'd like. The only requirement is that the SDK receives a `logAssignment` callback function. Here we define an implementation of the Eppo `IAssignmentLogger` interface containing a single function named `logAssignment`: |
122 | | - |
123 | | -```javascript |
124 | | -import { IAssignmentLogger } from "@eppo/js-client-sdk"; |
125 | | -import { AnalyticsBrowser } from "@segment/analytics-next"; |
126 | | - |
127 | | -// Connect to Segment (or your own event-tracking system) |
128 | | -const analytics = AnalyticsBrowser.load({ writeKey: "<SEGMENT_WRITE_KEY>" }); |
129 | | - |
130 | | -const assignmentLogger: IAssignmentLogger = { |
131 | | - logAssignment(assignment) { |
132 | | - analytics.track({ |
133 | | - userId: assignment.subject, |
134 | | - event: "Eppo Randomized Assignment", |
135 | | - type: "track", |
136 | | - properties: { ...assignment }, |
137 | | - }); |
138 | | - }, |
139 | | -}; |
140 | | -``` |
141 | | - |
142 | | -## Philosophy |
143 | | - |
144 | | -Eppo's SDKs are built for simplicity, speed and reliability. Flag configurations are compressed and distributed over a global CDN (Fastly), typically reaching end users in under 15ms. Those configurations are then cached locally, ensuring that each assignment is made instantly. Each SDK is as light as possible, with evaluation logic at around [25 simple lines of code](https://github.com/Eppo-exp/js-client-sdk-common/blob/b903bbbca21ca75c0ab49d894951eb2f1fc6c85b/src/evaluator.ts#L34-L59). The simple typed functions listed above are all developers need to know about, abstracting away the complexity of the underlying set of features. |
145 | | - |
146 | | -## React |
147 | | - |
148 | | -Visit the [Eppo docs](https://docs.geteppo.com/sdks/client-sdks/javascript#usage-in-react) for best practices when using this SDK within a React context. |
| 24 | +**Note**: The release will not be published if: |
| 25 | +- A pre-release is marked as "latest" |
| 26 | +- A pre-release label is used without checking "Set as pre-release" |
0 commit comments