curacel-support-ai-react-native-sdk

React Native host SDK for embedding the Curacel Support AI web widget via WebView, with a native launcher bubble and proper minimize/close behavior.

Installation

npm install curacel-support-ai-react-native-sdk react-native-webview

Peer dependencies:

• react: >= 17
• react-native: >= 0.70
• react-native-webview: >= 13

Basic usage

Mount the widget host once at the root of your app (for example in your root layout or App.tsx):

import React, { useState } from 'react';
import { SupportAiWidgetHost } from 'curacel-support-ai-react-native-sdk';

export default function AppRoot() {
  const [sessionId, setSessionId] = useState<string | null>(null);

  return (
    <>
      {/* Your existing navigation / screens */}

      <SupportAiWidgetHost
        businessSlug="acme-labs"
        theme="light"
        language="auto"
        customer={{
          externalId: 'user-123',
          name: 'Jane Doe',
          email: '[email protected]',
        }}
        contextTags={{
          plan: 'pro',
          source: 'mobile-app',
        }}
        onSessionChange={setSessionId}
      />
    </>
  );
}

This renders:

• A floating launcher bubble (bottom-right by default).
• A single WebView hosting the chat widget in a panel above the bubble.

Props

• businessSlug (required, string): Business slug used by your Curacel Support AI backend, e.g. 'acme-labs'.

• position ('bottom-right' | 'bottom-left', default 'bottom-right'): Where the bubble and panel are anchored.

• theme ('light' | 'dark', default 'light'): Passed as ?theme= to the widget.

• language ('auto' | 'english' | 'arabic', default 'auto'): Passed as ?lang= to the widget.

• customer:

  interface Customer {
    externalId: string;
    name?: string;
    email?: string;
    phone?: string;
  }

  Mapped to customer_external_id, customer_name, customer_email, customer_phone query params.

• contextTags (Record<string, unknown>, optional): Serialized as context_tags={JSON.stringify(contextTags)} and passed to the widget.

• zIndex (number, default 9999): Stacking order above your app UI.

• onSessionChange ((sessionId: string | null) => void, optional): Called whenever the widget reports a session change (via chat-session-update).

Behavior: open / minimize / close

• Open:
  • Tapping the bubble sets isOpen = true and shows the WebView panel.
• Minimize (caret button in the widget header):
  • Widget posts { type: 'chat-widget-minimize' }.
  • Host sets isOpen = false, hides the panel, keeps the WebView and session alive.
  • Tapping the bubble again resumes the same conversation.
• Close (X button in the widget header):
  • Widget posts { type: 'chat-widget-close' }.
  • Host hides the panel, sets isOpen = false, and increments an internal sessionKey so the WebView is remounted on next open.
  • Next open starts a fresh widget session.

Session tracking

The widget (in your web project) emits a chat-session-update message with the current session_id. The host listens and calls onSessionChange(sessionId).

This allows you to:

• Persist the sessionId (for example, with AsyncStorage).
• Link mobile analytics/events to the same session ID the backend uses.

The SDK itself treats sessionId as an opaque string; you decide how to store or use it.