React SDK

What is the React SDK?

The React SDK is an open-source client-side Typescript/JavaScript library that allows you to integrate Bucket with your app.

It also works out of the box with Next.js.

Getting started

You can find the full developer documentation on GitHub.

Install the SDK

Install the SDK.

npm i @bucketco/react-sdk

Define your features

To get type safe feature definitions, extend the definition of the Features interface and define which features you have. See the example below for the details.

If no explicit feature definitions are provided, there will be no types checked feature lookups.

Example

import "@bucketco/react-sdk";

// Define your features by extending the `Features` interface in @bucketco/react-sdk
declare module "@bucketco/react-sdk" {
  interface Features {
    huddle: boolean;
    recordVideo: boolean;
  }
}

Add the context provider

Add the BucketProvider context provider to your application. This will initialize the Bucket SDK to fetch feature configuration and listen for automated feedback survey events.

Once a features has been successfully fetched, they are stored in localStorage and will be used as a fallback for up to 30 days if the client cannot connect to Bucket's servers.

import { BucketProvider } from "@bucketco/react-sdk";

<BucketProvider
  publishableKey="{YOUR_PUBLISHABLE_KEY}"
  company={{ id: "acme_inc" }}
  user={{ id: "john doe" }}
  loadingComponent={<Loading />}
  fallbackFeatures={["huddle"]}
>
  {/* children here are shown when loading finishes or immediately if no `loadingComponent` is given */}
</BucketProvider>;

• publishableKey is used to connect the provider to an environment on Bucket. Find your publishableKey under Activity on https://app.bucket.co.

• 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.

  If you specify company and/or user they must have at least the id property plus anything additional you want to be able to evaluate feature targeting against. See "Managing Bucket context" below.

• fallbackFeatures is a list of strings which specify which features to consider enabled if the SDK is unable to fetch features.

• 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:

  function LoadingBucket({ children }) {
    const { isLoading } = useFeature("myFeature")
    if (isLoading) {
      return <Spinner />
    }
  
    return children
  }
  
  //-- Initialize the Bucket provider
  <BucketProvider publishableKey="{YOUR_PUBLISHABLE_KEY}">
    <LoadingBucket>
    {/* children here are shown when loading finishes */}
    </LoadingBucket>
  </BucketProvider>

Implement feature targeting

useFeature() returns the state of a given feature for the current company/user:

import { useFeature } from "@bucketco/react-sdk";

function StartHuddleButton() {
  const {isEnabled, track} = useFeature("huddle");

  if (!isEnabled) {
    return null;
  }

  return <button onClick={() => track()}>Start huddle!</button>;
}

This example checks if a user should be shown the Start huddle button by checking the isEnabled boolean and then sends an event once the Huddle starts to let Bucket automatically track usage and collect feedback.

Custom event tracking

useTrack() lets you send custom events to Bucket whenever a user uses a feature:

import { useFeature, useTrack } from "@bucketco/react-sdk";

function StartHuddleButton() {
  const { isLoading, isEnabled } = useFeature("huddle");
  const track = useTrack();

  if (isLoading) {
    return <Loading />;
  }

  if (!isEnabled) {
    return null;
  }

  // send a custom event, in this case using the "Object/Action" terminology
  // by using the `track` function from `useTrack` and send along
  // some custom attributes along.
  return (
    <Button onClick={() => track("Huddle Started", {type: "voice"})}>
      Start voice huddle!
    </Button>
  );
}

Add additional hooks

There are additional hooks available:

• useRequestFeedback(): Returns a function that lets you open a dialog to ask for feedback on a specific feature.

• useSendFeedback(): Returns a function that lets you send feedback to Bucket.

Complete developer documentation

You can find the complete developer documentation on GitHub.