> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native SDK

> Learn how to integrate Suada with your React Native application

## Overview

The Suada React Native SDK provides a native mobile integration experience for both iOS and Android platforms. Built specifically for React Native, it offers platform-specific components, hooks, and utilities that follow mobile development best practices while maintaining a consistent API across platforms.

## Prerequisites

* React Native 0.70.0 or higher
* React 18.0.0 or higher
* Node.js 16.0.0 or higher
* A Suada API key
* iOS: Xcode 14+ (for iOS development)
* Android: Android Studio (for Android development)

## Installation

Install the Suada React Native SDK and its peer dependencies:

```bash theme={null}
# Using npm
npm install @suada/react-native @suada/core

# Using yarn
yarn add @suada/react-native @suada/core
```

### iOS Setup

Install the iOS dependencies:

```bash theme={null}
cd ios && pod install && cd ..
```

### Android Setup

No additional setup required for Android.

## Quick Start

Here's a basic example to get you started:

```tsx theme={null}
import { SuadaProvider, ChatView } from '@suada/react-native';

function App() {
  return (
    <SuadaProvider
      config={{
        apiKey: 'your-api-key'
      }}
    >
      <ChatView
        onMessageSubmit={(message) => console.log('Message sent:', message)}
        onResponseReceived={(response) => console.log('Response:', response)}
        style={styles.chat}
      />
    </SuadaProvider>
  );
}

const styles = StyleSheet.create({
  chat: {
    flex: 1,
    backgroundColor: '#ffffff'
  }
});
```

## Authentication

### Setting up your API Key

We recommend storing your API key securely using react-native-config:

1. Install the package:

```bash theme={null}
npm install react-native-config
```

2. Create environment files:

```env theme={null}
# .env.development
SUADA_API_KEY=your-dev-key
SUADA_BASE_URL=https://dev-api.suada.ai

# .env.production
SUADA_API_KEY=your-prod-key
SUADA_BASE_URL=https://api.suada.ai
```

3. Configure the provider:

```tsx theme={null}
import Config from 'react-native-config';
import { SuadaProvider } from '@suada/react-native';

function App() {
  return (
    <SuadaProvider
      config={{
        apiKey: Config.SUADA_API_KEY,
        baseUrl: Config.SUADA_BASE_URL
      }}
    >
      <YourApp />
    </SuadaProvider>
  );
}
```

## Core Components

### ChatView

A pre-built native chat interface component:

```tsx theme={null}
import { ChatView } from '@suada/react-native';

function ChatScreen() {
  return (
    <ChatView
      theme="light"
      placeholder="Ask a question..."
      initialMessages={[]}
      privacyMode={true}
      onMessageSubmit={(message) => {
        console.log('Message:', message);
      }}
      onResponseReceived={(response) => {
        console.log('Response:', response);
      }}
      style={styles.chatView}
    />
  );
}

const styles = StyleSheet.create({
  chatView: {
    flex: 1,
    backgroundColor: '#ffffff'
  }
});
```

#### Props

| Prop               | Type                         | Required | Description                        |
| ------------------ | ---------------------------- | -------- | ---------------------------------- |
| theme              | 'light' \| 'dark'            | No       | UI theme (defaults to 'light')     |
| placeholder        | string                       | No       | Input placeholder text             |
| initialMessages    | Message\[]                   | No       | Pre-loaded chat messages           |
| privacyMode        | boolean                      | No       | Enable enhanced privacy features   |
| style              | ViewStyle                    | No       | Container style                    |
| onMessageSubmit    | (message: string) => void    | Yes      | Called when a message is submitted |
| onResponseReceived | (response: Response) => void | Yes      | Called when a response is received |
| onError            | (error: Error) => void       | No       | Called when an error occurs        |

### Integration Components

#### IntegrationManager

Native component for managing integrations:

```tsx theme={null}
import { IntegrationManager } from '@suada/react-native';

function IntegrationsScreen() {
  return (
    <IntegrationManager
      onIntegrationConnected={(integration) => {
        console.log(`${integration.provider} connected`);
      }}
      onIntegrationDisconnected={(integration) => {
        console.log(`${integration.provider} disconnected`);
      }}
      style={styles.manager}
    />
  );
}

const styles = StyleSheet.create({
  manager: {
    flex: 1,
    padding: 16
  }
});
```

