--- schema_version: "1" id: edb1c376eec8f22cc786af6db770e78d6053966c98a0a6d7f72aa41c6d8da3a5 title: React Native SDK Limitations collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/genai/agentforce-mobile-sdk/guides/react-native/agentforce-mobile-sdk-react-native-limitations.md canonical_url: https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-limitations.html source_site: developer.salesforce.com content_type: documentation content_hash: b96ce348dc286732ac8dc89f33f5f644f2399804346e1c5d27a0d64de26da702 products: - Agentforce Mobile SDK - Agentforce and Einstein Generative AI --- # React Native SDK Limitations Understand the limitations and considerations when using the React Native bridge compared to the native iOS and Android SDKs. ## Overview The React Native Agentforce SDK is a **bridge** to the native iOS and Android SDKs, not a full reimplementation. This architecture provides cross-platform convenience but means some features available in the native SDKs aren't exposed or work differently in React Native. ## Feature Comparison | Feature | Native iOS/Android | React Native Bridge | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | Service Agent | Full support | Full support | | Employee Agent | Full support | Full support | | Prebuilt Conversation UI | Full support | Full support | | Headless/Custom UI | Full support | Not available | | Theming/Branding | Full customization | Supported via `appearance` API (colors, icons, display names, theme mode, typography) | | Analytics Instrumentation | Full support | Not exposed | | Typography/Fonts | Full customization | Supported (generic fonts, bundled fonts, sizes, weights) | | Voice Input | Full support | Supported (feature flag, limited customization via `voiceOptions`) | | Hidden Prechat Fields | Full support | Full support | | Custom Lightning Types — native overrides (`AFMobileCustom/`) | Full support | Supported via View Provider delegate (`setViewProviderDelegate()`); `enableCustomViewProvider` is advisory | | Custom Lightning Types — LWC | Supported in other clients (see [Custom Lightning Types on Mobile](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/agent-sdk-mobile-custom-lightning-types.md)) | Not yet supported | ## No Headless Mode The native iOS and Android SDKs support a "headless" mode where you can build a completely custom conversation UI while using the SDK for conversation management. The React Native bridge doesn't expose this capability. **What this means**: You must use the SDK's prebuilt conversation UI. You can't create a fully custom chat interface in React Native while using the Agentforce SDK for the backend. **Workaround**: Use the View Provider delegate to customize individual output components within the prebuilt UI. See [Delegates](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-delegates.md) for details. ## Theming and Branding via the Appearance API The React Native bridge exposes an `appearance` API for colors, icons, display names, theme mode, and typography (fonts, sizes, weights) on both iOS and Android. **What this means**: You can theme and brand the conversation UI from React Native code without writing native Swift or Kotlin. Advanced native theming capabilities beyond what `appearance` exposes still require the View Provider delegate or native code. **Workaround**: For anything not covered by `appearance`, use the View Provider delegate to override specific SDK output views with your own React Native components. ## No Analytics Instrumentation The native SDKs expose an analytics/instrumentation API for tracking events and markers. The React Native bridge doesn't expose this functionality. **What this means**: You can't receive or track SDK analytics events from your React Native code. **Workaround**: Use the Logger delegate to capture log messages, which may include some operational information useful for debugging. ## Voice Input Voice input is controlled by a feature flag (`enableVoice`) but there's no React Native-specific voice API. The native SDK handles voice input internally when enabled. Voice is supported for both **Employee Agents** and **Service Agents**. **What this means**: You can enable voice input for both agent types and adjust some behavior via `voiceOptions` (and, on iOS, `voiceCloseBehavior`), but you can't render a custom voice UI or handle voice events directly in React Native. The native SDK renders and manages the voice UI. The native SDK renders and drives the voice UI, so several voice behaviors that the native iOS and Android SDKs expose aren't configurable from React Native: - **No direct launch into voice mode.** `launchConversation()` always opens the chat interface first. There's no React Native option to open the voice screen by default. - **No configurable close behavior.** Closing the voice screen returns the user to chat. You can't configure the bridge to close the entire Agentforce window when voice is closed. - **No default closed-caption preference.** Closed captions default to off, and the user activates them manually. Feature flags don't change the user's default caption preference, and there's no React Native API to turn captions on by default. - **No voice UI theming.** You can't customize the voice experience from React Native—including the closed-caption text color, the voice aura color, or a custom centered voice icon. These native customizations aren't exposed through the bridge. **Workaround**: If any of these behaviors are required, use the native iOS or Android SDK, where the underlying voice APIs are available. For setup instructions and how closed captions affect agent responses, see [Set Up Agentforce Voice](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-voice.md). ## Custom Lightning Types: LWC and React Web UI Custom Lightning Types (**CLTs**) can be rendered in React Native apps that integrate the Agentforce React Native SDK when you use native-style overrides in metadata — definitions prefixed with `AFMobileCustom/…` — and wire them through the View Provider delegate. Call `setViewProviderDelegate()` to register your provider directly; `enableCustomViewProvider` is advisory metadata, not a hard requirement for wiring the delegate. The bridge talks to the native SDKs. Your React Native components replace the native output for those definitions. See [Delegates](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-delegates.md) and [Custom Lightning Types on Mobile with the Agentforce Mobile SDK](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/agent-sdk-mobile-custom-lightning-types.md). **What is not supported yet in React Native**: Using Lightning web components (LWC) as the CLT user interface inside the bridge, and using React web components inside CLT. **What this means**: Plan on native-override metadata and React Native View Provider mappings for CLTs in RN apps. Do not assume existing LWC-based CLT renderers or React web component CLT UIs work in the React Native SDK until support is announced. ## Platform-Specific Behavior Differences Some behaviors differ between iOS and Android implementations. ### setEmployeeAgentId() Side Effects | Platform | Behavior | | -------- | -------------------------------------------------------------------------------------------- | | iOS | Calling with a different agent ID triggers conversation close and client cleanup immediately | | Android | Only persists the value; call `configure()` with the new agent ID to apply it | ### Log Levels | Platform | Levels Emitted | | -------- | -------------------------------- | | iOS | `error`, `warn`, `info`, `debug` | | Android | `error`, `warn`, `info` | iOS emits the `debug` level; Android doesn't. ### enableCustomViewProvider Persistence | Platform | Behavior | | -------- | ------------------------------ | | iOS | Persisted in UserDefaults | | Android | Persisted in SharedPreferences | ## Thread Safety Notes For advanced debugging, the bridge implementations handle thread safety differently: - **Android**: Uses a `@Volatile` annotation for thread-safe reads of `BridgeHiddenPreChat.fields`. - **iOS**: Uses `listenerLock` (NSLock) for thread-safe event emission. The `_hasListeners` flag is protected by this lock. This is primarily relevant if you're debugging race conditions or contributing to the bridge. ## Recommendations Choose the right SDK based on your requirements. ### When to Use React Native Bridge - You have an existing React Native app and want to add Agentforce conversations - You need cross-platform development with a single codebase - The prebuilt UI meets your needs with minor customizations via View Provider - You're building a Service Agent integration with standard features ### When to Consider Native SDKs - You need a fully custom conversation UI (headless mode) - You need theming or branding beyond what the `appearance` API exposes - You need analytics instrumentation - You need maximum control over the conversation experience ## See Also - [Configure the SDK](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-integration.md) - [Delegates](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-delegates.md) - [Custom Lightning Types on Mobile with the Agentforce Mobile SDK](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/agent-sdk-mobile-custom-lightning-types.md) - [Troubleshooting](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-troubleshooting.md)