Skip to content

Commit c069369

Browse files
updated react native layout (#491)
* updated react native layout * a few edits to getStringAssignment example
1 parent 1cfb232 commit c069369

File tree

1 file changed

+116
-61
lines changed

1 file changed

+116
-61
lines changed

docs/sdks/client-sdks/react-native.md

Lines changed: 116 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@ Eppo's open source React Native SDK can be used for both feature flagging and ex
88
- [GitHub repository](https://github.com/Eppo-exp/react-native-sdk)
99
- [NPM package](https://www.npmjs.com/package/@eppo/react-native-sdk)
1010

11-
## 1. Install the SDK
11+
## Getting Started
12+
13+
### Installation
1214

1315
You can install the SDK with Yarn or NPM:
1416

@@ -31,104 +33,111 @@ npm install @eppo/react-native-sdk
3133

3234
</Tabs>
3335

34-
## 2. Initialize the SDK
36+
### Usage
37+
38+
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.
3539

36-
Initialize the SDK with a SDK key, which can be generated in the Eppo interface:
40+
#### Initialize once
3741

3842
```javascript
3943
import { init } from "@eppo/react-native-sdk";
4044

41-
await init({
42-
apiKey: "<SDK_KEY>",
43-
assignmentLogger,
44-
});
45+
await init({ apiKey: "<SDK-KEY>" });
4546
```
4647

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.
4848

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
5050

51+
```javascript
52+
import * as EppoSdk from "@eppo/react-native-sdk";
5153

52-
### Define an assignment logger (experiment assignment only)
54+
const eppoClient = EppoSdk.getInstance();
55+
const user = getCurrentUser();
5356

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.
57+
const variation = eppoClient.getBooleanAssignment('show-new-feature', user.id, {
58+
'country': user.country,
59+
'device': user.device,
60+
}, false);
61+
```
5562

56-
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).
5764

58-
```javascript
59-
import { IAssignmentLogger } from '@eppo/react-native-sdk';
60-
import { createClient, AnalyticsProvider } from '@segment/analytics-react-native';
61-
import { useAnalytics } from '@segment/analytics-react-native';
65+
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.
6270

63-
// Connect to Segment (or your own event-tracking system, it can be any system you like)
64-
const segmentClient = createClient({
65-
writeKey: 'SEGMENT_API_KEY'
71+
```javascript
72+
await init({
73+
apiKey: "<SDK_KEY>",
74+
assignmentLogger,
6675
});
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`:
81+
82+
```javascript
83+
import { IAssignmentLogger } from "@eppo/react-native-sdk";
84+
import { AnalyticsBrowser } from "@segment/analytics-next";
85+
86+
// Connect to Segment (or your own event-tracking system)
87+
const analytics = AnalyticsBrowser.load({ writeKey: "<SEGMENT_WRITE_KEY>" });
6788

6889
const assignmentLogger: IAssignmentLogger = {
6990
logAssignment(assignment) {
70-
const { track } = useAnalytics();
71-
72-
track(
73-
'Eppo Randomized Assignment',
74-
{
75-
userId: assignment.subject,
76-
type: 'track',
77-
properties: { ...assignment }
78-
}
91+
analytics.track({
92+
userId: assignment.subject,
93+
event: "Eppo Randomized Assignment",
94+
type: "track",
95+
properties: { ...assignment },
7996
});
8097
},
8198
};
8299
```
83100

84-
The SDK will invoke the `logAssignment` function with an `assignment` object that contains the following fields:
85-
86-
| Field | Description | Example |
87-
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
88-
| `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
101102

102103
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.
103104

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.
105108

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`:
108110

109111
```javascript
110112
import * as EppoSdk from "@eppo/react-native-sdk";
111113

112114
const eppoClient = EppoSdk.getInstance();
115+
116+
// replace this with your own user object
117+
const user = getCurrentUser();
118+
113119
const variation = eppoClient.getStringAssignment(
114-
"<FLAG-KEY>",
115-
"<SUBJECT-KEY>",
116-
<SUBJECT-ATTRIBUTES>, // Metadata used for targeting
117-
"<DEFAULT-VALUE>",
118-
);
120+
'show-new-feature', // flagKey
121+
user.id, // subjectKey
122+
{'country': user.country, 'device': user.device}, // subjectAttributes
123+
'default-value' // defaultValue
124+
)
119125
```
120126

121-
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.
122128

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.
126134
- `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.
127135

136+
![Example flag key](/img/feature-flagging/flag-key.png)
128137

129138
### Typed assignments
130139

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:
132141

133142
```javascript
134143
getBooleanAssignment(...)
@@ -138,9 +147,36 @@ getStringAssignment(...)
138147
getJSONAssignment(...)
139148
```
140149

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+
144180

145181
## Appendix
146182

@@ -215,3 +251,22 @@ The SDK uses `@react-native-async-storage` to store experiment configurations do
215251
### Debugging
216252

217253
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:
259+
260+
| Field | Description | Example |
261+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
262+
| `experiment` (string) | An Eppo experiment key | "recommendation-algo-allocation-17" |
263+
| `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" |
268+
| `allocation` (string) | An Eppo allocation key | "allocation-17" |
269+
270+
:::note
271+
More details about logging and examples (with Segment, Rudderstack, mParticle, and Snowplow) can be found in the [event logging](/sdks/event-logging/) page.
272+
:::

0 commit comments

Comments
 (0)