Understand the limitations and considerations when using the React Native bridge compared to the native iOS and Android SDKs.
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 | 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 | Limited (View Provider only) |
| Analytics Instrumentation | Full support | Not exposed |
| Typography/Fonts | Full customization | Not exposed |
| Voice Input | Full support | Employee Agent only (feature flag) |
| Hidden Prechat Fields | Full support | iOS only (Android: stored but not wired) |
Custom Lightning Types — native overrides (AFMobileCustom/) | Full support | Supported via View Provider delegate and enableCustomViewProvider |
| Custom Lightning Types — LWC | Supported in other clients (see Custom Lightning Types on Mobile) | Not yet supported |
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 for details.
The native SDKs provide comprehensive theming APIs for colors, typography, spacing, and component styling. The React Native bridge doesn’t expose these theming APIs.
What this means: You can’t customize the conversation UI’s colors, fonts, or overall visual appearance from React Native code.
Workaround: Use the View Provider delegate to override specific SDK output views with your own React Native components. This lets you control the rendering of message content, but not the overall chrome (navigation bar, input area, etc.).
Agent responses can include interactive UI elements (such as form fields). In React Native, these components are interactive when first rendered. After new chat activity occurs (for example, the user or agent sends another message), previously rendered interactive components become view-only and appear as static snapshots.
What this means: Users must complete interactions with those components before continuing the chat. If the conversation advances, earlier interactive elements aren’t available for further input.
Workaround: Design your UX so users finish form-style tasks before sending another message. If users continue the chat first, prompt them to restart that interaction in a new response.
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 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 currently supported for Employee Agents only — setting enableVoice: true for a Service Agent has no effect.
What this means: You can enable voice input for Employee Agents, but you can’t customize the voice experience or handle voice events directly in React Native. Service Agent voice isn’t available in the React Native bridge yet.
For setup instructions, see Set Up Agentforce Voice.
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 (with enableCustomViewProvider enabled). The bridge talks to the native SDKs. Your React Native components replace the native output for those definitions. See Delegates and Custom Lightning Types on Mobile with the Agentforce Mobile SDK.
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.
On Android, hidden prechat fields are stored but not yet wired to the native SDK delegate.
What this means: If you call registerHiddenPreChatFields() on Android, the fields are stored and retrievable via getHiddenPreChatFields(), but they won’t be sent to the Service Agent during session initialization.
Workaround: If hidden prechat fields are critical to your use case, use iOS or wait for a future bridge update.
Some behaviors differ between iOS and Android implementations.
| Platform | Behavior |
|---|---|
| iOS | Calling with a different agent ID triggers conversation close and client cleanup immediately |
| Android | Only persists the value; changes take effect on next configure() or launchConversation() |
| Platform | Levels Emitted |
|---|---|
| iOS | error, warn, info, debug |
| Android | error, warn, info |
iOS emits the debug level; Android doesn’t.
| Platform | Behavior |
|---|---|
| iOS | Not persisted in UserDefaults; read from config only |
| Android | Persisted in SharedPreferences |
For advanced debugging, the bridge implementations handle thread safety differently:
@Volatile annotations for thread-safe field reads in BridgeHiddenPreChat and BridgeLogger.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.
Choose the right SDK based on your requirements.
j