Skip to main content

Quick Start: React Native

Embed the Lovina chat widget in your React Native app using a WebView wrapper with typed events and imperative control via hooks.

Step 1: Install Dependencies​

npm install @lovina/react-native-chat-sdk react-native-webview @react-native-async-storage/async-storage

For iOS, install CocoaPods dependencies:

cd ios && pod install

@react-native-async-storage/async-storage is optional. Without it, session cookies will not persist across app restarts.

Step 2: Add the Chat Widget​

import React from 'react';
import { View } from 'react-native';
import { LovinaChatWidget } from '@lovina/react-native-chat-sdk';

export default function ChatScreen() {
  return (
    <View style={{ flex: 1 }}>
      <LovinaChatWidget
        config={{
          websiteToken: 'your-website-token',
          baseUrl: 'https://chat.lovina.app',
        }}
        onEvent={(event) => {
          console.log('Chat event:', event);
        }}
      />
    </View>
  );
}

That is all you need for a basic integration. The widget handles WebView setup, cookie persistence, and external link handling automatically.

Present chat as a full-screen modal with built-in safe area handling and a close button:

import React, { useState } from 'react';
import { Button, View } from 'react-native';
import { LovinaChatModal } from '@lovina/react-native-chat-sdk';

export default function App() {
  const [showChat, setShowChat] = useState(false);

  return (
    <View style={{ flex: 1, justifyContent: 'center' }}>
      <Button title="Open Chat" onPress={() => setShowChat(true)} />
      <LovinaChatModal
        isVisible={showChat}
        onClose={() => setShowChat(false)}
        config={{
          websiteToken: 'your-website-token',
          baseUrl: 'https://chat.lovina.app',
        }}
        onEvent={(event) => console.log(event)}
      />
    </View>
  );
}

Hook Usage​

The useLovinaChat hook provides imperative control over the widget:

import React from 'react';
import { Button, View } from 'react-native';
import { LovinaChatWidget, useLovinaChat } from '@lovina/react-native-chat-sdk';

export default function ChatScreen() {
  const { ref, open, close, setUser, setLocale, reset } = useLovinaChat();

  return (
    <View style={{ flex: 1 }}>
      <LovinaChatWidget
        ref={ref}
        config={{
          websiteToken: 'your-website-token',
          baseUrl: 'https://chat.lovina.app',
        }}
      />
      <View style={{ flexDirection: 'row', gap: 8, padding: 16 }}>
        <Button title="Open" onPress={open} />
        <Button title="Close" onPress={close} />
        <Button
          title="Set User"
          onPress={() => setUser('user-123', { name: 'Jane', email: 'jane@example.com' })}
        />
        <Button title="Reset" onPress={reset} />
      </View>
    </View>
  );
}

Configuration Options​

ParameterTypeDefaultDescription
websiteTokenstringrequiredWebsite channel token from your Lovina dashboard
baseUrlstringrequiredBase URL of your Lovina instance
localestring"id"Widget locale code (3 languages supported)
colorScheme'light' | 'dark' | 'auto'"auto"Color scheme (follows system when "auto")
userLovinaChatUserundefinedPre-identified user
customColorstringundefinedHex color for header/bubble theming

Pre-identified Users​

<LovinaChatWidget
  config={{
    websiteToken: 'your-token',
    baseUrl: 'https://chat.lovina.app',
    user: {
      identifier: 'user-12345',
      name: 'Jane Doe',
      email: 'jane@example.com',
      phoneNumber: '+6281234567890',
      identifierHash: 'hmac-hash-for-verification',
      customAttributes: {
        plan: 'premium',
        signupDate: '2025-01-15',
      },
    },
  }}
/>

Event Handling​

<LovinaChatWidget
  config={config}
  onEvent={(event) => {
    switch (event.type) {
      case 'loaded':
        console.log('Widget loaded, token:', event.authToken);
        break;
      case 'messageReceived':
        console.log('New message:', event.message);
        break;
      case 'unreadCountChanged':
        updateBadge(event.count);
        break;
      case 'closed':
        console.log('Chat closed, reason:', event.reason);
        break;
      case 'error':
        console.error(`Error [${event.code}]: ${event.message}`);
        break;
    }
  }}
/>
EventFieldsDescription
loadedauthToken?: stringWidget finished loading
messageReceivedmessage: Record<string, unknown>New message received
unreadCountChangedcount: numberUnread count changed
closedreason?: stringChat widget was closed
errorcode: string, message: stringAn error occurred

Imperative Methods​

Available via useLovinaChat hook or a ref:

MethodDescription
setUser(identifier, user)Set or update the identified user
setLocale(locale)Change the widget locale
setColorScheme(mode)Change the color scheme
toggle(show)Open or close the widget
reset()Clear session and reload
reload()Reload the widget

Session Management​

Sessions are persisted automatically via AsyncStorage. To clear a session:

const { reset } = useLovinaChat();
reset(); // Clears stored cookie and reloads

TypeScript​

The SDK exports all types:

import type {
  LovinaChatConfig,
  LovinaChatUser,
  ChatEvent,
  LovinaChatWidgetRef,
} from '@lovina/react-native-chat-sdk';

Requirements​

  • React Native 0.70+
  • React 18.0+
  • react-native-webview 13.0+
  • @react-native-async-storage/async-storage 1.19+ (optional)

Next Steps​