## Hooks

### useSuada

The main hook for accessing Suada functionality:

```tsx theme={null}
import { useSuada } from '@suada/react-native';

function ChatFeature() {
  const { sendMessage, isLoading, error } = useSuada();

  const handleSend = async () => {
    try {
      const response = await sendMessage({
        message: "What's the latest update?",
        privacyMode: true
      });
      console.log('Response:', response);
    } catch (error) {
      console.error('Error:', error);
    }
  };

  return (
    <View style={styles.container}>
      <Button
        onPress={handleSend}
        disabled={isLoading}
        title="Send Message"
      />
      {error && (
        <Text style={styles.error}>Error: {error.message}</Text>
      )}
    </View>
  );
}
```

## Error Handling

The SDK provides platform-specific error handling:

```tsx theme={null}
import { SuadaError, SuadaAPIError } from '@suada/core';

try {
  await sendMessage({ message: "Hello" });
} catch (error) {
  if (error instanceof SuadaAPIError) {
    // Handle API-specific errors
    Alert.alert('API Error', error.message);
  } else if (error instanceof SuadaError) {
    // Handle general SDK errors
    Alert.alert('SDK Error', error.message);
  } else {
    // Handle unexpected errors
    Alert.alert('Error', 'An unexpected error occurred');
  }
}
```

## Best Practices

### Security

* Store API keys securely using react-native-config
* Implement proper certificate pinning
* Use privacy mode for sensitive data
* Secure deep links for OAuth flows

### Performance

* Implement proper memory management
* Use proper image caching
* Handle background/foreground transitions
* Optimize network requests

### Development

* Follow React Native best practices
* Implement proper error boundaries
* Write platform-specific code when needed
* Keep dependencies updated

## Platform-Specific Considerations

### iOS

* Handle keyboard properly
* Implement proper permissions
* Follow Apple's privacy guidelines
* Support dark mode correctly

### Android

* Handle back button behavior
* Implement proper permissions
* Follow Material Design guidelines
* Support different screen sizes

## FAQ

### How do I handle deep linking for OAuth?

Configure deep linking in your app:

```tsx theme={null}
// For iOS: Add to Info.plist
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>suada</string>
    </array>
  </dict>
</array>

// For Android: Add to AndroidManifest.xml
<activity>
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="suada" />
  </intent-filter>
</activity>
```

### How do I customize the native UI?

Use the theme prop and style overrides:

```tsx theme={null}
<ChatView
  theme="light"
  style={styles.chat}
  messageStyle={styles.message}
  inputStyle={styles.input}
/>

const styles = StyleSheet.create({
  chat: {
    backgroundColor: '#f5f5f5'
  },
  message: {
    borderRadius: 8
  },
  input: {
    borderWidth: 1
  }
});
```

### How do I handle offline support?

The SDK includes built-in offline capabilities:

```tsx theme={null}
<SuadaProvider
  config={{
    apiKey: Config.SUADA_API_KEY,
    offlineMode: true,
    syncInterval: 5000
  }}
>
  <YourApp />
</SuadaProvider>
```

### How do I implement retry logic?

Configure retry behavior in the provider:

```tsx theme={null}
<SuadaProvider
  config={{
    apiKey: Config.SUADA_API_KEY,
    maxRetries: 3,
    retryDelay: 1000
  }}
>
  <YourApp />
</SuadaProvider>
```

### How can I debug the SDK?

Enable debug mode and use the debug tools:

```tsx theme={null}
<SuadaProvider
  config={{
    apiKey: Config.SUADA_API_KEY,
    debug: __DEV__,
    logger: (message) => console.log('[Suada]', message)
  }}
>
  <YourApp />
</SuadaProvider>
```

## Support & Resources

### Documentation

* [API Reference](/api-reference)
* [Component Library](/components)
* [Integration Guides](/guides)
* [iOS Guide](/ios-guide)
* [Android Guide](/android-guide)

### Support

* Email Support: [hello@suada.ai](mailto:hello@suada.ai)