Real-Time Audiences for Feature Experimentation segment qualification methods for the React SDK

How the React SDK handles ODP audience segments automatically, and how to use segment qualification methods for advanced use cases.

Prerequisites

You must enable and configure Real-Time Audiences for Feature Experimentation before using audience segment features.

Automatic segment fetching

When you enable ODP by passing createOdpManager() to createInstance, the React SDK automatically fetches qualified segments for the user when the <OptimizelyProvider> creates the user context. You do not need to manually call fetchQualifiedSegments in client components — the decide hooks (useDecide, etc.) already have access to the fetched segments when making decisions.

import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor,
  createOdpManager,
  OptimizelyProvider,
  useDecide,
} from '@optimizely/react-sdk';

const optimizely = createInstance({
  projectConfigManager: createPollingProjectConfigManager({
    sdkKey: 'YOUR_SDK_KEY',
  }),
  eventProcessor: createBatchEventProcessor(),
  odpManager: createOdpManager(),
});

function App() {
  return (
    <OptimizelyProvider client={optimizely} user={{ id: 'user-123' }}>
      <MyComponent />
    </OptimizelyProvider>
  );
}

function MyComponent() {
  // Segments are already fetched automatically — decisions use them
  const { decision, isLoading, error } = useDecide('my-flag');

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>{decision.enabled ? 'Feature on' : 'Feature off'}</div>;
}

Checking segment qualification

If you need to check whether the user is qualified for a specific segment (for example, for analytics or conditional rendering), use isQualifiedFor() on the user context:

import { useOptimizelyUserContext } from '@optimizely/react-sdk';

function SegmentDebug() {
  const { userContext, isLoading } = useOptimizelyUserContext();

  if (isLoading || !userContext) return null;

  const isQualified = userContext.isQualifiedFor('segment1');

  return <p>Is qualified for segment1: {isQualified ? 'Yes' : 'No'}</p>;
}

Segment caching

Fetched segments are cached in memory. The cache is configured when creating the ODP manager:

Cache size — Default: 100. Set to 0 to disable caching.
Cache timeout — Default: 600,000 milliseconds (10 minutes). Set to 0 to disable timeout (never expires).

const odpManager = createOdpManager({
  segmentsCacheSize: 100,
  segmentsCacheTimeout: 600000, // 10 minutes in milliseconds
});

The cache uses the least recently used (LRU) algorithm, so the oldest record is evicted when the maximum size is reached.

Manual segment fetching (server-side)

Manual fetchQualifiedSegments is primarily useful in server components or server-side code where there is no <OptimizelyProvider>. In these cases, you create a user context directly on the client and fetch segments before making decisions:

import { createInstance, createStaticProjectConfigManager, createOdpManager } from '@optimizely/react-sdk';

export default async function ServerComponent({ datafile }) {
  const client = createInstance({
    projectConfigManager: createStaticProjectConfigManager({ datafile }),
    odpManager: createOdpManager(),
  });

  await client.onReady();

  const userContext = client.createUserContext('user-123');
  await userContext.fetchQualifiedSegments();

  const decision = userContext.decide('my-flag');

  client.close();

  return decision.enabled ? <NewFeature /> : <Default />;
}

fetchQualifiedSegments

Parameters

Parameter	Type	Description
`options` (optional)	`OptimizelySegmentOption[]`	A set of options for fetching qualified segments from ODP.

Returns

Promise<boolean> — resolves with true if segments are fetched successfully, false otherwise.

Cache bypass options

OptimizelySegmentOption.IGNORE_CACHE — Bypass segments cache for lookup and save.
OptimizelySegmentOption.RESET_CACHE — Reset all segments cache.

isQualifiedFor

Checks if the user is qualified for the given audience segment.

Parameters

Parameter	Type	Description
`segment`	string	The ODP audience segment name to check.

Returns

true if the user is qualified, otherwise false.

SSR with pre-fetched segments

For server-side rendering, ODP segments require async I/O that is not available during synchronous rendering. Use getQualifiedSegments to pre-fetch segments server-side and pass them to the Provider:

import { getQualifiedSegments } from '@optimizely/react-sdk';

// In your server-side data fetching (e.g., Next.js layout or getServerSideProps)
const { segments } = await getQualifiedSegments('user-123', datafile);

<OptimizelyProvider
  client={optimizely}
  user={{ id: 'user-123' }}
  qualifiedSegments={segments}
  skipSegments={true}
>
  <App />
</OptimizelyProvider>

For more details, see the Next.js integration guide.

Source files

The language and platform source files containing the implementation for the React SDK are available on GitHub.

Updated about 3 hours ago