From d41d26d8ad503b35345079bc04384334a2ff03e9 Mon Sep 17 00:00:00 2001 From: Matus Vacula Date: Tue, 18 Feb 2025 16:25:11 +0100 Subject: [PATCH] chore: change directory structure --- SUMMARY.md | 18 +- {api-1 => api}/api-reference.md | 0 {api-1 => api}/http-api.md | 0 integrations/datadog.md | 2 +- sdk-docs/@bucketco/browser-sdk/README.md | 293 --- sdk-docs/@bucketco/browser-sdk/globals.md | 956 ------- sdk-docs/@bucketco/node-sdk/README.md | 447 ---- sdk-docs/@bucketco/node-sdk/globals.md | 2755 --------------------- sdk-docs/@bucketco/react-sdk/README.md | 239 -- sdk-docs/@bucketco/react-sdk/globals.md | 755 ------ sdk-docs/README.md | 90 - sdk-docs/_media/type-check-failed.png | Bin 105925 -> 0 bytes sdk-docs/documents/FEEDBACK.md | 481 ---- supported-languages/next.js.md | 4 +- supported-languages/overview.md | 2 +- 15 files changed, 13 insertions(+), 6029 deletions(-) rename {api-1 => api}/api-reference.md (100%) rename {api-1 => api}/http-api.md (100%) delete mode 100644 sdk-docs/@bucketco/browser-sdk/README.md delete mode 100644 sdk-docs/@bucketco/browser-sdk/globals.md delete mode 100644 sdk-docs/@bucketco/node-sdk/README.md delete mode 100644 sdk-docs/@bucketco/node-sdk/globals.md delete mode 100644 sdk-docs/@bucketco/react-sdk/README.md delete mode 100644 sdk-docs/@bucketco/react-sdk/globals.md delete mode 100644 sdk-docs/README.md delete mode 100644 sdk-docs/_media/type-check-failed.png delete mode 100644 sdk-docs/documents/FEEDBACK.md diff --git a/SUMMARY.md b/SUMMARY.md index f6a3182..b8011c8 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -21,13 +21,13 @@ ## Supported languages * [Overview](supported-languages/overview.md) -* [React SDK](sdk-docs/@bucketco/react-sdk/README.md) - * [Reference](sdk-docs/@bucketco/react-sdk/globals.md) -* [Browser SDK](sdk-docs/@bucketco/browser-sdk/README.md) - * [Feedback](sdk-docs/documents/FEEDBACK.md) - * [Reference](sdk-docs/@bucketco/browser-sdk/globals.md) -* [Node.js SDK](sdk-docs/@bucketco/node-sdk/README.md) - * [Reference](sdk-docs/@bucketco/node-sdk/globals.md) +* [React SDK](sdk/@bucketco/react-sdk/README.md) + * [Reference](sdk/@bucketco/react-sdk/globals.md) +* [Browser SDK](sdk/@bucketco/browser-sdk/README.md) + * [Feedback](sdk/documents/FEEDBACK.md) + * [Reference](sdk/@bucketco/browser-sdk/globals.md) +* [Node.js SDK](sdk/@bucketco/node-sdk/README.md) + * [Reference](sdk/@bucketco/node-sdk/globals.md) * [Next.js](supported-languages/next.js.md) * [OpenFeature](supported-languages/openfeature.md) * [Community support](supported-languages/community-support/README.md) @@ -71,5 +71,5 @@ ## API -* [Introduction](api-1/http-api.md) -* [API Reference](api-1/api-reference.md) +* [Introduction](api/http-api.md) +* [API Reference](api/api-reference.md) diff --git a/api-1/api-reference.md b/api/api-reference.md similarity index 100% rename from api-1/api-reference.md rename to api/api-reference.md diff --git a/api-1/http-api.md b/api/http-api.md similarity index 100% rename from api-1/http-api.md rename to api/http-api.md diff --git a/integrations/datadog.md b/integrations/datadog.md index 4087e34..6163e21 100644 --- a/integrations/datadog.md +++ b/integrations/datadog.md @@ -4,7 +4,7 @@ With the Datadog integration, you can enrich your RUM data with feature flag dat ### Get available features from Bucket -In this example, we're using the [Browser SDK](../sdk-docs/@bucketco/browser-sdk/): +In this example, we're using the [Browser SDK](../sdk/@bucketco/browser-sdk/): ```javascript //init diff --git a/sdk-docs/@bucketco/browser-sdk/README.md b/sdk-docs/@bucketco/browser-sdk/README.md deleted file mode 100644 index cf121a0..0000000 --- a/sdk-docs/@bucketco/browser-sdk/README.md +++ /dev/null @@ -1,293 +0,0 @@ ---- -layout: - visible: true -title: - visible: true -description: - visible: false -tableOfContents: - visible: true -outline: - visible: true -pagination: - visible: true ---- - -# Bucket Browser SDK - -Basic client for Bucket.co. If you're using React, you'll be better off with the Bucket React SDK. - -## Install - -First find your `publishableKey` under [environment settings](https://app.bucket.co/envs/current/settings/app-environments) in Bucket. - -The package can be imported or used directly in a HTML script tag: - -A. Import module - -```ts -import { BucketClient } from "@bucketco/browser-sdk"; - -const user = { - id: 42, - role: "manager", -}; - -const company = { - id: 99, - plan: "enterprise", -}; - -const bucketClient = new BucketClient({ publishableKey, user, company }); - -await bucketClient.initialize(); - -const { isEnabled, track, requestFeedback } = bucketClient.getFeature("huddle"); - -if (isEnabled) { - // show feature. When retrieving `isEnabled` the client automatically - // sends a "check" event for the "huddle" feature which is shown in the - // Bucket UI. - - // On usage, call `track` to let Bucket know that a user interacted with the feature - track(); - - // Use `requestFeedback` to create "Send feedback" buttons easily for specific - // features. This is not related to `track` and you can call them individually. - requestFeedback({ title: "Tell us what you think of Huddles" }); -} - -// `track` just calls `bucketClient.track()` to send an event using the same feature key -// You can also use `track` on the client directly to send any custom event. -bucketClient.track("huddle"); - -// similarly, `requestFeedback` just calls `bucketClient.requestFeedback({featureKey: })` -// which you can also call directly: -bucketClient.requestFeedback({ featureKey: "huddle" }); -``` - -B. Script tag (client-side directly in html) - -See [example/browser.html](https://github.com/bucketco/bucket-javascript-sdk/tree/main/packages/browser-sdk/example/browser.html) for a working example: - -```html - - -Loading... - -``` - -### Init options - -Supply these to the constructor call: - -```ts -type Configuration = { - logger: console; // by default only logs warn/error, by passing `console` you'll log everything - apiBaseUrl?: "https://front.bucket.co"; - 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[]; // Enable these features if unable to contact bucket.co - timeoutMs?: number; // Timeout for fetching features - staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI - 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`. - }; -}; -``` - -### Feature toggles - -Bucket determines which features are active for a given user/company. The user/company is given in the BucketClient constructor. - -If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety. -In addition to the `id`, you must also supply anything additional that you want to be able to evaluate feature targeting rules against. - -Attributes cannot be nested (multiple levels) and must be either strings, integers or booleans. -Some attributes are special and used in Bucket UI: - -- `name` is used to display name for `user`/`company`, -- `email` is accepted for `user`s and will be highlighted in the Bucket UI if available, -- `avatar` can be provided for both `user` and `company` and should be an URL to an image. - -```ts -const bucketClient = new BucketClient({ - publishableKey, - user: { - id: "user_123", - name: "John Doe", - email: "john@acme.com" - avatar: "https://example.com/images/udsy6363" - }, - company: { - id: "company_123", - name: "Acme, Inc", - avatar: "https://example.com/images/31232ds" - }, -}); -``` - -To retrieve features along with their targeting information, use `getFeature(key: string)`: - -```ts -const huddle = bucketClient.getFeature("huddle"); -// { -// isEnabled: true, -// track: () => Promise -// requestFeedback: (options: RequestFeedbackData) => void -// } -``` - -You can use `getFeatures()` to retrieve all enabled features currently. - -```ts -const features = bucketClient.getFeatures(); -// { -// huddle: { -// isEnabled: true, -// targetingVersion: 42, -// } -// } -``` - -`getFeatures()` is meant to be more low-level than `getFeature()` and it typically used -by down-stream clients, like the React SDK. - -Note that accessing `isEnabled` on the object returned by `getFeatures` does not automatically -generate a `check` event, contrary to the `isEnabled` property on the object return from `getFeature`. - -### Tracking feature usage - -The `track` function lets you send events to Bucket to denote feature usage. -By default Bucket expects event names to align with the feature keys, but -you can customize it as you wish. - -```ts -bucketClient.track("huddle", { voiceHuddle: true }); -``` - -### Updating user/company/other context - -Attributes given for the user/company/other context in the BucketClient constructor can be updated for use in feature targeting evaluation with the `updateUser()`, `updateCompany()` and `updateOtherContext()` methods. -They return a promise which resolves once the features have been re-evaluated follow the update of the attributes. - -The following shows how to let users self-opt-in for a new feature. The feature must have the rule `voiceHuddleOptIn IS true` set in the Bucket UI. - -```ts -// toggle opt-in for the voiceHuddle feature: -const { isEnabled } = bucketClient.getFeature("voiceHuddle"); -// this toggles the feature on/off. The promise returns once feature targeting has been -// re-evaluated. -await bucketClient.updateUser({ voiceHuddleOptIn: (!isEnabled).toString() }); -``` - -Note that user/company attributes are also stored remotely on the Bucket servers and will automatically be used to evaluate feature targeting if the page is refreshed. - -### Qualitative feedback - -Bucket can collect qualitative feedback from your users in the form of a [Customer Satisfaction Score](https://en.wikipedia.org/wiki/Customer_satisfaction) and a comment. - -#### Automated feedback collection - -The Bucket Browser SDK comes with automated feedback collection mode enabled by default, which lets the Bucket service ask your users for feedback for relevant features just after they've used them. - -Note: To get started with automatic feedback collection, make sure you've set `user` in the `BucketClient` constructor. - -Automated feedback surveys work even if you're not using the SDK to send events to Bucket. -It works because the Bucket Browser SDK maintains a live connection to Bucket's servers and can automatically show a feedback prompt whenever the Bucket servers determines that an event should trigger a prompt - regardless of how this event is sent to Bucket. - -You can find all the options to make changes to the default behavior in the [Bucket feedback documentation](../../documents/FEEDBACK.md). - -#### Bucket feedback UI - -Bucket can assist you with collecting your user's feedback by offering a pre-built UI, allowing you to get started with minimal code and effort. - -![image](https://github.com/bucketco/bucket-javascript-sdk/assets/34348/c387bac1-f2e2-4efd-9dda-5030d76f9532) - -[Read the Bucket feedback UI documentation](../../documents/FEEDBACK.md) - -#### Bucket feedback SDK - -Feedback can be submitted to Bucket using the SDK: - -```js -bucketClient.feedback({ - featureId: "my_feature_id", // String (required), copy from Feature feedback tab - score: 5, // Number: 1-5 (optional) - comment: "Absolutely stellar work!", // String (optional) -}); -``` - -#### Bucket feedback API - -If you are not using the Bucket Browser SDK, you can still submit feedback using the HTTP API. - -See details in [Feedback HTTP API](https://docs.bucket.co/reference/http-tracking-api#feedback) - -### Zero PII - -The Bucket Browser SDK doesn't collect any metadata and HTTP IP addresses are _not_ being stored. - -For tracking individual users, we recommend using something like database ID as userId, as it's unique and doesn't include any PII (personal identifiable information). If, however, you're using e.g. email address as userId, but prefer not to send any PII to Bucket, you can hash the sensitive data before sending it to Bucket: - -``` -import bucket from "@bucketco/browser-sdk"; -import { sha256 } from 'crypto-hash'; - -bucket.user(await sha256("john_doe")); -``` - -### Use of cookies - -The Bucket Browser SDK uses a couple of cookies to support automated feedback surveys. These cookies are not used for tracking purposes and thus should not need to appear in cookie consent forms. - -The two cookies are: - -- `bucket-prompt-${userId}`: store the last automated feedback prompt message ID received to avoid repeating surveys -- `bucket-token-${userId}`: caching a token used to connect to Bucket's live messaging infrastructure that is used to deliver automated feedback surveys in real time. - -### Typescript - -Types are bundled together with the library and exposed automatically when importing through a package manager. - -## Content Security Policy (CSP) - -If you are running with strict Content Security Policies active on your website, you will need to enable these directives in order to use the SDK: - -| Directive | Values | Reason | -| ----------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| connect-src | https://front.bucket.co | Basic functionality` | -| connect-src | https://livemessaging.bucket.co | Server sent events for use in automated feedback surveys, which allows for automatically collecting feedback when a user used a feature. | -| style-src | 'unsafe-inline' | The feedback UI is styled with inline styles. Not having this directive results unstyled HTML elements. | - -If you are including the Bucket tracking SDK with a ` -``` - -## Internationalization (i18n) - -By default, the feedback UI is written in English. However, you can supply your own -translations by passing an object in the options to either or both of the -`new BucketClient(options)` or `bucketClient.requestFeedback(options)` calls. -These translations will replace the English ones used by the feedback interface. -See examples below. - -![image](https://github.com/bucketco/bucket-tracking-sdk/assets/331790/68805b38-e9f6-4de5-9f55-188216983e3c) - -See [default English localization keys](https://github.com/bucketco/bucket-javascript-sdk/tree/main/packages/browser-sdk/src/feedback/ui/config/defaultTranslations.tsx) -for a reference of what translation keys can be supplied. - -### Static language configuration - -If you know the language at page load, you can configure your translation keys while -initializing the Bucket Browser SDK: - -```typescript -new BucketClient({ - publishableKey: "my-publishable-key", - feedback: { - ui: { - translations: { - DefaultQuestionLabel: - "Dans quelle mesure êtes-vous satisfait de cette fonctionnalité ?", - QuestionPlaceholder: - "Comment pouvons-nous améliorer cette fonctionnalité ?", - ScoreStatusDescription: "Choisissez une note et laissez un commentaire", - ScoreStatusLoading: "Chargement...", - ScoreStatusReceived: "La note a été reçue !", - ScoreVeryDissatisfiedLabel: "Très insatisfait", - ScoreDissatisfiedLabel: "Insatisfait", - ScoreNeutralLabel: "Neutre", - ScoreSatisfiedLabel: "Satisfait", - ScoreVerySatisfiedLabel: "Très satisfait", - SuccessMessage: "Merci d'avoir envoyé vos commentaires!", - SendButton: "Envoyer", - }, - }, - }, -}); -``` - -### Runtime language configuration - -If you only know the user's language after the page has loaded, you can provide -translations to either the `bucketClient.requestFeedback(options)` call or -the `autoFeedbackHandler` option before the feedback interface opens. -See examples below. - -```typescript -bucketClient.requestFeedback({ - ... // Other options - translations: { - // your translation keys - } -}) -``` - -### Translations - -When you are collecting feedback through the Bucket automation, you can intercept -the default prompt handling and override the defaults. - -If you set the prompt question in the Bucket app to be one of your own translation -keys, you can even get a translated version of the question you want to ask your -customer in the feedback UI. - -```javascript -new BucketClient({ - publishableKey: "bucket-publishable-key", - feedback: { - autoFeedbackHandler: (message, handlers) => { - const translatedQuestion = - i18nLookup[message.question] ?? message.question; - handlers.openFeedbackForm({ - title: translatedQuestion, - translations: { - // your static translation keys - }, - }); - }, - }, -}); -``` - -## Custom styling - -You can adapt parts of the look of the Bucket feedback UI by applying CSS custom -properties to your page in your CSS `:root`-scope. - -For example, a dark mode theme might look like this: - -```html -image -``` - -```css -:root { - --bucket-feedback-dialog-background-color: #1e1f24; - --bucket-feedback-dialog-color: rgba(255, 255, 255, 0.92); - --bucket-feedback-dialog-secondary-color: rgba(255, 255, 255, 0.3); - --bucket-feedback-dialog-border: rgba(255, 255, 255, 0.16); - --bucket-feedback-dialog-primary-button-background-color: #655bfa; - --bucket-feedback-dialog-primary-button-color: white; - --bucket-feedback-dialog-input-border-color: rgba(255, 255, 255, 0.16); - --bucket-feedback-dialog-input-focus-border-color: rgba(255, 255, 255, 0.3); - --bucket-feedback-dialog-error-color: #f56565; - - --bucket-feedback-dialog-rating-1-color: #ed8936; - --bucket-feedback-dialog-rating-1-background-color: #7b341e; - --bucket-feedback-dialog-rating-2-color: #dd6b20; - --bucket-feedback-dialog-rating-2-background-color: #652b19; - --bucket-feedback-dialog-rating-3-color: #787c91; - --bucket-feedback-dialog-rating-3-background-color: #3e404c; - --bucket-feedback-dialog-rating-4-color: #38a169; - --bucket-feedback-dialog-rating-4-background-color: #1c4532; - --bucket-feedback-dialog-rating-5-color: #48bb78; - --bucket-feedback-dialog-rating-5-background-color: #22543d; - - --bucket-feedback-dialog-submitted-check-background-color: #38a169; - --bucket-feedback-dialog-submitted-check-color: #ffffff; -} -``` - -Other examples of custom styling can be found in our [development example style-sheet](https://github.com/bucketco/bucket-javascript-sdk/tree/main/packages/browser-sdk/src/feedback/ui/index.css). - -## Using your own UI to collect feedback - -You may have very strict design guidelines for your app and maybe the Bucket feedback -UI doesn't quite work for you. In this case, you can implement your own feedback -collection mechanism, which follows your own design guidelines. This is the data -type you need to collect: - -```typescript -type DataToCollect = { - // Customer satisfaction score - score?: 1 | 2 | 3 | 4 | 5; - - // The comment. - comment?: string; -}; -``` - -Either `score` or `comment` must be defined in order to pass validation in the -Bucket API. - -### Manual feedback collection with custom UI - -Examples of a HTML-form that collects the relevant data can be found -in [feedback.html](https://github.com/bucketco/bucket-javascript-sdk/tree/main/packages/browser-sdk/example/feedback/feedback.html) and [feedback.jsx](https://github.com/bucketco/bucket-javascript-sdk/tree/main/packages/browser-sdk/example/feedback/Feedback.jsx). - -Once you have collected the feedback data, pass it along to `bucketClient.feedback()`: - -```javascript -bucketClient.feedback({ - featureKey: "bucket-feature-key", - userId: "your-user-id", - score: 5, - comment: "Best thing I've ever tried!", -}); -``` - -### Intercepting automated feedback survey events - -When using automated feedback surveys, the Bucket service will, when specified, -send a feedback prompt message to your user's instance of the Bucket Browser SDK. -This will result in the feedback UI being opened. - -You can intercept this behavior and open your own custom feedback collection form: - -```typescript -new Bucketclient({ - publishableKey: "bucket-publishable-key", - feedback: { - autoFeedbackHandler: async (promptMessage, handlers) => { - // This opens your custom UI - customFeedbackCollection({ - // The question configured in the Bucket UI for the feature - question: promptMessage.question, - // When the user successfully submits feedback data. - // Use this instead of `bucketClient.feedback()`, otherwise - // the feedback prompt handler will keep being called - // with the same prompt message - onFeedbackSubmitted: (feedback) => { - handlers.reply(feedback); - }, - // When the user closes the custom feedback form - // without leaving any response. - // It is important to feed this back, otherwise - // the feedback prompt handler will keep being called - // with the same prompt message - onFeedbackDismissed: () => { - handlers.reply(null); - }, - }); - }, - }, -}); -``` diff --git a/supported-languages/next.js.md b/supported-languages/next.js.md index af4f554..aa11ca1 100644 --- a/supported-languages/next.js.md +++ b/supported-languages/next.js.md @@ -1,6 +1,6 @@ # Next.js -Using Bucket with Next.js is straightforward. You can use the [@bucketco/node-sdk](broken-reference) on the server or [@bucketco/react-sdk](../sdk-docs/@bucketco/react-sdk/) in the browser. Handling feature targeting server-side is often advantageous because it removes the need for additional handling of loading states. +Using Bucket with Next.js is straightforward. You can use the [@bucketco/node-sdk](broken-reference) on the server or [@bucketco/react-sdk](../sdk/@bucketco/react-sdk/) in the browser. Handling feature targeting server-side is often advantageous because it removes the need for additional handling of loading states. ## Server-side Rendering (SSR) @@ -175,4 +175,4 @@ function StartHuddle() { } ``` -For more details, please see the [React SDK documentation](../sdk-docs/@bucketco/react-sdk/) +For more details, please see the [React SDK documentation](../sdk/@bucketco/react-sdk/) diff --git a/supported-languages/overview.md b/supported-languages/overview.md index 179222d..6892590 100644 --- a/supported-languages/overview.md +++ b/supported-languages/overview.md @@ -14,6 +14,6 @@ layout: # Overview -
ReactFeature flagging and evaluation for Reactreact.svg
BrowserClient-side feature flagging and evaluationts-js.svg
Node.jsServer-side feature flagging and evaluationnode-js.svg
Next.jsFeature flagging and evaluation for Next.jsnext-js.svg
OpenFeatureBucket supports OpenFeature.openfeature.svg
HTTP APIDon't use these languages or frameworks? Use our APIapi.svg
+
ReactFeature flagging and evaluation for Reactreact.svg
BrowserClient-side feature flagging and evaluationts-js.svg
Node.jsServer-side feature flagging and evaluationnode-js.svg
Next.jsFeature flagging and evaluation for Next.jsnext-js.svg
OpenFeatureBucket supports OpenFeature.openfeature.svg
HTTP APIDon't use these languages or frameworks? Use our APIapi.svg
###