React Native SDK Limitations
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 | Feature flag only |
| Hidden Prechat Fields | Full support | iOS only (Android: stored but not wired) |
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.).
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.
What this means: You can enable voice input, but you can't customize the voice experience or handle voice events directly in React Native.
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:
- Android: Uses
@Volatileannotations for thread-safe field reads inBridgeHiddenPreChatandBridgeLogger. - iOS: Uses
listenerLock(NSLock) for thread-safe event emission. The_hasListenersflag 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.
- 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
- You need a fully custom conversation UI (headless mode)
- Visual branding and theming are critical requirements
- You need analytics instrumentation
- Hidden prechat fields are required on Android
- You need maximum control over the conversation experience