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)	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 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.

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 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.

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