React SDK

The React SDK sits around the Javascript Client SDK and gives React specific handlers.

Install

npm i @obelism/improve-sdk-react

Setup

In your config folder create the following file: improveClient.ts

import { generateImproveProvider } from '@obelism/improve-sdk-react'

export default generateImproveProvider(...)

API

generateImproveProvider

generateImproveProvider(improveArgs: ImproveSetupArgs) => ({
    ImproveProvider,
    useImproveStatus,
    usePostAnalytic,
    useTestValue,
    useFlagValue
})

Setup function that generates the React component and hooks. The argument is the same ImproveSetupArgs used by the Client SDK (organizationId, environment, optional config, fetchTimeout, baseUrl, dataLayer, …).

ImproveProvider

<ImproveProvider>
    {children}
</ImproveProvider>

On mount this automatically fetches the ImproveSDK and the config if not provided initially. Exposes a context that is used to populate data to the hooks down the component tree.

useImproveStatus

const status: 'loading' | 'setup' | 'error' = useImproveStatus()

Reports where the provider is in its lifecycle: loading while the SDK and config are being fetched, setup once it's ready, or error if setup failed. Useful for rendering a fallback until the SDK is ready.

useFlagValue

const value: string = useFlagValue(flagSlug: string, fallback?: string)

Wrapper around getFlagValue that's passed down when the context is set up. Returns fallback (when provided) while the config is still loading or when no flag matches the slug.

useTestValue

const value: string = useTestValue(testSlug: string, fallback?: string)

Wrapper around getTestValue that's passed down when the context is set up. Returns fallback (when provided) while the config is still loading or when no test matches the slug.

usePostAnalytic

usePostAnalytic takes no arguments and returns a global postAnalytic function. Events are test-independent: call the returned function with an event name, a required scope (a short, stable identifier for where/what the event refers to, not display text), and an optional payload, and the server attributes the event to whichever tests/flags the visitor was exposed to. Exposure is recorded by reading a variant with useTestValue / useFlagValue.

const postAnalytic = usePostAnalytic()

// Simple event
<button onClick={() => postAnalytic('add_to_cart', 'product_page')} />

// With a value for revenue / AOV, and GA4 ecommerce params for GTM
<button
	onClick={() =>
		postAnalytic('purchase', 'checkout', {
			value: 72.05,
			currency: 'USD',
			params: { ecommerce: { transaction_id: 'T_1', items: [/* … */] } },
		})
	}
/>

Wrapper around postAnalytic that's passed down when the context is set up.

NextJS App router

For NextJS we need to make sure the generated provider is marked as a client component. For this we need to declare the ImproveProvider within the file where we declare "use client".

This is needed because the ImproveProvider uses a useEffect to asynchronously fetch/load the JS SDK and fetch the config if needed. After it's set up it uses context to pass the data down.

'use client'

import { generateImproveProvider } from 'utils/generateImproveProvider'

const improveReact = generateImproveProvider(...)

export const ImproveProvider = improveReact.ImproveProvider
export const useTestValue = improveReact.useTestValue
export const useFlagValue = improveReact.useFlagValue
export const usePostAnalytic = improveReact.usePostAnalytic

On this page