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
The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
285
+
This is essential for robust experimentation powered by feature flags.
286
+
For example, a flag enhancing the appearance of a UI component might drive user engagement to a new feature; to test this hypothesis, telemetry collected by a [hook](#hooks) or [provider](#providers) can be associated with telemetry reported in the client's `track` function.
287
+
288
+
```ts
289
+
// flag is evaluated
290
+
client.getBooleanValue('new-feature', false);
291
+
292
+
// new feature is used and track function is called recording the usage
293
+
useNewFeature();
294
+
client.track('new-feature-used');
295
+
```
296
+
281
297
### Shutdown
282
298
283
299
The OpenFeature API provides a close function to perform a cleanup of all registered providers.
@@ -336,7 +352,7 @@ class MyProvider implements Provider {
336
352
}
337
353
338
354
// implement with "new OpenFeatureEventEmitter()", and use "emit()" to emit events
Multiple providers can be used by passing a `domain` to the `OpenFeatureProvider`:
172
173
173
174
```tsx
174
-
// Flags within this domain will use the a client/provider associated with `my-domain`,
175
+
// Flags within this domain will use the client/provider associated with `my-domain`,
175
176
function App() {
176
177
return (
177
178
<OpenFeatureProviderdomain={'my-domain'}>
@@ -233,11 +234,11 @@ Note that if your provider doesn't support updates, this configuration has no im
233
234
234
235
#### Suspense Support
235
236
236
-
> [!NOTE]
237
-
> React suspense is an experimental feature and subject to change in future versions.
237
+
> [!NOTE]
238
+
> React suspense is an experimental feature and is subject to change in future versions.
238
239
239
240
Frequently, providers need to perform some initial startup tasks.
240
-
It may be desireable not to display components with feature flags until this is complete, or when the context changes.
241
+
It may be desirable not to display components with feature flags until this is complete or when the context changes.
241
242
Built-in [suspense](https://react.dev/reference/react/Suspense) support makes this easy.
242
243
Use `useSuspenseFlag` or pass `{ suspend: true }` in the hook options to leverage this functionality.
243
244
@@ -270,11 +271,31 @@ function Fallback() {
270
271
// component to render before READY.
271
272
return <p>Waiting for provider to be ready...</p>;
272
273
}
273
-
274
274
```
275
275
276
276
This can be disabled in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)).
277
277
278
+
#### Tracking
279
+
280
+
The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
281
+
This is essential for robust experimentation powered by feature flags.
282
+
For example, a flag enhancing the appearance of a UI component might drive user engagement to a new feature; to test this hypothesis, telemetry collected by a [hook](/docs/reference/technologies/client/web/#hooks) or [provider](/docs/reference/technologies/client/web/#providers) can be associated with telemetry reported in the client's `track` function.
283
+
284
+
The React SDK includes a hook for firing tracking events in the `<OpenFeatureProvider>` context in use:
285
+
286
+
```tsx
287
+
function MyComponent() {
288
+
// get a tracking function for this <OpenFeatureProvider>.
289
+
const { track } =useTrack();
290
+
291
+
// call the tracking event
292
+
// can be done in render, useEffect, or in handlers, depending on your use case
293
+
track(eventName, trackingDetails);
294
+
295
+
return <>...</>;
296
+
}
297
+
```
298
+
278
299
### Testing
279
300
280
301
The React SDK includes a built-in context provider for testing.
@@ -339,23 +360,23 @@ class MyTestProvider implements Partial<Provider> {
339
360
> I get an error that says something like: `A React component suspended while rendering, but no fallback UI was specified.`
340
361
341
362
The OpenFeature React SDK features built-in [suspense support](#suspense-support).
342
-
This means that it will render your loading fallback automatically while the your provider starts up, and during context reconciliation for any of your components using feature flags!
363
+
This means that it will render your loading fallback automatically while your provider starts up and during context reconciliation for any of your components using feature flags!
343
364
If you use suspense and neglect to create a suspense boundary around any components using feature flags, you will see this error.
344
365
Add a suspense boundary to resolve this issue.
345
366
Alternatively, you can disable this suspense (the default) by removing `suspendWhileReconciling=true`, `suspendUntilReady=true` or `suspend=true` in the [evaluation hooks](#evaluation-hooks) or the [OpenFeatureProvider](#openfeatureprovider-context-provider) (which applies to all evaluation hooks in child components).
346
367
347
-
> I get odd rendering issues, or errors when components mount, if I use the suspense features.
368
+
> I get odd rendering issues or errors when components mount if I use the suspense features.
348
369
349
370
In React 16/17's "Legacy Suspense", when a component suspends, its sibling components initially mount and then are hidden.
350
371
This can cause surprising effects and inconsistencies if sibling components are rendered while the provider is still getting ready.
351
372
To fix this, you can upgrade to React 18, which uses "Concurrent Suspense", in which siblings are not mounted until their suspended sibling resolves.
352
373
Alternatively, if you cannot upgrade to React 18, you can use the `useWhenProviderReady` utility hook in any sibling components to prevent them from mounting until the provider is ready.
353
374
354
-
> I am using multiple `OpenFeatureProvider` contexts, but they are sharing the same provider or evaluation context. Why?
375
+
> I am using multiple `OpenFeatureProvider` contexts, but they share the same provider or evaluation context. Why?
355
376
356
377
The `OpenFeatureProvider` binds a `client` to all child components, but the provider and context associated with that client is controlled by the `domain` parameter.
357
378
This is consistent with all OpenFeature SDKs.
358
-
To scope an OpenFeatureProvider to a particular provider/context set the `domain` parameter on your `OpenFeatureProvider`:
379
+
To scope an OpenFeatureProvider to a particular provider/context, set the `domain` parameter on your `OpenFeatureProvider`:
359
380
360
381
```tsx
361
382
<OpenFeatureProviderdomain={'my-domain'}>
@@ -365,7 +386,7 @@ To scope an OpenFeatureProvider to a particular provider/context set the `domain
365
386
366
387
> I can import things form the `@openfeature/react-sdk`, `@openfeature/web-sdk`, and `@openfeature/core`; which should I use?
367
388
368
-
The `@openfeature/react-sdk` re-exports everything from its peers (`@openfeature/web-sdk` and `@openfeature/core`), and adds the React-specific features.
389
+
The `@openfeature/react-sdk` re-exports everything from its peers (`@openfeature/web-sdk` and `@openfeature/core`) and adds the React-specific features.
369
390
You can import everything from the `@openfeature/react-sdk` directly.
370
391
Avoid importing anything from `@openfeature/web-sdk` or `@openfeature/core`.
0 commit comments