Initialize the React Native SDK

Use the createInstance method to initialize the React Native SDK and instantiate a Client instance. Each client corresponds to the datafile representing the state of a project for a certain environment.

Minimum SDK version

v4.0.0+

For versions 3.x and earlier, see React Native SDK prior to v4.

Description

The createInstance method accepts a modular configuration object. Unlike v3, where options like sdkKey, datafile, and event batching were top-level parameters, v4 uses dedicated factory functions for each component.

Important: You must use createInstance from @optimizely/react-sdk, not from @optimizely/optimizely-sdk. A client created directly from the JS SDK will not work correctly with <OptimizelyProvider> and hooks.

Parameters

The following table lists the required and optional parameters for the createInstance configuration object:

Returns

Instantiates a Client instance. In v4, createInstance throws an error on invalid config (v3 returned null).

Example

Instantiate with a datafile

Use createStaticProjectConfigManager for a fixed datafile with no polling:

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

const optimizely = createInstance({
  projectConfigManager: createStaticProjectConfigManager({
    datafile: optimizelyDatafile,
  }),
  eventProcessor: createForwardingEventProcessor(),
});

Instantiate with the SDK key

Use createPollingProjectConfigManager to have the SDK fetch and poll for the datafile:

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

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

Instantiate with both SDK key and datafile

Use the given datafile immediately, then fetch and poll for updates in the background:

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

const optimizely = createInstance({
  projectConfigManager: createPollingProjectConfigManager({
    sdkKey: 'YOUR_SDK_KEY',
    datafile: optimizelyDatafile,
    autoUpdate: true,
  }),
  eventProcessor: createBatchEventProcessor(),
});

Instantiate offline with SDK key

The React Native SDK provides default datafile caching to support fast initialization and offline mode. This means you can initialize using the SDK key even when there is no Internet connectivity. Once downloaded, the datafile is stored in the cache on the user's device. When the SDK is initialized the next time, it uses the datafile from the cache if available and resolves the ready promise. It then continues to load the latest datafile from the server. This results in faster SDK initialization.

Render an OptimizelyProvider with a client and user

To use the React Native SDK hooks inside your app, render an OptimizelyProvider as the parent of your root app component. Provide your client as the client prop and a user object:

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

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

export default function App() {
  return (
    <OptimizelyProvider
      client={optimizely}
      user={{ id: '<YOUR_USER_ID>' }}
    >
      <App />
    </OptimizelyProvider>
  );
}

Render an OptimizelyProvider in VUID-only mode

For VUID-only mode (no user ID), pass an empty object as the user prop. The SDK uses an auto-generated visitor UID for decisions and event tracking. You must enable VUID by passing createVuidManager and createOdpManager to createInstance:

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

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

export default function App() {
  return (
    <OptimizelyProvider
      client={optimizely}
      user={{}}
    >
      <App />
    </OptimizelyProvider>
  );
}

Config manager factories

Polling config manager options

Event processor factories

📘

Note

Event processing is opt-in in v4. If no eventProcessor is passed to createInstance, no events are dispatched. To disable event dispatching, simply omit the eventProcessor parameter.

Other configurable modules

Full client creation example

import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor,
  createOdpManager,
  createVuidManager,
  createLogger,
  createErrorNotifier,
  DEBUG,
} from '@optimizely/react-sdk';

const optimizely = createInstance({
  projectConfigManager: createPollingProjectConfigManager({
    sdkKey: 'YOUR_SDK_KEY',
    autoUpdate: true,
    updateInterval: 60000,
  }),
  eventProcessor: createBatchEventProcessor({
    batchSize: 10,
    flushInterval: 2000,
  }),
  odpManager: createOdpManager(),
  vuidManager: createVuidManager({ enableVuid: true }),
  logger: createLogger({ logLevel: DEBUG }),
  errorNotifier: createErrorNotifier({
    handleError: (error) => console.error('Custom error handler', error),
  }),
});

Dispose of the client

For effective resource management, properly close the Optimizely client instance when it is no longer needed by calling optimizely.close().

The .close() method ensures that the processes and queues associated with the instance are properly released. This is essential for preventing memory leaks, especially in environments where resources are limited.

See Close Optimizely on application exit.

Source files

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