From 1589b762f5148aa51ddf8dcf3be97abb4406e60e Mon Sep 17 00:00:00 2001 From: Alex Freas Date: Tue, 24 Mar 2026 16:02:25 +0000 Subject: [PATCH 1/3] Update READMEs to be consistent with code and terminology --- packages/react-native-sdk/README.md | 216 +++++++++++++++++++++--- packages/react-native-sdk/dev/README.md | 4 +- 2 files changed, 199 insertions(+), 21 deletions(-) diff --git a/packages/react-native-sdk/README.md b/packages/react-native-sdk/README.md index ddea936a..ab2487d4 100644 --- a/packages/react-native-sdk/README.md +++ b/packages/react-native-sdk/README.md @@ -4,9 +4,7 @@

-

Contentful Personalization & Analytics

- -

Optimization React Native SDK

+

Contentful Optimization React Native SDK

@@ -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 From d398e8492068a476148a01f811c4123a0419a65a Mon Sep 17 00:00:00 2001 From: Alex Freas Date: Tue, 24 Mar 2026 16:09:42 +0000 Subject: [PATCH 2/3] Update tsdocs to be consistent with code and terminology --- .../src/ContentfulOptimization.ts | 2 +- .../OptimizationNavigationContainer.tsx | 4 +- .../src/components/OptimizationProvider.tsx | 4 +- .../src/components/OptimizationRoot.tsx | 6 +- .../src/components/OptimizedEntry.tsx | 8 +-- .../src/context/OptimizationContext.tsx | 10 +-- .../src/context/OptimizationScrollContext.tsx | 11 +-- .../handlers/createAppStateChangeListener.ts | 2 +- .../handlers/createOnlineChangeListener.ts | 2 +- .../src/hooks/useTapTracking.ts | 4 +- .../src/hooks/useViewportTracking.ts | 8 +-- packages/react-native-sdk/src/index.ts | 7 +- .../src/preview/components/PreviewPanel.tsx | 2 +- .../src/preview/hooks/useDefinitions.ts | 4 +- .../react-native-sdk/src/preview/types.ts | 67 +++++++++---------- 15 files changed, 71 insertions(+), 70 deletions(-) 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..034bb6b6 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 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/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 Date: Tue, 24 Mar 2026 16:32:59 +0000 Subject: [PATCH 3/3] Fix remaining documentation issues --- packages/react-native-sdk/src/components/OptimizedEntry.tsx | 1 + packages/react-native-sdk/src/hooks/useScreenTracking.ts | 2 +- packages/react-native-sdk/src/preview/utils/contentfulUtils.ts | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/react-native-sdk/src/components/OptimizedEntry.tsx b/packages/react-native-sdk/src/components/OptimizedEntry.tsx index 034bb6b6..a261132d 100644 --- a/packages/react-native-sdk/src/components/OptimizedEntry.tsx +++ b/packages/react-native-sdk/src/components/OptimizedEntry.tsx @@ -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/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/preview/utils/contentfulUtils.ts b/packages/react-native-sdk/src/preview/utils/contentfulUtils.ts index f394d99d..f69ad6ed 100644 --- a/packages/react-native-sdk/src/preview/utils/contentfulUtils.ts +++ b/packages/react-native-sdk/src/preview/utils/contentfulUtils.ts @@ -13,7 +13,7 @@ const BATCH_SIZE = 100 * @param include - Depth of linked entries to resolve * @returns Promise resolving to an array of all entries * - * @defaultValue include is `10` + * @defaultValue `10` * * @public */