OCA SDK Mobile Livechat - React Native

React Native bridge for OCA Livechat SDK — integrates Android native livechat widget (Jetpack Compose) into React Native apps via Native Module.

Installation

npm install oca-sdk-mobile-livechat-rn
# or
yarn add oca-sdk-mobile-livechat-rn

Android Setup

1. Firebase Configuration (Required for Push Notifications)

1. Go to Firebase Console
2. Create a project or use existing one
3. Add your Android app with package name matching your appId
4. Download google-services.json
5. Place it in android/app/google-services.json

2. Add Google Services Plugin

Add to android/build.gradle:

dependencies {
    classpath("com.google.gms:google-services:4.4.0")
}

Add to android/app/build.gradle:

apply plugin: "com.google.gms.google-services"

3. Build Android

cd android && ./gradlew assembleRelease

Quick Start

Provider Setup

Wrap your app with LivechatProvider:

import React from 'react';
import { LivechatProvider } from 'oca-sdk-mobile-livechat-rn';

function App() {
  return (
    <LivechatProvider>
      <YourApp />
    </LivechatProvider>
  );
}

Initialize and Use

import { useLivechat } from 'oca-sdk-mobile-livechat-rn';

function ChatButton() {
  const { initialize, openChat, isInitialized } = useLivechat();

  const handleStartChat = async () => {
    // Initialize SDK (call once)
    await initialize({
      appId: 'com.yourapp',
      ocaKey: 'YOUR_OCA_KEY',
      enablePollingFallback: true,
      pollingIntervalMs: 3000,
    });

    // Open chat screen
    await openChat();
  };

  return (
    <Button
      title="Start Chat"
      onPress={handleStartChat}
      disabled={!isInitialized}
    />
  );
}

API Reference

Livechat Class

initialize(config: LivechatConfig): Promise<void>

Initialize the SDK with tenant configuration. Must be called before other methods.

await Livechat.initialize({
  appId: 'com.yourapp',
  ocaKey: 'YOUR_OCA_KEY',
  userAgent: 'Android-SDK/1.0', // optional
  enablePollingFallback: false, // optional
  pollingIntervalMs: 3000, // optional
});

openChat(): Promise<void>

Open the native chat screen (Jetpack Compose Activity).

closeChat(): Promise<void>

Close the chat screen.

sendMessage(text: string, callbackData?: string): Promise<void>

Send a text message to the agent.

endSession(): Promise<void>

End the active chat session.

registerPushToken(token: string): Promise<void>

Register FCM token for push notifications.

unregisterPushToken(): Promise<void>

Unregister push token.

onEvent(listener: (event: LivechatEvent) => void): () => void

Subscribe to SDK events. Returns unsubscribe function.

const unsubscribe = Livechat.onEvent((event) => {
  switch (event.type) {
    case 'onStateChanged':
      console.log('State:', event.state);
      break;
    case 'onMessageReceived':
      console.log('Message:', event.message);
      break;
    case 'onError':
      console.error('Error:', event.message);
      break;
  }
});

// Later: unsubscribe();

removeAllListeners(): void

Remove all event listeners. Call during cleanup.

React Hooks

useLivechat()

Access Livechat context. Must be used within <LivechatProvider>.

const {
  state,           // Current SDK state
  isInitialized,   // Whether SDK is initialized
  error,           // Last error message
  initialize,      // Initialize function
  openChat,        // Open chat function
  closeChat,       // Close chat function
  sendMessage,     // Send message function
  endSession,      // End session function
  registerPushToken,
  unregisterPushToken,
} = useLivechat();

useLivechatEvent(listener)

Subscribe to Livechat events with automatic cleanup.

useLivechatEvent((event) => {
  if (event.type === 'onStateChanged') {
    console.log('State:', event.state);
  }
});

Events

| Event | Payload | Description | |-------|---------|-------------| | onStateChanged | { state: LivechatState } | SDK state changed | | onMessageReceived | { message: string } | New message from agent | | onError | { message: string } | Error occurred |

LivechatState

• idle - SDK not initialized
• loading - SDK is loading
• configuration_loaded - SDK ready to open chat
• chat_active - Chat screen is open
• error - Error state
• unauthorized - Authentication failed

Configuration

LivechatConfig

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | appId | string | Yes | - | Android package name | | ocaKey | string | Yes | - | OCA tenant key | | userAgent | string | No | "Android-SDK/1.0" | Custom user agent | | enablePollingFallback | boolean | No | false | Enable polling fallback | | pollingIntervalMs | number | No | 3000 | Polling interval (ms) |

Troubleshooting

"The package doesn't seem to be linked"

• Rebuild the app after installing the package
• Ensure npx react-native config shows the package
• Check that android/build.gradle includes the library

"No current activity available"

• Ensure the app is in foreground when calling SDK methods
• Check that MainActivity is properly initialized

Push notifications not working

• Verify google-services.json is in android/app/
• Check Firebase project configuration
• Ensure FCM token is registered: Livechat.registerPushToken(token)

License

MIT