Ada Messaging React Native SDK

This package is for React Native teams embedding Ada inside an iOS and Android app through react-native-webview.

Requirements

• react >= 18.0.0
• react-native >= 0.73.0
• react-native-webview >= 13.0.0

This package does not ship a separate Ada native module of its own. Complete the normal react-native-webview native installation steps for your app first, then add this package on top.

Your minimum iOS and Android OS versions follow the versions supported by your React Native app and react-native-webview. The Ada package does not add a separate deployment-target requirement beyond that.

Install

npm install @ada-cx/messaging-react-native react-native-webview

If your app does not already include compatible react and react-native versions, upgrade those first.

Quick Start

import { useRef } from "react";
import {
  AdaMessagingView,
  type AdaMessagingViewHandle,
} from "@ada-cx/messaging-react-native";

export function SupportScreen() {
  const adaRef = useRef<AdaMessagingViewHandle>(null);

  return (
    <AdaMessagingView
      ref={adaRef}
      handle="my-bot"
      language="en"
      metaFields={{ plan: "pro", signedIn: true }}
      onReady={() => {
        adaRef.current?.setSensitiveMetaFields({
          authToken: "secure-session-token",
        });
        adaRef.current?.setDeviceToken("push-token");
      }}
      onEvent={(key, data) => {
        console.log("[Ada]", key, data);
      }}
      style={{ flex: 1 }}
    />
  );
}

Most customer apps only need handle. Leave cluster unset unless Ada tells you your AI agent is hosted on a non-default production region.

Imperative handle methods:

• reset(...)
• setLanguage(...)
• sendMessage(...)
• setMetaFields(...)
• setSensitiveMetaFields(...)
• setDeviceToken(...)
• deleteHistory()

Useful component props:

• handle
• cluster
• language
• greeting
• metaFields
• onReady
• onEvent
• onStateCache
• onError

Upgrade From The Legacy React Native SDK

The safest migration is:

1. replace the old npm package
2. keep the runtime on legacy first
3. use the AdaEmbedView alias only as a temporary bridge if that reduces churn
4. move to AdaMessagingView and the new prop patterns once the package upgrade is stable

Side-by-side mapping

| Legacy | Messaging SDK | |---|---| | @ada-support/react-native-sdk | @ada-cx/messaging-react-native | | AdaEmbedView | AdaMessagingView | | require_relative '../node_modules/@ada-support/react-native-sdk/react_native_pods' in Podfile | remove it | | use_ada!() in Podfile | remove it |

The new package also exports a deprecated AdaEmbedView alias to make the first migration smaller if needed.

Before / after: package

# Before
npm install @ada-support/react-native-sdk

# After
npm install @ada-cx/messaging-react-native

If your old integration added Ada-specific Podfile helpers from @ada-support/react-native-sdk, remove them. The new package relies on the standard React Native and react-native-webview native setup only.

Before / after: imports

Smallest possible migration:

import { AdaEmbedView } from "@ada-cx/messaging-react-native";

Recommended end state:

import { AdaMessagingView } from "@ada-cx/messaging-react-native";

Important Code Changes To Make

1. Most customer apps should only set handle

For the normal production path, keep your setup simple:

<AdaMessagingView handle="my-bot" />

If Ada tells you your bot is hosted on a non-default production region such as Maple, pass the exact cluster value they give you:

<AdaMessagingView
  handle="my-bot"
  cluster="maple"
/>

2. Move sensitive metadata and device tokens to the ref in onReady

This is the preferred pattern in the new package:

onReady={() => {
  adaRef.current?.setSensitiveMetaFields({ authToken: "secure-session-token" });
  adaRef.current?.setDeviceToken(deviceToken);
}}

3. Move event handling to onEvent

For new code, prefer one event callback surface:

onEvent={(key, data) => {
  if (key === "ada:end_conversation") {
    console.log("Conversation ended", data);
  }
}}

Legacy Prop Compatibility

Some older props still work for compatibility, but they are no longer the preferred integration pattern.

| Legacy prop / pattern | Status in the new package | Recommended approach | |---|---|---| | sensitiveMetaFields prop | supported but deprecated | call ref.setSensitiveMetaFields() in onReady | | deviceToken prop | supported but deprecated | call ref.setDeviceToken() in onReady | | eventCallbacks | supported but deprecated | use onEvent | | endConversationCallback | supported but deprecated | use onEvent and check for ada:end_conversation | | thirdPartyCookiesEnabled | still present but deprecated; Android only | normally omit it | | styles | removed from the component API | no direct component replacement | | zdChatterAuthCallback | supported | keep using it when you need Zendesk chat auth |

Upload And Media Permissions

If your bot flow lets users upload files or capture media, make sure your app includes the normal platform permissions required by react-native-webview and the device features you use.

For iOS, that usually means Info.plist usage descriptions such as:

• NSCameraUsageDescription
• NSPhotoLibraryUsageDescription
• NSMicrophoneUsageDescription

For Android, add any permissions your app's upload or capture flow requires in AndroidManifest.xml. If you are migrating from much older legacy guidance, re-check those permissions against your current Android target SDK rather than copying them forward blindly.

State Restoration

If your app wants to restore chat immediately after process recreation, use:

• onStateCache to persist the latest non-sensitive state snapshot
• initialState to inject that snapshot the next time the view mounts

That removes the loading spinner on WebView restart flows.

Release Checklist

Before shipping a migration:

• verify chat renders on both iOS and Android
• confirm onReady fires
• confirm your event logging still receives Ada SDK events
• if you use push notifications, call setDeviceToken() and verify registration
• test background / foreground and process restart behavior