You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Begin by initializing a singleton instance of Eppo's client with an SDK key from the [Eppo dashboard](https://eppo.cloud/feature-flags/keys). Once initialized, the client can be used to make assignments anywhere in your app.
35
39
36
-
Initialize the SDK with a SDK key, which can be generated in the Eppo interface:
40
+
#### Initialize once
37
41
38
42
```javascript
39
43
import { init } from"@eppo/react-native-sdk";
40
44
41
-
awaitinit({
42
-
apiKey:"<SDK_KEY>",
43
-
assignmentLogger,
44
-
});
45
+
awaitinit({ apiKey:"<SDK-KEY>" });
45
46
```
46
47
47
-
During initialization, the SDK sends an API request to Eppo to retrieve the most recent experiment configurations such as variation values and traffic allocation. The SDK stores these configurations in memory so that assignments are effectively instant. For more information, see the [architecture overview](/sdks/architecture) page.
48
48
49
-
If you are using the SDK for experiment assignments, make sure to pass in an assignment logging callback (see [section](#define-an-assignment-logger-experiment-assignment-only) below).
49
+
#### Assign anywhere
50
50
51
+
```javascript
52
+
import*asEppoSdkfrom"@eppo/react-native-sdk";
51
53
52
-
### Define an assignment logger (experiment assignment only)
54
+
consteppoClient=EppoSdk.getInstance();
55
+
constuser=getCurrentUser();
53
56
54
-
If you are using the Eppo SDK for experiment assignment (i.e randomization), 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 code below illustrates an example implementation of a logging callback using Segment. You could also use your own logging system, the only requirement is that the SDK receives a `logAssignment` function. Here we define an implementation of the Eppo `AssignmentLogger` interface containing a single function named `logAssignment`:
63
+
After initialization, the SDK begins polling Eppo’s API at regular intervals to retrieve the most recent experiment configurations (variation values, traffic allocation, etc.). You can customize initialization and polling preferences by passing in additional [initialization options](#initialization-options).
The SDK stores these configurations in memory so that assignments thereafter are effectively instant. For more information, see the [architecture overview](/sdks/architecture) page.
66
+
67
+
### Connecting an event logger
68
+
69
+
Eppo is architected so that raw user data never leaves your system. As part of that, instead of pushing subject-level exposure events to Eppo's servers, Eppo's SDKs integrate with your existing logging system. This is done with a logging callback function defined at SDK initialization.
62
70
63
-
// Connect to Segment (or your own event-tracking system, it can be any system you like)
64
-
constsegmentClient=createClient({
65
-
writeKey:'SEGMENT_API_KEY'
71
+
```javascript
72
+
awaitinit({
73
+
apiKey:"<SDK_KEY>",
74
+
assignmentLogger,
66
75
});
76
+
```
77
+
78
+
This logger takes an [analytic event](#assignment-logger-schema) created by Eppo, `assignment`, and writes in to a table in the data warehouse (Snowflake, Databricks, BigQuery, or Redshift). You can read more on the [Event Logging](/sdks/event-logging) page.
79
+
80
+
The code below illustrates an example implementation of a logging callback using Segment. You could also use your own logging system, the only requirement is that the SDK receives a `logAssignment` function. Here we define an implementation of the Eppo ``IAssignmentLogger` interface containing a single function named `logAssignment`:
|`experiment` (string) | An Eppo experiment key | "recommendation-algo-allocation-17" |
89
-
|`subject` (string) | An identifier of the subject or user assigned to the experiment variation | UUID |
90
-
|`variation` (string) | The experiment variation the subject was assigned to | "control" |
91
-
|`timestamp` (string) | The time when the subject was assigned to the variation | 2021-06-22T17:35:12.000Z |
92
-
|`subjectAttributes` (map) | A free-form map of metadata about the subject. These attributes are only logged if passed to the SDK assignment function |`{ "country": "US" }`|
93
-
|`featureFlag` (string) | An Eppo feature flag key | "recommendation-algo" |
94
-
|`allocation` (string) | An Eppo allocation key | "allocation-17" |
95
-
96
-
:::note
97
-
More details about logging and examples (with Segment, Rudderstack, mParticle, and Snowplow) can be found in the [event logging](/sdks/event-logging/) page.
98
-
:::
99
-
100
-
#### Avoiding duplicated assignment logs
101
+
#### Deduplicating assignment logs
101
102
102
103
Eppo's SDK uses an internal cache to ensure that duplicate assignment events are not logged to the data warehouse. While Eppo's analytic engine will automatically deduplicate assignment records, this internal cache prevents firing unnecessary events and can help minimize costs associated with event logging.
103
104
104
-
## 3. Assign variations
105
+
### Getting variations
106
+
107
+
Now that the SDK is initialized and connected to your event logger, you can check what variant a specific subject (typically user) should see by calling the `get<Type>Assignment` functions.
105
108
106
-
Assign users to flags or experiments using `get<Type>Assignment`, depending on the type of the flag.
107
-
For example, for a String-valued flag, use `getStringAssignment`:
109
+
For example, for a string-valued flag, use `getStringAssignment`:
108
110
109
111
```javascript
110
112
import*asEppoSdkfrom"@eppo/react-native-sdk";
111
113
112
114
consteppoClient=EppoSdk.getInstance();
115
+
116
+
// replace this with your own user object
117
+
constuser=getCurrentUser();
118
+
113
119
constvariation=eppoClient.getStringAssignment(
114
-
"<FLAG-KEY>",
115
-
"<SUBJECT-KEY>",
116
-
<SUBJECT-ATTRIBUTES>, //Metadata used for targeting
The `getStringAssignment` function takes three required and one optional input to assign a variation:
127
+
Note that Eppo uses a unified API for feature gates, experiments, and mutually exclusive layers. This makes it easy to turn a flag into an experiment or vice versa without having to do a code release.
122
128
123
-
-`flagKey` - This key is available on the detail page for both flags and experiments. Can also be an experiment key.
124
-
-`subjectKey` - The entity ID that is being experimented on, typically represented by a uuid.
125
-
-`subjectAttributes` - A map of metadata about the subject used for targeting. If you create rules based on attributes on a flag/experiment, those attributes should be passed in on every assignment call. If no attributes are needed, pass in an empty object.
129
+
The `getStringAssignment` function takes four inputs to assign a variation:
130
+
131
+
-`flagKey` - The key for the flag you are evaluating. This key is available on the feature flag detail page (see below).
132
+
-`subjectKey` - A unique identifier for the subject being experimented on (e.g., user), typically represented by a UUID. This key is used to deterministically assign subjects to variants.
133
+
-`subjectAttributes` - A map of metadata about the subject used for [targeting](/feature-flagging/concepts/targeting/). If targeting is not needed, pass in an empty object.
126
134
-`defaultValue` - The value that will be returned if no allocation matches the subject, if the flag is not enabled, if `getStringAssignment` is invoked before the SDK has finished initializing, or if the SDK was not able to retrieve the flag configuration. Its type must match the `get<Type>Assignment` call.
127
135
136
+

128
137
129
138
### Typed assignments
130
139
131
-
The following typed functions are available:
140
+
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:
132
141
133
142
```javascript
134
143
getBooleanAssignment(...)
@@ -138,9 +147,36 @@ getStringAssignment(...)
138
147
getJSONAssignment(...)
139
148
```
140
149
141
-
:::note
142
-
It may take up to 10 seconds for changes to Eppo experiments to be reflected by the SDK assignments.
143
-
:::
150
+
Each function has the same signature, but returns the type in the function name. The only exception is `defaultValue`, which should be the same type as the flag. For boolean flags for instance, you should use `getBooleanAssignment`, which has the following signature:
151
+
152
+
```javascript
153
+
getBooleanAssignment: (
154
+
flagKey: string,
155
+
subjectKey: string,
156
+
subjectAttributes: Record<string, any>,
157
+
defaultValue: boolean,
158
+
) => boolean
159
+
```
160
+
161
+
To read more about different flag types, see the [Flag Variations](/feature-flagging/concepts/flag-variations) page.
162
+
163
+
164
+
## Advanced Options
165
+
166
+
### Initialization options
167
+
168
+
The `init` function accepts the following optional configuration arguments.
169
+
170
+
| Option | Type | Description | Default |
171
+
| ------ | ----- | ----- | ----- |
172
+
|**`assignmentLogger`**|[IAssignmentLogger](https://github.com/Eppo-exp/js-client-sdk-common/blob/main/src/assignment-logger.ts#L15)| A callback that sends each assignment to your data warehouse. Required only for experiment analysis. See [example](#assignment-logger) below. |`null`|
173
+
|**`requestTimeoutMs`**| number | Timeout in milliseconds for HTTPS requests for the experiment configurations. |`5000`|
174
+
|**`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`|
175
+
|**`pollAfterSuccessfulInitialization`**| boolean | Poll for new configurations (every 30 seconds) after successfully requesting the initial configurations. |`false`|
176
+
|**`pollAfterFailedInitialization`**| boolean | Poll for new configurations even if the initial configurations request failed. |`false`|
177
+
|**`throwOnFailedInitialization`**| boolean | Throw an error (reject the promise) if unable to fetch initial configurations during initialization. |`true`|
178
+
|**`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`|
179
+
144
180
145
181
## Appendix
146
182
@@ -215,3 +251,22 @@ The SDK uses `@react-native-async-storage` to store experiment configurations do
215
251
### Debugging
216
252
217
253
You may encounter a situation where a flag assignment produces a value that you did not expect. There are functions [detailed here](/sdks/sdk-features/debugging-flag-assignment/) to help you understand how flags are assigned, which will allow you to take corrective action on potential configuration issues.
254
+
255
+
256
+
### Assignment Logger Schema
257
+
258
+
The SDK will invoke the `logAssignment` function with an `assignment` object that contains the following fields:
| `subject` (string) | An identifier of the subject or user assigned to the experiment variation | UUID |
264
+
| `variation` (string) | The experiment variation the subject was assigned to | "control" |
265
+
| `timestamp` (string) | The time when the subject was assigned to the variation | 2021-06-22T17:35:12.000Z |
266
+
| `subjectAttributes` (map) | A free-form map of metadata about the subject. These attributes are only logged if passed to the SDK assignment function | `{"country": "US"}` |
267
+
| `featureFlag` (string) | An Eppo feature flag key | "recommendation-algo" |
More details about logging and examples (with Segment, Rudderstack, mParticle, and Snowplow) can be found in the [event logging](/sdks/event-logging/) page.
0 commit comments