Skip to content

Commit e131faf

Browse files
toddbaerttoddbaert
authored
docs: add tracking sections (#1068)
- adds tracking to all relevant READMEs --------- Signed-off-by: Todd Baert <[email protected]>
1 parent 62f7668 commit e131faf

File tree

3 files changed

+69
-15
lines changed

3 files changed

+69
-15
lines changed

‎packages/react/README.md

+25-3
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc
5454
- [Re-rendering with Context Changes](#re-rendering-with-context-changes)
5555
- [Re-rendering with Flag Configuration Changes](#re-rendering-with-flag-configuration-changes)
5656
- [Suspense Support](#suspense-support)
57+
- [Tracking](#tracking)
5758
- [Testing](#testing)
5859
- [FAQ and troubleshooting](#faq-and-troubleshooting)
5960
- [Resources](#resources)
@@ -132,7 +133,7 @@ function App() {
132133

133134
#### Evaluation hooks
134135

135-
Within the provider, you can use the various evaluation hooks to evaluate flags.
136+
Within the provider, you can use the various evaluation hooks to evaluate flags.
136137

137138
```tsx
138139
function Page() {
@@ -236,7 +237,7 @@ Note that if your provider doesn't support updates, this configuration has no im
236237

237238
#### Suspense Support
238239

239-
> [!NOTE]
240+
> [!NOTE]
240241
> React suspense is an experimental feature and subject to change in future versions.
241242
242243

@@ -274,11 +275,32 @@ function Fallback() {
274275
// component to render before READY.
275276
return <p>Waiting for provider to be ready...</p>;
276277
}
277-
278278
```
279279

280280
This can be disabled in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)).
281281

282+
#### Tracking
283+
284+
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+
The React SDK includes a hook for firing tracking events in the <OpenFeatureProvider> context in use:
289+
290+
```tsx
291+
function MyComponent() {
292+
293+
// get a tracking function for this <OpenFeatureProvider>.
294+
const { track } = useTrack();
295+
296+
// call the tracking event
297+
// can be done in render, useEffect, or in handlers, depending on your use case
298+
track(eventName, trackingDetails);
299+
300+
return <>...</>;
301+
}
302+
```
303+
282304
### Testing
283305

284306
The React SDK includes a built-in context provider for testing.

‎packages/server/README.md

+26-10
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ npm install --save @openfeature/server-sdk
6464
yarn add @openfeature/server-sdk @openfeature/core
6565
```
6666

67-
> [!NOTE]
67+
> [!NOTE]
6868
> `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations.
6969
> Every SDK version has a requirement on a single, specific version of this dependency.
7070
> For more information, and similar implications on libraries developed with OpenFeature see [considerations when extending](#considerations).
@@ -96,15 +96,16 @@ See [here](https://open-feature.github.io/js-sdk/modules/_openfeature_server_sdk
9696

9797
| Status | Features | Description |
9898
| ------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
99-
| ✅ | [Providers](#providers) | Integrate with a commercial, open source, or in-house feature management tool. |
100-
| ✅ | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](/docs/reference/concepts/evaluation-context). |
101-
| ✅ | [Hooks](#hooks) | Add functionality to various stages of the flag evaluation life-cycle. |
102-
| ✅ | [Logging](#logging) | Integrate with popular logging packages. |
103-
| ✅ | [Domains](#domains) | Logically bind clients with providers. |
104-
| ✅ | [Eventing](#eventing) | React to state changes in the provider or flag management system. |
105-
| ✅ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. |
106-
| ✅ | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
107-
| ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. |
99+
| ✅ | [Providers](#providers) | Integrate with a commercial, open source, or in-house feature management tool. |
100+
| ✅ | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](/docs/reference/concepts/evaluation-context). |
101+
| ✅ | [Hooks](#hooks) | Add functionality to various stages of the flag evaluation life-cycle. |
102+
| ✅ | [Logging](#logging) | Integrate with popular logging packages. |
103+
| ✅ | [Domains](#domains) | Logically bind clients with providers. |
104+
| ✅ | [Eventing](#eventing) | React to state changes in the provider or flag management system. |
105+
| ✅ | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
106+
| ✅ | [Tracking](#tracking) | Associate user actions with feature flag evaluations, particularly for A/B testing. |
107+
| ✅ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. |
108+
| ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. |
108109

109110
<sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
110111

@@ -289,6 +290,21 @@ app.use((req: Request, res: Response, next: NextFunction) => {
289290
})
290291
```
291292

293+
### Tracking
294+
295+
The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
296+
This is essential for robust experimentation powered by feature flags.
297+
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.
298+
299+
```ts
300+
// flag is evaluated
301+
await client.getBooleanValue('new-feature', false);
302+
303+
// new feature is used and track function is called recording the usage
304+
useNewFeature();
305+
client.track('new-feature-used');
306+
```
307+
292308
### Shutdown
293309

294310
The OpenFeature API provides a close function to perform a cleanup of all registered providers.

‎packages/web/README.md

+18-2
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ npm install --save @openfeature/web-sdk
6464
yarn add @openfeature/web-sdk @openfeature/core
6565
```
6666

67-
> [!NOTE]
67+
> [!NOTE]
6868
> `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations.
6969
> Every SDK version has a requirement on a single, specific version of this dependency.
7070
> For more information, and similar implications on libraries developed with OpenFeature see [considerations when extending](#considerations).
@@ -102,6 +102,7 @@ See [here](https://open-feature.github.io/js-sdk/modules/_openfeature_web_sdk.ht
102102
| ✅ | [Logging](#logging) | Integrate with popular logging packages. |
103103
| ✅ | [Domains](#domains) | Logically bind clients with providers. |
104104
| ✅ | [Eventing](#eventing) | React to state changes in the provider or flag management system. |
105+
| ✅ | [Tracking](#tracking) | Associate user actions with feature flag evaluations, particularly for A/B testing. |
105106
| ✅ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. |
106107
| ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. |
107108

@@ -281,6 +282,21 @@ client.addHandler(ProviderEvents.Error, (eventDetails) => {
281282
});
282283
```
283284

285+
### Tracking
286+
287+
The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
288+
This is essential for robust experimentation powered by feature flags.
289+
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.
290+
291+
```ts
292+
// flag is evaluated
293+
client.getBooleanValue('new-feature', false);
294+
295+
// new feature is used and track function is called recording the usage
296+
useNewFeature();
297+
client.track('new-feature-used');
298+
```
299+
284300
### Shutdown
285301

286302
The OpenFeature API provides a close function to perform a cleanup of all registered providers.
@@ -339,7 +355,7 @@ class MyProvider implements Provider {
339355
}
340356

341357
// implement with "new OpenFeatureEventEmitter()", and use "emit()" to emit events
342-
events?: ProviderEventEmitter<AnyProviderEvent> | undefined;
358+
events?: ProviderEventEmitter<AnyProviderEvent> | undefined;
343359

344360
initialize?(context?: EvaluationContext | undefined): Promise<void> {
345361
// code to initialize your provider

0 commit comments

Comments
 (0)