From ecee021872ab1a4449623856e518505a54f725da Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Wed, 26 Feb 2025 11:37:52 +0100 Subject: [PATCH 1/5] docs(react-sdk,browser-sdk): updated various out-of-date docs --- packages/browser-sdk/README.md | 44 +++----- packages/react-sdk/README.md | 158 ++++++++++++--------------- packages/react-sdk/dev/plain/app.tsx | 3 - 3 files changed, 83 insertions(+), 122 deletions(-) diff --git a/packages/browser-sdk/README.md b/packages/browser-sdk/README.md index 588e9ae4..b9f74faf 100644 --- a/packages/browser-sdk/README.md +++ b/packages/browser-sdk/README.md @@ -100,15 +100,13 @@ type Configuration = { sseBaseUrl?: "https://livemessaging.bucket.co"; feedback?: undefined; // See FEEDBACK.md enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Bucket servers. Useful when you're impersonating a user - featureOptions?: { - fallbackFeatures?: - | string[] - | Record; // Enable these features if unable to contact bucket.co. Can be a list of feature keys or a record with configuration values - timeoutMs?: number; // Timeout for fetching features (default: 5000ms) - staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI (default: false) - staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase in the case of a non-SPA - expireTimeMs?: number; // In case we're unable to fetch features from Bucket, cached/stale features will be used instead until they expire after `expireTimeMs`. Default is 30 days - }; + fallbackFeatures?: + | string[] + | Record; // Enable these features if unable to contact bucket.co. Can be a list of feature keys or a record with configuration values + timeoutMs?: number; // Timeout for fetching features (default: 5000ms) + staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI (default: false) + staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase in the case of a non-SPA + expireTimeMs?: number; // In case we're unable to fetch features from Bucket, cached/stale features will be used instead until they expire after `expireTimeMs`. Default is 30 days }; ``` @@ -194,23 +192,6 @@ const override = bucketClient.getFeatureOverride("huddle"); // returns boolean | Feature overrides are persisted in `localStorage` and will be restored when the page is reloaded. -### Feature Updates - -You can listen for feature updates using `onFeaturesUpdated`: - -```ts -// Register a callback for feature updates -const unsubscribe = bucketClient.onFeaturesUpdated(() => { - console.log("Features were updated"); -}); - -// Later, stop listening for updates -unsubscribe(); -``` - -> [!NOTE] -> Note that the callback may be called even if features haven't actually changed. - ### Remote config Similar to `isEnabled`, each feature has a `config` property. This configuration is managed from within Bucket. @@ -312,11 +293,12 @@ See details in [Feedback HTTP API](https://docs.bucket.co/reference/http-trackin Event listeners allow for capturing various events occurring in the `BucketClient`. This is useful to build integrations with other system or for various debugging purposes. There are 5 kinds of events: -- FeaturesUpdated -- User -- Company -- Check -- Track +- `configCheck`: Your code used a feature config +- `enabledCheck`: Your code checked whether a specific feature should be enabled +- `featuresUpdated`: Features were updated. Either because they were loaded as part of initialization or because the user/company updated +- `user`: User information updated (similar to the `identify` call used in tracking terminology) +- `company`: Company information updated (sometimes to the `group` call used in tracking terminology) +- `track`: Track event occurred. Use the `on()` method to add an event listener to respond to certain events. See the API reference for details on each hook. diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index 06c24922..76e8cb74 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -52,107 +52,32 @@ import { BucketProvider } from "@bucketco/react-sdk"; company={{ id: "acme_inc", plan: "pro" }} user={{ id: "john doe" }} loadingComponent={} - featureOptions={{ fallbackFeatures: ["huddle"] }} > {/* children here are shown when loading finishes or immediately if no `loadingComponent` is given */} ; ``` -- `publishableKey` is used to connect the provider to an _environment_ on Bucket. Find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket, -- `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc. - > [!Note] - > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate feature targeting against, -- `featureOptions` contains configuration for features: - - - `fallbackFeatures`: A list of strings which specify which features to consider enabled if the SDK is unable to fetch features. Can be provided in two formats: - - ```ts - // Simple array of feature keys - featureOptions={{ - fallbackFeatures: ["feature1", "feature2"] - }} - - // Or with configuration overrides - featureOptions={{ - fallbackFeatures: { - "feature1": true, // just enable the feature - "feature2": { // enable with configuration - key: "variant-a", - payload: { - limit: 100, - mode: "test" - } - } - } - }} - ``` +### 3. Use `useFeature()` to get feature status - - `timeoutMs`: Timeout in milliseconds when fetching features from the server, - - `staleWhileRevalidate`: If set to `true`, stale features will be returned while refetching features in the background, - - `expireTimeMs`: If set, features will be cached between page loads for this duration (in milliseconds), - - `staleTimeMs`: Maximum time (in milliseconds) that stale features will be returned if `staleWhileRevalidate` is true and new features cannot be fetched. +Using the `useFeature` hook from your components lets you toggle features on/off and configure features through Remote Config: -Example with all options: +**Example:** ```tsx - - {children} - -``` - -- `loadingComponent` lets you specify an React component to be rendered instead of the children while the Bucket provider is initializing. If you want more control over loading screens, `useFeature()` returns `isLoading` which you can use to customize the loading experience: - - ```tsx - function LoadingBucket({ children }) { - const { isLoading } = useFeature("myFeature") - if (isLoading) { - return - } +function StartHuddleButton() { + const { + isEnabled, // boolean indicating if the feature is enabled + } = useFeature("huddle"); - return children + if (!isEnabled) { + return null; } - //-- Initialize the Bucket provider - - - {/* children here are shown when loading finishes */} - - - ``` - -- `enableTracking` (default: `true`): Set to `false` to stop sending tracking events and user/company updates to Bucket. Useful when you're impersonating a user, -- `apiBaseUrl`: Optional base URL for the Bucket API. Use this to override the default API endpoint, -- `appBaseUrl`: Optional base URL for the Bucket application. Use this to override the default app URL, -- `sseBaseUrl`: Optional base URL for Server-Sent Events. Use this to override the default SSE endpoint, -- `debug`: Set to `true` to enable debug logging to the console, -- `toolbar`: Optional configuration for the Bucket toolbar, -- `feedback`: Optional configuration for feedback collection: + return ; +} +``` - ```ts - { - enableLiveSatisfaction: boolean; // Enable/disable live satisfaction surveys - } - ``` +See a full example for `useFeature` [see below](#usefeature). ## Feature toggles @@ -212,6 +137,63 @@ configuration in your application. Note that, similar to `isEnabled`, accessing `config` on the object returned by `useFeature()` automatically generates a `check` event. +## `` component + +- `publishableKey` is used to connect the provider to an _environment_ on Bucket. Find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket, +- `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc. + > [!Note] + > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate feature targeting against, +- `fallbackFeatures`: A list of strings which specify which features to consider enabled if the SDK is unable to fetch features. Can be provided in two formats: + + ```ts + // Simple array of feature keys + fallbackFeatures={["feature1", "feature2"]} + + // Or with configuration overrides + fallbackFeatures: { + "feature1": true, // just enable the feature + "feature2": { // enable with configuration + key: "variant-a", + payload: { + limit: 100, + mode: "test" + } + } + } + ``` + +- `timeoutMs`: Timeout in milliseconds when fetching features from the server, +- `staleWhileRevalidate`: If set to `true`, stale features will be returned while refetching features in the background, +- `expireTimeMs`: If set, features will be cached between page loads for this duration (in milliseconds), +- `staleTimeMs`: Maximum time (in milliseconds) that stale features will be returned if `staleWhileRevalidate` is true and new features cannot be fetched. +- `loadingComponent` lets you specify an React component to be rendered instead of the children while the Bucket provider is initializing. If you want more control over loading screens, `useFeature()` returns `isLoading` which you can use to customize the loading experience: + + ```tsx + function LoadingBucket({ children }) { + const { isLoading } = useFeature("myFeature") + if (isLoading) { + return + } + + return children + } + + //-- Initialize the Bucket provider + + + {/* children here are shown when loading finishes */} + + + ``` + +- `enableTracking` Set to `false` to stop sending tracking events and user/company updates to Bucket. Useful when you're impersonating a user (defaults to `true`), +- `apiBaseUrl`: Optional base URL for the Bucket API. Use this to override the default API endpoint, +- `appBaseUrl`: Optional base URL for the Bucket application. Use this to override the default app URL, +- `sseBaseUrl`: Optional base URL for Server-Sent Events. Use this to override the default SSE endpoint, +- `debug`: Set to `true` to enable debug logging to the console, +- `toolbar`: Optional configuration for the Bucket toolbar, +- `feedback`: Optional configuration for feedback collection + ## Hooks ### `useFeature()` diff --git a/packages/react-sdk/dev/plain/app.tsx b/packages/react-sdk/dev/plain/app.tsx index 3890fa63..fb35b846 100644 --- a/packages/react-sdk/dev/plain/app.tsx +++ b/packages/react-sdk/dev/plain/app.tsx @@ -221,9 +221,6 @@ export function App() { return ( Date: Wed, 26 Feb 2025 11:41:02 +0100 Subject: [PATCH 2/5] minor fixup --- packages/react-sdk/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index 76e8cb74..efdbd592 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -39,8 +39,7 @@ declare module "@bucketco/react-sdk" { ### 2. Add the `BucketProvider` context provider -Add the `BucketProvider` context provider to your application. -This will initialize the Bucket SDK, fetch features and start listening for automated feedback survey events. +Add the `BucketProvider` context provider to your application: **Example:** @@ -139,6 +138,8 @@ generates a `check` event. ## `` component +The `` initializes the Bucket SDK, fetch features and start listening for automated feedback survey events. The component can be configured using a number of props: + - `publishableKey` is used to connect the provider to an _environment_ on Bucket. Find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket, - `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc. > [!Note] From 75391d04f4e2cca540b7c434f57cb8e2b1686dc7 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Wed, 26 Feb 2025 11:41:40 +0100 Subject: [PATCH 3/5] rename "setup" to "get started" --- packages/react-sdk/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index efdbd592..dceaf44d 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -10,7 +10,7 @@ Install via npm: npm i @bucketco/react-sdk ``` -## Setup +## Get started ### 1. Define Features (optional) From 8f5edfa66e1e5eda15789d2ef1875c60b7754e57 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Wed, 26 Feb 2025 11:43:23 +0100 Subject: [PATCH 4/5] elaborate --- packages/react-sdk/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index dceaf44d..5f64d755 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -76,7 +76,7 @@ function StartHuddleButton() { } ``` -See a full example for `useFeature` [see below](#usefeature). +`useFeature` can help you do much more. See a full example for `useFeature` [see below](#usefeature). ## Feature toggles From 61bdd48bb3b00290adff4b503fad6362e349a170 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Wed, 26 Feb 2025 11:53:28 +0100 Subject: [PATCH 5/5] AI review :+1: --- packages/browser-sdk/README.md | 2 +- packages/react-sdk/README.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/browser-sdk/README.md b/packages/browser-sdk/README.md index b9f74faf..82356416 100644 --- a/packages/browser-sdk/README.md +++ b/packages/browser-sdk/README.md @@ -105,7 +105,7 @@ type Configuration = { | Record; // Enable these features if unable to contact bucket.co. Can be a list of feature keys or a record with configuration values timeoutMs?: number; // Timeout for fetching features (default: 5000ms) staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI (default: false) - staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase in the case of a non-SPA + staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase this in the case of a non-SPA expireTimeMs?: number; // In case we're unable to fetch features from Bucket, cached/stale features will be used instead until they expire after `expireTimeMs`. Default is 30 days }; ``` diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index 5f64d755..3dda0a89 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -66,6 +66,7 @@ Using the `useFeature` hook from your components lets you toggle features on/off function StartHuddleButton() { const { isEnabled, // boolean indicating if the feature is enabled + track, // track usage of the feature } = useFeature("huddle"); if (!isEnabled) { @@ -86,7 +87,7 @@ If you supply `user` or `company` objects, they must include at least the `id` p In addition to the `id`, you must also supply anything additional that you want to be able to evaluate feature targeting rules against. The additional attributes are supplied using the `otherContext` prop. -Attributes cannot be nested (multiple levels) and must be either strings, integers or booleans. +Attributes cannot be nested (multiple levels) and must be either strings, numbers or booleans. A number of special attributes exist: - `name` -- display name for `user`/`company`, @@ -138,7 +139,7 @@ generates a `check` event. ## `` component -The `` initializes the Bucket SDK, fetch features and start listening for automated feedback survey events. The component can be configured using a number of props: +The `` initializes the Bucket SDK, fetches features and starts listening for automated feedback survey events. The component can be configured using a number of props: - `publishableKey` is used to connect the provider to an _environment_ on Bucket. Find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket, - `company`, `user` and `otherContext` make up the _context_ that is used to determine if a feature is enabled or not. `company` and `user` contexts are automatically transmitted to Bucket servers so the Bucket app can show you which companies have access to which features etc. @@ -187,7 +188,7 @@ The `` initializes the Bucket SDK, fetch features and start list ``` -- `enableTracking` Set to `false` to stop sending tracking events and user/company updates to Bucket. Useful when you're impersonating a user (defaults to `true`), +- `enableTracking`: Set to `false` to stop sending tracking events and user/company updates to Bucket. Useful when you're impersonating a user (defaults to `true`), - `apiBaseUrl`: Optional base URL for the Bucket API. Use this to override the default API endpoint, - `appBaseUrl`: Optional base URL for the Bucket application. Use this to override the default app URL, - `sseBaseUrl`: Optional base URL for Server-Sent Events. Use this to override the default SSE endpoint, @@ -231,7 +232,7 @@ function StartHuddleButton() {