@uselingu/react-native-sdk

> Lingu AI Chat SDK for React Native - Hybrid approach with WebView UI and native API


Features

- Full-Page Chat UI - Immersive full-screen chat experience with back navigation
- Message Persistence - Conversations saved locally and restored automatically
- Hybrid Architecture - WebView UI with native API performance
- Easy Integration - Drop-in component for React Native apps
- Session Management - Automatic session handling and heartbeat
- Customizable - Full control over colors, position, and behavior
- TypeScript - Full type safety
- Cross-platform - Works on iOS and Android

---

Installation

``bash
npm install @uselingu/react-native-sdk react-native-webview @react-native-async-storage/async-storage


or


yarn add @uselingu/react-native-sdk react-native-webview @react-native-async-storage/async-storage
`

$3

`bash
cd ios && pod install
`

$3

No additional setup required.

---

Quick Start

`tsx
import React from 'react';
import { View } from 'react-native';
import { LinguChat } from '@uselingu/react-native-sdk';

export default function App() {
return (

{/ Your app content /}

apiKey="your-api-key-here"
position="bottom-right"
theme="light"
primaryColor="#4ade80"
/>

);
}
`

---

Configuration

$3

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| apiKey | string | Yes | - | Your Lingu API key |
| position | ChatPosition | No | bottom-right | FAB position (when closed) |
| theme | ThemeMode | No | light | Theme mode |
| primaryColor | string | No | #4ade80 | Primary color |
| autoOpen | boolean | No | false | Auto-open on mount |
| showBackButton | boolean | No | true | Show back button in header |
| onBackPress | () => void | No | - | Back button callback |
| onSessionStart | (sessionId: string) => void | No | - | Session start callback |
| onSessionEnd | (sessionId: string) => void | No | - | Session end callback |
| onMessageSent | (message: string) => void | No | - | Message sent callback |
| onMessageReceived | (message: string) => void | No | - | Message received callback |

$3

`typescript
type ChatPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
type ThemeMode = 'light' | 'dark' | 'system';
`

$3

`tsx
import { useColorScheme } from 'react-native';

function App() {
const colorScheme = useColorScheme();

return (
apiKey="your-api-key"
theme={colorScheme === 'dark' ? 'dark' : 'light'}
/>
);
}
`

$3

No special permissions required!
- No camera access needed
- No microphone access needed
- Only internet and storage (automatic)

---

Advanced Usage

$3

`tsx
import { useLinguChat } from '@uselingu/react-native-sdk';

function CustomChat() {
const {
messages,
isLoading,
config,
sendMessage,
startSession,
endSession,
isSessionActive,
} = useLinguChat({
apiKey: 'your-api-key-here',
});

// Build your custom UI
return (
// Your custom chat UI
);
}
`

$3

`tsx
apiKey="your-api-key-here"
onSessionStart={(sessionId) => {
console.log('Session started:', sessionId);
}}
onSessionEnd={(sessionId) => {
console.log('Session ended:', sessionId);
}}
onMessageSent={(message) => {
console.log('User sent:', message);
}}
onMessageReceived={(message) => {
console.log('Bot replied:', message);
}}
/>
`

---

API Reference

$3

Main component that renders the chat widget.

$3

Custom hook for managing chat state and operations.

Returns:
- messages: Array of chat messages
- isLoading: Loading state
- config: Widget configuration
- sendMessage(text): Send a message
- startSession(): Start a new session
- endSession(): End the current session
- isSessionActive: Session status

$3

Low-level API client for direct API access.

Methods:
- getConfig(): Get widget configuration
- startSession(): Start a new session
- sendMessage(message, sessionId): Send a message
- endSession(sessionId): End a session
- sendHeartbeat(sessionId): Send heartbeat

---

Examples

$3

`tsx
import { LinguChat } from '@uselingu/react-native-sdk';


`

$3

`tsx
apiKey="your-api-key-here"
position="bottom-left"
theme="dark"
primaryColor="#3b82f6"
/>
`

$3

`tsx
apiKey="your-api-key-here"
onSessionStart={(id) => analytics.track('chat_started', { sessionId: id })}
onMessageSent={(msg) => analytics.track('message_sent', { message: msg })}
/>
`

---

Troubleshooting

$3

1. Check that react-native-webview is installed
2. Verify your API key is correct
3. Check console for error messages

$3

1. Ensure session is active
2. Check network connectivity
3. Verify API endpoint is accessible

$3

1. Make sure the widget container has proper positioning
2. Check z-index conflicts
3. Verify parent View has flex: 1`

---

Requirements

- React Native >= 0.70
- iOS >= 13.0
- Android >= 21 (Android 5.0)

---

License

MIT © Lingu Team

---

Support

- Email: chris@uselingu.app
- Chat: https://uselingu.app
- Docs: https://docs.uselingu.app
---