docs: add tracking sections (#1068)

- adds tracking to all relevant READMEs --------- Signed-off-by: Todd Baert <[email protected]>
open-feature · Oct 29, 2024 · e131faf · e131faf
1 parent 62f7668
commit e131faf
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 15 deletions.
diff --git 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 <p>Waiting for provider to be ready...</p>;
 }
-
 ```
 
 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 <OpenFeatureProvider> context in use:
+
+```tsx
+      function MyComponent() {
+
+        // get a tracking function for this <OpenFeatureProvider>.
+        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
@@ -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.                                                                                   |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
 
@@ -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
@@ -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<AnyProviderEvent> | undefined; 
+  events?: ProviderEventEmitter<AnyProviderEvent> | undefined;
 
   initialize?(context?: EvaluationContext | undefined): Promise<void> {
     // code to initialize your provider