diff --git a/packages/react/README.md b/packages/react/README.md index 08a88168a..4c02f71d5 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -54,6 +54,7 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc - [Re-rendering with Context Changes](#re-rendering-with-context-changes) - [Re-rendering with Flag Configuration Changes](#re-rendering-with-flag-configuration-changes) - [Suspense Support](#suspense-support) + - [Tracking](#tracking) - [Testing](#testing) - [FAQ and troubleshooting](#faq-and-troubleshooting) - [Resources](#resources) @@ -132,7 +133,7 @@ function App() { #### Evaluation hooks -Within the provider, you can use the various evaluation hooks to evaluate flags. +Within the provider, you can use the various evaluation hooks to evaluate flags. ```tsx function Page() { @@ -236,7 +237,7 @@ Note that if your provider doesn't support updates, this configuration has no im #### Suspense Support -> [!NOTE] +> [!NOTE] > React suspense is an experimental feature and subject to change in future versions. @@ -274,11 +275,32 @@ function Fallback() { // component to render before READY. return

Waiting for provider to be ready...

; } - ``` This can be disabled in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)). +#### Tracking + +The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations. +This is essential for robust experimentation powered by feature flags. +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. + +The React SDK includes a hook for firing tracking events in the context in use: + +```tsx + function MyComponent() { + + // get a tracking function for this . + const { track } = useTrack(); + + // call the tracking event + // can be done in render, useEffect, or in handlers, depending on your use case + track(eventName, trackingDetails); + + return <>...; + } +``` + ### Testing The React SDK includes a built-in context provider for testing. diff --git a/packages/server/README.md b/packages/server/README.md index 54912ce01..4c2ab2a75 100644 --- a/packages/server/README.md +++ b/packages/server/README.md @@ -64,7 +64,7 @@ npm install --save @openfeature/server-sdk yarn add @openfeature/server-sdk @openfeature/core ``` -> [!NOTE] +> [!NOTE] > `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations. > Every SDK version has a requirement on a single, specific version of this dependency. > 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 | Status | Features | Description | | ------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| ✅ | [Providers](#providers) | Integrate with a commercial, open source, or in-house feature management tool. | -| ✅ | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](/docs/reference/concepts/evaluation-context). | -| ✅ | [Hooks](#hooks) | Add functionality to various stages of the flag evaluation life-cycle. | -| ✅ | [Logging](#logging) | Integrate with popular logging packages. | -| ✅ | [Domains](#domains) | Logically bind clients with providers. | -| ✅ | [Eventing](#eventing) | React to state changes in the provider or flag management system. | -| ✅ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. | -| ✅ | [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) | -| ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. | +| ✅ | [Providers](#providers) | Integrate with a commercial, open source, or in-house feature management tool. | +| ✅ | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](/docs/reference/concepts/evaluation-context). | +| ✅ | [Hooks](#hooks) | Add functionality to various stages of the flag evaluation life-cycle. | +| ✅ | [Logging](#logging) | Integrate with popular logging packages. | +| ✅ | [Domains](#domains) | Logically bind clients with providers. | +| ✅ | [Eventing](#eventing) | React to state changes in the provider or flag management system. | +| ✅ | [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) | +| ✅ | [Tracking](#tracking) | Associate user actions with feature flag evaluations, particularly for A/B testing. | +| ✅ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. | +| ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. | Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌ @@ -289,6 +290,21 @@ app.use((req: Request, res: Response, next: NextFunction) => { }) ``` +### Tracking + +The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations. +This is essential for robust experimentation powered by feature flags. +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. + +```ts +// flag is evaluated +await client.getBooleanValue('new-feature', false); + +// new feature is used and track function is called recording the usage +useNewFeature(); +client.track('new-feature-used'); +``` + ### Shutdown The OpenFeature API provides a close function to perform a cleanup of all registered providers. diff --git a/packages/web/README.md b/packages/web/README.md index 8de41c730..d840d23ae 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -64,7 +64,7 @@ npm install --save @openfeature/web-sdk yarn add @openfeature/web-sdk @openfeature/core ``` -> [!NOTE] +> [!NOTE] > `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations. > Every SDK version has a requirement on a single, specific version of this dependency. > 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 | ✅ | [Logging](#logging) | Integrate with popular logging packages. | | ✅ | [Domains](#domains) | Logically bind clients with providers. | | ✅ | [Eventing](#eventing) | React to state changes in the provider or flag management system. | +| ✅ | [Tracking](#tracking) | Associate user actions with feature flag evaluations, particularly for A/B testing. | | ✅ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. | | ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. | @@ -281,6 +282,21 @@ client.addHandler(ProviderEvents.Error, (eventDetails) => { }); ``` +### Tracking + +The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations. +This is essential for robust experimentation powered by feature flags. +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. + +```ts +// flag is evaluated +client.getBooleanValue('new-feature', false); + +// new feature is used and track function is called recording the usage +useNewFeature(); +client.track('new-feature-used'); +``` + ### Shutdown The OpenFeature API provides a close function to perform a cleanup of all registered providers. @@ -339,7 +355,7 @@ class MyProvider implements Provider { } // implement with "new OpenFeatureEventEmitter()", and use "emit()" to emit events - events?: ProviderEventEmitter | undefined; + events?: ProviderEventEmitter | undefined; initialize?(context?: EvaluationContext | undefined): Promise { // code to initialize your provider