@@ -35,13 +33,19 @@ based on the [Optimization Core Library](../universal/core-sdk/README.md). This
- [Event Builder Options](#event-builder-options)
- [Fetch Options](#fetch-options)
- [Personalization Options](#personalization-options)
-- [Component Tracking](#component-tracking)
+- [Entry Tracking](#entry-tracking)
- [`
`](#optimizedentry-)
- - [ScrollView vs Non-ScrollView Usage](#scrollview-vs-non-scrollview-usage)
- - [Inside ScrollView (Recommended for Scrollable Content)](#inside-scrollview-recommended-for-scrollable-content)
- - [Outside ScrollView (For Non-Scrollable Content)](#outside-scrollview-for-non-scrollable-content)
+ - [With vs Without OptimizationScrollProvider](#with-vs-without-optimizationscrollprovider)
+ - [With OptimizationScrollProvider (Recommended for Scrollable Content)](#with-optimizationscrollprovider-recommended-for-scrollable-content)
+ - [Without OptimizationScrollProvider (For Non-Scrollable Content)](#without-optimizationscrollprovider-for-non-scrollable-content)
- [Custom Tracking Thresholds](#custom-tracking-thresholds)
- [Manual Analytics Tracking](#manual-analytics-tracking)
+ - [`useInteractionTracking`](#useinteractiontracking)
+ - [`useTapTracking`](#usetaptracking)
+- [Screen Tracking](#screen-tracking)
+ - [`useScreenTracking`](#usescreentracking)
+ - [`useScreenTrackingCallback`](#usescreentrackingcallback)
+ - [`OptimizationNavigationContainer`](#optimizationnavigationcontainer)
- [OptimizationRoot](#optimizationroot)
- [Preview Panel](#preview-panel)
- [Live Updates Behavior](#live-updates-behavior)
@@ -51,6 +55,7 @@ based on the [Optimization Core Library](../universal/core-sdk/README.md). This
- [2. Global Setting via OptimizationRoot](#2-global-setting-via-optimizationroot)
- [3. Per-Component Override](#3-per-component-override)
- [Priority Order](#priority-order)
+ - [`useLiveUpdates`](#useliveupdates)
- [React Native-Specific Defaults](#react-native-specific-defaults)
- [Persistence Behavior](#persistence-behavior)
- [Offline Support](#offline-support)
@@ -97,13 +102,16 @@ const optimization = await ContentfulOptimization.create({
## Configuration
+The SDK communicates with two APIs: the **Experience API** (for personalization and variant
+resolution) and the **Insights API** (for analytics event ingestion).
+
### Top-level Configuration Options
| Option | Required? | Default | Description |
| ------------------- | --------- | ----------------------------- | ------------------------------------------------------------ |
| `allowedEventTypes` | No | `['identify', 'screen']` | Allow-listed event types permitted when consent is not set |
| `analytics` | No | See "Analytics Options" | Configuration specific to the Analytics/Insights API |
-| `clientId` | Yes | N/A | The Optimization API key |
+| `clientId` | Yes | N/A | The Optimization client identifier |
| `defaults` | No | `undefined` | Set of default state values applied on initialization |
| `environment` | No | `'main'` | The environment identifier |
| `eventBuilder` | No | See "Event Builder Options" | Event builder configuration (channel/library metadata, etc.) |
@@ -131,7 +139,7 @@ Configuration method signatures:
### Event Builder Options
Event builder options should only be supplied when building an SDK on top of the Optimization React
-Native SDK or any of its descendent SDKs.
+Native SDK or any of its descendant SDKs.
| Option | Required? | Default | Description |
| ------------------- | --------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
@@ -203,11 +211,10 @@ Configuration method signatures:
> Call `ContentfulOptimization.create(...)` once per app runtime and share the returned instance. In
> tests or hot-reload workflows, call `destroy()` before creating a replacement instance.
-## Component Tracking
+## Entry Tracking
-**Important:** When we refer to "component tracking," we're talking about tracking **Contentful
-entry components** (content entries in your CMS), NOT React Native UI components. The term
-"component" comes from Contentful's terminology for personalized content entries.
+Entry tracking refers to tracking **Contentful entries** (content entries in your CMS) for analytics
+purposes — views, taps, and variant resolution — not React Native UI components.
### `
`
@@ -217,7 +224,7 @@ automatically:
- Detects whether the entry is personalized (has `nt_experiences` field)
- Resolves the correct variant for personalized entries based on user profile
- Passes non-personalized entries through unchanged
-- Tracks component views when visibility and time thresholds are met
+- Tracks entry views when visibility and time thresholds are met
- Tracks taps when enabled
`children` accepts either a **render prop** `(resolvedEntry) => ReactNode` for accessing the
@@ -244,11 +251,11 @@ The component tracks when an entry:
- Is at least **80% visible** in the viewport (configurable via `threshold` prop)
- Has been viewed for **2000ms** (2 seconds, configurable via `viewTimeMs` prop)
-### ScrollView vs Non-ScrollView Usage
+### With vs Without OptimizationScrollProvider
The tracking component works in two modes:
-#### Inside ScrollView (Recommended for Scrollable Content)
+#### With OptimizationScrollProvider (Recommended for Scrollable Content)
When used inside a `
`, tracking uses the actual scroll position and
viewport dimensions:
@@ -270,7 +277,7 @@ viewport dimensions:
- Works for content that appears below the fold
- Triggers when component scrolls into view
-#### Outside ScrollView (For Non-Scrollable Content)
+#### Without OptimizationScrollProvider (For Non-Scrollable Content)
When used without ``, tracking uses screen dimensions instead:
@@ -317,7 +324,8 @@ is ideal for:
**Key Features:**
-- Tracks only once per component instance
+- The initial view event fires once per component mount; periodic duration updates continue while
+ visible
- Works with or without `OptimizationScrollProvider` (automatically adapts)
- Default: 80% visible for 2000ms (both configurable)
- Tracking fires even if user never scrolls (checks on initial layout)
@@ -325,7 +333,8 @@ is ideal for:
### Manual Analytics Tracking
-You can also manually track events using the analytics API:
+For cases outside the `` component pattern — such as custom screens or
+non-Contentful content — you can manually track events using the analytics API:
```typescript
import { useOptimization } from '@contentful/optimization-react-native'
@@ -345,6 +354,142 @@ function MyComponent() {
}
```
+### `useInteractionTracking`
+
+Returns the resolved interaction tracking configuration from the nearest
+`InteractionTrackingProvider` (set up by `OptimizationRoot`). Use this to check whether view or tap
+tracking is globally enabled:
+
+```tsx
+import { useInteractionTracking } from '@contentful/optimization-react-native'
+
+function DebugOverlay() {
+ const { views, taps } = useInteractionTracking()
+ return (
+
+ Views: {String(views)}, Taps: {String(taps)}
+
+ )
+}
+```
+
+### `useTapTracking`
+
+Low-level hook that detects taps on a View via raw touch events and emits `component_click`
+analytics events. `` uses this internally, but you can use it directly for custom
+tracking layouts:
+
+```tsx
+import { useTapTracking } from '@contentful/optimization-react-native'
+
+function TrackedEntry({ entry }: { entry: Entry }) {
+ const { onTouchStart, onTouchEnd } = useTapTracking({
+ entry,
+ enabled: true,
+ })
+
+ return (
+
+ {entry.fields.title}
+
+ )
+}
+```
+
+## Screen Tracking
+
+### `useScreenTracking`
+
+Hook for tracking screen views. By default, tracks the screen automatically when the component
+mounts. Set `trackOnMount: false` to disable automatic tracking and use the returned `trackScreen`
+function for manual control.
+
+```tsx
+import { useScreenTracking } from '@contentful/optimization-react-native'
+
+// Automatic tracking on mount (default)
+function HomeScreen() {
+ useScreenTracking({ name: 'Home' })
+ return ...
+}
+
+// Manual tracking
+function DetailsScreen() {
+ const { trackScreen } = useScreenTracking({
+ name: 'Details',
+ trackOnMount: false,
+ })
+
+ useEffect(() => {
+ if (dataLoaded) {
+ trackScreen()
+ }
+ }, [dataLoaded])
+
+ return ...
+}
+```
+
+### `useScreenTrackingCallback`
+
+Returns a stable callback to track screen views with dynamic names. Use this when screen names are
+not known at render time (e.g., from navigation state):
+
+```tsx
+import { useScreenTrackingCallback } from '@contentful/optimization-react-native'
+
+function DynamicScreen({ screenName }: { screenName: string }) {
+ const trackScreenView = useScreenTrackingCallback()
+
+ useEffect(() => {
+ trackScreenView(screenName, { source: 'deep-link' })
+ }, [screenName])
+
+ return ...
+}
+```
+
+### `OptimizationNavigationContainer`
+
+Wraps React Navigation's `NavigationContainer` to automatically track screen views when the active
+route changes. Uses a render prop pattern so navigation props are spread onto the
+`NavigationContainer` without requiring a direct dependency on `@react-navigation/native`:
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native'
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+import {
+ OptimizationNavigationContainer,
+ OptimizationProvider,
+} from '@contentful/optimization-react-native'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+ return (
+
+
+ {(navigationProps) => (
+
+
+
+
+
+
+ )}
+
+
+ )
+}
+```
+
+| Prop | Required? | Default | Description |
+| --------------- | --------- | ------- | ----------------------------------------------------------------- |
+| `children` | Yes | N/A | Render prop receiving `ref`, `onReady`, and `onStateChange` |
+| `onStateChange` | No | N/A | Called when navigation state changes, after screen tracking fires |
+| `onReady` | No | N/A | Called when navigation container is ready, after initial tracking |
+| `includeParams` | No | `false` | Whether to include route params in screen event properties |
+
## OptimizationRoot
`OptimizationRoot` is the recommended way to set up the SDK. It combines `OptimizationProvider` with
@@ -375,6 +520,23 @@ function App() {
}
```
+`OptimizationRoot` also accepts a `trackEntryInteraction` prop to control global view and tap
+tracking for all `` components. By default, view tracking is enabled and tap
+tracking is disabled:
+
+```tsx
+
+ {/* All OptimizedEntry components will track both views and taps */}
+
+```
+
+Individual `` components can override the global setting via their `trackViews`
+and `trackTaps` props.
+
### Preview Panel
When `previewPanel.enabled` is `true`, a floating action button appears that opens the preview
@@ -494,6 +656,22 @@ The live updates setting is determined for a particular `` comp
| Closed | `true` | `false` | Live updates OFF |
| Closed | `false` | `undefined` | Live updates OFF |
+### `useLiveUpdates`
+
+The `useLiveUpdates` hook provides read access to the live updates state from the nearest
+`LiveUpdatesProvider`. Use it to check the current global live updates setting or preview panel
+visibility:
+
+```tsx
+import { useLiveUpdates } from '@contentful/optimization-react-native'
+
+function MyComponent() {
+ const liveUpdates = useLiveUpdates()
+ const isLive = liveUpdates?.globalLiveUpdates ?? false
+ return {isLive ? 'Live' : 'Locked'}
+}
+```
+
## React Native-Specific Defaults
The SDK automatically configures:
diff --git a/packages/react-native-sdk/dev/README.md b/packages/react-native-sdk/dev/README.md
index 3e2b497d..718b3423 100644
--- a/packages/react-native-sdk/dev/README.md
+++ b/packages/react-native-sdk/dev/README.md
@@ -207,10 +207,10 @@ The app connects to the mock server by default. Configuration is in `env.config.
## What This App Tests
-1. **SDK Initialization** - Verifies the Optimization SDK initializes correctly
+1. **SDK Initialization** - Verifies the Optimization React Native SDK initializes correctly
2. **Profile Management** - Tests profile creation and updates
3. **Merge Tag Resolution** - Demonstrates merge tag value resolution
-4. **Component Tracking** - Tests viewport-based analytics tracking
+4. **Entry Tracking** - Tests viewport-based analytics tracking
5. **Personalization** - Shows personalized content rendering
## Available Scripts
diff --git a/packages/react-native-sdk/src/ContentfulOptimization.ts b/packages/react-native-sdk/src/ContentfulOptimization.ts
index 92a6261a..e8e1147a 100644
--- a/packages/react-native-sdk/src/ContentfulOptimization.ts
+++ b/packages/react-native-sdk/src/ContentfulOptimization.ts
@@ -56,7 +56,7 @@ async function mergeConfig({
let activeOptimizationInstance: ContentfulOptimization | undefined = undefined
/**
- * Main entry point for the Contentful ContentfulOptimization React Native SDK.
+ * Main entry point for the Contentful Optimization React Native SDK.
*
* Extends {@link CoreStateful} with React Native-specific behavior including
* AsyncStorage persistence, network connectivity detection via
diff --git a/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx b/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx
index 3db63172..31768779 100644
--- a/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx
+++ b/packages/react-native-sdk/src/components/OptimizationNavigationContainer.tsx
@@ -60,7 +60,7 @@ export interface OptimizationNavigationContainerProps {
/**
* Whether to include route params in the screen event properties.
*
- * @defaultValue false
+ * @defaultValue `false`
*/
includeParams?: boolean
}
@@ -87,7 +87,7 @@ export interface OptimizationNavigationContainerProps {
*
* function App() {
* return (
- *
+ *
*
* {(navigationProps) => (
*
diff --git a/packages/react-native-sdk/src/components/OptimizationProvider.tsx b/packages/react-native-sdk/src/components/OptimizationProvider.tsx
index 65766fae..66b038a8 100644
--- a/packages/react-native-sdk/src/components/OptimizationProvider.tsx
+++ b/packages/react-native-sdk/src/components/OptimizationProvider.tsx
@@ -15,13 +15,13 @@ const logger = createScopedLogger('RN:Provider')
*/
export interface OptimizationProviderProps extends OptimizationConfig {
/**
- * Children components that will have access to the ContentfulOptimization instance.
+ * Children components that will have access to the {@link ContentfulOptimization} instance.
*/
children?: ReactNode
}
/**
- * Provides the ContentfulOptimization instance to all child components via React Context.
+ * Provides the {@link ContentfulOptimization} instance to all child components via React Context.
*
* Handles SDK initialization, loading state, and cleanup internally.
* Children are not rendered until the SDK is ready (loading gate).
diff --git a/packages/react-native-sdk/src/components/OptimizationRoot.tsx b/packages/react-native-sdk/src/components/OptimizationRoot.tsx
index b289d1a5..a9a40b2c 100644
--- a/packages/react-native-sdk/src/components/OptimizationRoot.tsx
+++ b/packages/react-native-sdk/src/components/OptimizationRoot.tsx
@@ -49,7 +49,7 @@ export interface OptimizationRootProps extends CoreStatefulConfig {
* @example
* ```tsx
*
*
@@ -59,7 +59,7 @@ export interface OptimizationRootProps extends CoreStatefulConfig {
trackEntryInteraction?: TrackEntryInteractionOptions
/**
- * Children components that will have access to the Optimization instance.
+ * Children components that will have access to the {@link ContentfulOptimization} instance.
*/
children: ReactNode
}
@@ -82,7 +82,7 @@ export interface OptimizationRootProps extends CoreStatefulConfig {
* @example With interaction tracking
* ```tsx
*
*
diff --git a/packages/react-native-sdk/src/components/OptimizedEntry.tsx b/packages/react-native-sdk/src/components/OptimizedEntry.tsx
index 48f47f4a..a261132d 100644
--- a/packages/react-native-sdk/src/components/OptimizedEntry.tsx
+++ b/packages/react-native-sdk/src/components/OptimizedEntry.tsx
@@ -81,7 +81,7 @@ export interface OptimizedEntryProps {
* Interval (in milliseconds) between periodic view duration update events
* after the initial event has fired.
*
- * @defaultValue 5000
+ * @defaultValue `5000`
*/
viewDurationUpdateIntervalMs?: number
@@ -161,10 +161,10 @@ function resolveTapsEnabled(
* @returns A wrapper View with interaction tracking attached
*
* @remarks
- * "Component tracking" refers to tracking Contentful entry components (content entries),
+ * "Tracking" refers to tracking Contentful content entries,
* not React Native UI components. Must be used within an {@link OptimizationProvider}.
- * Works with or without a {@link OptimizationScrollProvider} — when outside a OptimizationScrollProvider,
- * screen dimensions are used instead.
+ * Works with or without an {@link OptimizationScrollProvider} — when outside an
+ * {@link OptimizationScrollProvider}, screen dimensions are used instead.
*
* By default the component locks to the first variant it receives to prevent UI
* flashing. Set `liveUpdates` to `true` or open the preview panel to enable
@@ -203,6 +203,7 @@ function resolveTapsEnabled(
* ```
*
* @see {@link OptimizationRoot} for configuring global interaction tracking
+ * @see {@link useLiveUpdates} for reading live update state programmatically
*
* @public
*/
diff --git a/packages/react-native-sdk/src/context/OptimizationContext.tsx b/packages/react-native-sdk/src/context/OptimizationContext.tsx
index a5268818..80766abb 100644
--- a/packages/react-native-sdk/src/context/OptimizationContext.tsx
+++ b/packages/react-native-sdk/src/context/OptimizationContext.tsx
@@ -11,16 +11,16 @@ interface OptimizationContextValue {
}
/**
- * React Context that holds the ContentfulOptimization instance.
+ * React Context that holds the {@link ContentfulOptimization} instance.
*
* @internal
*/
const OptimizationContext = createContext(null)
/**
- * Returns the ContentfulOptimization instance from the nearest {@link OptimizationProvider}.
+ * Returns the {@link ContentfulOptimization} instance from the nearest {@link OptimizationProvider}.
*
- * @returns The current ContentfulOptimization instance
+ * @returns The current {@link ContentfulOptimization} instance
*
* @throws Error if called outside of an {@link OptimizationProvider}
* @throws Error if the SDK is still initializing
@@ -48,8 +48,8 @@ export function useOptimization(): ContentfulOptimization {
if (!context) {
throw new Error(
- 'useOptimization must be used within an OptimizationProvider. ' +
- 'Make sure to wrap your component tree with .',
+ 'useOptimization must be used within an OptimizationProvider or OptimizationRoot. ' +
+ 'Make sure to wrap your component tree with or .',
)
}
diff --git a/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx b/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx
index c992411e..9404418b 100644
--- a/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx
+++ b/packages/react-native-sdk/src/context/OptimizationScrollContext.tsx
@@ -25,7 +25,10 @@ const SCROLL_LOG_THRESHOLD = 50
/**
* Returns the current scroll position and viewport height from the nearest {@link OptimizationScrollProvider}.
*
- * @returns The scroll context value, or `null` if not within a {@link OptimizationScrollProvider}
+ * @returns The scroll context value, or `null` if not within an {@link OptimizationScrollProvider}
+ *
+ * @remarks
+ * Useful for building custom scroll-position-dependent behaviors alongside Optimization tracking.
*
* @example
* ```tsx
@@ -59,9 +62,9 @@ export interface OptimizationScrollProviderProps extends ScrollViewProps {
* @returns A `ScrollView` wrapped in a scroll context provider
*
* @remarks
- * When {@link OptimizedEntry} components are placed inside a
- * `OptimizationScrollProvider`, they use the actual scroll position for visibility calculations.
- * Without a `OptimizationScrollProvider`, they fall back to screen dimensions.
+ * When {@link OptimizedEntry} components are placed inside an
+ * {@link OptimizationScrollProvider}, they use the actual scroll position for visibility calculations.
+ * Without an {@link OptimizationScrollProvider}, they fall back to screen dimensions.
*
* @example
* ```tsx
diff --git a/packages/react-native-sdk/src/handlers/createAppStateChangeListener.ts b/packages/react-native-sdk/src/handlers/createAppStateChangeListener.ts
index b1acb620..5e51479b 100644
--- a/packages/react-native-sdk/src/handlers/createAppStateChangeListener.ts
+++ b/packages/react-native-sdk/src/handlers/createAppStateChangeListener.ts
@@ -18,7 +18,7 @@ type Callback = () => Promise | void
* May return a promise.
* @returns A function that removes the registered event listener when called.
*
- * @public
+ * @internal
* @remarks
* - On iOS, `inactive` state occurs during transitions (e.g., opening control center).
* - On Android, `inactive` state is not commonly used.
diff --git a/packages/react-native-sdk/src/handlers/createOnlineChangeListener.ts b/packages/react-native-sdk/src/handlers/createOnlineChangeListener.ts
index eb07dc2f..a3a8d5a0 100644
--- a/packages/react-native-sdk/src/handlers/createOnlineChangeListener.ts
+++ b/packages/react-native-sdk/src/handlers/createOnlineChangeListener.ts
@@ -53,7 +53,7 @@ const loadNetInfoModule = async (): Promise => {
* May return a promise.
* @returns A function that removes the registered event listener when called.
*
- * @public
+ * @internal
* @remarks
* - Requires `@react-native-community/netinfo` to be installed as a peer dependency.
* - If NetInfo is not installed, a warning is logged and a no-op cleanup function is returned.
diff --git a/packages/react-native-sdk/src/hooks/useScreenTracking.ts b/packages/react-native-sdk/src/hooks/useScreenTracking.ts
index c057fdf6..e54066b5 100644
--- a/packages/react-native-sdk/src/hooks/useScreenTracking.ts
+++ b/packages/react-native-sdk/src/hooks/useScreenTracking.ts
@@ -24,7 +24,7 @@ export interface UseScreenTrackingOptions {
/**
* Whether to automatically track the screen on mount.
*
- * @defaultValue true
+ * @defaultValue `true`
*/
trackOnMount?: boolean
}
diff --git a/packages/react-native-sdk/src/hooks/useTapTracking.ts b/packages/react-native-sdk/src/hooks/useTapTracking.ts
index ffd268ea..68032def 100644
--- a/packages/react-native-sdk/src/hooks/useTapTracking.ts
+++ b/packages/react-native-sdk/src/hooks/useTapTracking.ts
@@ -59,8 +59,8 @@ export interface UseTapTrackingReturn {
}
/**
- * Detects taps on a View via raw touch events and emits `component_click`
- * analytics events through the existing Insights pipeline.
+ * Detects taps on a View and emits analytics events (internally named `component_click`
+ * for cross-platform consistency with the web SDK).
*
* @param options - Tracking options including the entry, personalization data, and enabled state.
* @returns {@link UseTapTrackingReturn} with touch handlers to spread onto a View,
diff --git a/packages/react-native-sdk/src/hooks/useViewportTracking.ts b/packages/react-native-sdk/src/hooks/useViewportTracking.ts
index 4ab25ef4..0c5c157c 100644
--- a/packages/react-native-sdk/src/hooks/useViewportTracking.ts
+++ b/packages/react-native-sdk/src/hooks/useViewportTracking.ts
@@ -27,14 +27,14 @@ export interface UseViewportTrackingOptions {
/**
* Minimum visibility ratio (0.0 - 1.0) required to consider the component "visible".
*
- * @defaultValue 0.8
+ * @defaultValue `0.8`
*/
threshold?: number
/**
* Minimum accumulated visible time (in milliseconds) before the first tracking event fires.
*
- * @defaultValue 2000
+ * @defaultValue `2000`
*/
viewTimeMs?: number
@@ -51,7 +51,7 @@ export interface UseViewportTrackingOptions {
* Interval (in milliseconds) between periodic view duration update events
* after the initial event has fired.
*
- * @defaultValue 5000
+ * @defaultValue `5000`
*/
viewDurationUpdateIntervalMs?: number
}
@@ -186,7 +186,7 @@ function getRemainingMsUntilNextFire(
}
/**
- * Tracks whether a component is visible in the viewport and fires component view
+ * Tracks whether a component is visible in the viewport and fires entry view
* events with accumulated duration tracking.
*
* The hook implements a three-phase event lifecycle per visibility cycle:
diff --git a/packages/react-native-sdk/src/index.ts b/packages/react-native-sdk/src/index.ts
index 93e81e0b..f8d4430d 100644
--- a/packages/react-native-sdk/src/index.ts
+++ b/packages/react-native-sdk/src/index.ts
@@ -1,5 +1,5 @@
/**
- * Contentful ContentfulOptimization React Native SDK.
+ * Contentful Optimization React Native SDK.
*
* @remarks
* Implements React Native-specific functionality on top of the ContentfulOptimization Core Library.
@@ -15,9 +15,10 @@ import './polyfills/crypto'
import type { CoreStatefulConfig } from '@contentful/optimization-core'
/**
- * SDK initialization config passed as props to {@link OptimizationProvider} and {@link OptimizationRoot}.
+ * Configuration options for initializing the Optimization React Native SDK.
*
- * Alias of {@link CoreStatefulConfig}. Only `clientId` is required.
+ * Passed as props to {@link OptimizationProvider} and {@link OptimizationRoot}.
+ * Only `clientId` is required. See the README for full configuration reference.
*
* @public
*/
diff --git a/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx b/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx
index 41d459c5..e4c323b0 100644
--- a/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx
+++ b/packages/react-native-sdk/src/preview/components/PreviewPanel.tsx
@@ -63,7 +63,7 @@ function PreviewPanelHeader({ consent }: { consent: boolean | undefined }): Reac
*
* function App() {
* return (
- *
+ *
*
*
*
diff --git a/packages/react-native-sdk/src/preview/hooks/useDefinitions.ts b/packages/react-native-sdk/src/preview/hooks/useDefinitions.ts
index 674e80b7..e7604806 100644
--- a/packages/react-native-sdk/src/preview/hooks/useDefinitions.ts
+++ b/packages/react-native-sdk/src/preview/hooks/useDefinitions.ts
@@ -13,8 +13,8 @@ interface UseDefinitionsResult {
* Creates memoized audience/experience definitions and name lookup maps
* from raw Contentful entries.
*
- * @param audienceEntries - Raw Contentful `nt_audience` entries
- * @param experienceEntries - Raw Contentful `nt_experience` entries
+ * @param audienceEntries - Raw Contentful `nt_audience` entries (Contentful content type IDs created by the Optimization platform)
+ * @param experienceEntries - Raw Contentful `nt_experience` entries (Contentful content type IDs created by the Optimization platform)
* @returns Definitions arrays and name maps
*
* @internal
diff --git a/packages/react-native-sdk/src/preview/types.ts b/packages/react-native-sdk/src/preview/types.ts
index d34e430b..6462f253 100644
--- a/packages/react-native-sdk/src/preview/types.ts
+++ b/packages/react-native-sdk/src/preview/types.ts
@@ -8,7 +8,7 @@ import type { StyleProp, ViewStyle } from 'react-native'
/**
* Audience definition from the optimization platform.
*
- * @public
+ * @internal
*/
export interface AudienceDefinition {
/** Unique audience identifier */
@@ -22,7 +22,7 @@ export interface AudienceDefinition {
/**
* Variant distribution configuration for an experience.
*
- * @public
+ * @internal
*/
export interface VariantDistribution {
/** Variant index (0 = baseline) */
@@ -42,7 +42,7 @@ export interface VariantDistribution {
/**
* Simplified Contentful entry structure for mapping entries to preview panel definitions.
*
- * @public
+ * @internal
*/
export interface ContentfulEntry {
sys: {
@@ -59,7 +59,7 @@ export interface ContentfulEntry {
/**
* Entry collection response from the Contentful client, including pagination metadata.
*
- * @public
+ * @internal
*/
export interface ContentfulEntryCollection {
items: ContentfulEntry[]
@@ -85,7 +85,7 @@ export interface ContentfulClient {
/**
* Experience definition representing a personalization or experiment configuration.
*
- * @public
+ * @internal
*/
export interface ExperienceDefinition {
/** Unique experience identifier */
@@ -104,14 +104,14 @@ export interface ExperienceDefinition {
* Three-state override value for audiences: `'on'` forces active, `'off'` forces
* inactive, `'default'` defers to the SDK evaluation.
*
- * @public
+ * @internal
*/
export type AudienceOverrideState = 'on' | 'off' | 'default'
/**
* Combined audience data with associated experiences, used for audience-grouped display.
*
- * @public
+ * @internal
*/
export interface AudienceWithExperiences {
/** Audience definition */
@@ -129,7 +129,7 @@ export interface AudienceWithExperiences {
/**
* Preview data containing all audience and experience definitions.
*
- * @public
+ * @internal
*/
export interface PreviewData {
/** All available audience definitions */
@@ -145,7 +145,7 @@ export interface PreviewData {
/**
* Tracks a manual audience activation or deactivation override.
*
- * @public
+ * @internal
*/
export interface AudienceOverride {
/** Audience ID being overridden */
@@ -161,7 +161,7 @@ export interface AudienceOverride {
/**
* Tracks a manual variant selection override.
*
- * @public
+ * @internal
*/
export interface PersonalizationOverride {
/** Experience ID being overridden */
@@ -173,7 +173,7 @@ export interface PersonalizationOverride {
/**
* Combined override state managed by the preview panel.
*
- * @public
+ * @internal
*/
export interface OverrideState {
/** Map of audience ID to override */
@@ -185,7 +185,7 @@ export interface OverrideState {
/**
* Preview state derived from SDK signals.
*
- * @public
+ * @internal
*/
export interface PreviewState {
/** Current profile from SDK */
@@ -201,7 +201,7 @@ export interface PreviewState {
/**
* Actions available in the preview panel for overriding audiences and personalizations.
*
- * @public
+ * @internal
*/
export interface PreviewActions {
/** Activate an audience override and set variant index to 1 for associated experiences */
@@ -232,7 +232,8 @@ export interface PreviewPanelProps {
onVisibilityChange?: (isVisible: boolean) => void
/**
* Contentful client instance used to fetch audience and experience entries.
- * The panel will automatically fetch nt_audience and nt_experience content types.
+ * The panel will automatically fetch `nt_audience` and `nt_experience` content types
+ * (Contentful content type IDs created by the Optimization platform).
*/
contentfulClient: ContentfulClient
}
@@ -252,7 +253,7 @@ export interface PreviewPanelOverlayProps extends Omit