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

# React Native SDK

> Client-facing guide for integrating the g-tateth mobile chat SDK in React Native apps.

The official React Native SDK for integrating g-tateth chat into iOS and Android apps.

## Overview

With the React Native SDK, clients can:

* Initialize a chat session from mobile
* Send and receive messages in real time
* Render native chat UI
* Open a native help center modal before chat
* Customize chat and help center UI in-app

## Installation

```bash theme={null}
npm install gtateth-react-native-sdk @react-native-async-storage/async-storage
```

Clients do not need to install `axios`, `socket.io-client`, or `uuid` manually.

## Required Configuration

`GtatethChatWidget` needs:

* `config.baseUrl` (required)
* Tenant identity (required): `config.tenantDomain` or `config.tenantId`

`customer` is optional. Customer fields are optional.

## Quick Integration

```tsx theme={null}
import React from "react";
import { SafeAreaView } from "react-native";
import { GtatethChatWidget } from "gtateth-react-native-sdk";

export function SupportScreen() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <GtatethChatWidget
        config={{
          baseUrl: "https://api.g-tateth.com",
          tenantDomain: "your-tenant-domain.com"
        }}
        customer={{
          firstName: "Jane",
          lastName: "Doe",
          email: "jane@example.com"
        }}
        allowInAppCustomization
      />
    </SafeAreaView>
  );
}
```

## Help Center + Chat Flow

`GtatethHelpCenter` is exported from package root and opens directly as a modal.

```tsx theme={null}
import React, { useState } from "react";
import { Modal, Pressable, Text } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import {
  GtatethChatWidget,
  GtatethHelpCenter,
  WidgetClientConfig
} from "gtateth-react-native-sdk";

const config: WidgetClientConfig = {
  baseUrl: "https://api.g-tateth.com",
  tenantDomain: "your-tenant-domain.com"
};

export function SupportScreen() {
  const [chatVisible, setChatVisible] = useState(false);

  return (
    <SafeAreaView style={{ flex: 1 }}>
      {!chatVisible ? (
        <GtatethHelpCenter
          config={config}
          onStartChat={() => setChatVisible(true)}
        />
      ) : null}

      <Modal visible={chatVisible} animationType="slide" onRequestClose={() => setChatVisible(false)}>
        <SafeAreaView style={{ flex: 1 }}>
          <Pressable onPress={() => setChatVisible(false)}>
            <Text>Close</Text>
          </Pressable>
          <GtatethChatWidget
            config={config}
            customer={{ firstName: "Jane", lastName: "Doe", email: "jane@example.com" }}
            onBackPress={() => setChatVisible(false)}
            backLabel="BACK"
            allowInAppCustomization
            persistInAppCustomization
          />
        </SafeAreaView>
      </Modal>
    </SafeAreaView>
  );
}
```

## In-App Customization

Enable runtime settings editing:

```tsx theme={null}
<GtatethChatWidget
  config={{
    baseUrl: "https://api.g-tateth.com",
    tenantDomain: "your-tenant-domain.com"
  }}
  allowInAppCustomization
  persistInAppCustomization
/>
```

When enabled, users can edit:

* `APPEARANCE`: chat colors
* `BEHAVIOR`: text and behavior toggles
* `CHATBOT`: chatbot controls
* `HELP CENTER`: help center modal colors

If `GtatethHelpCenter` is used in the same app, saved `HELP CENTER` settings are automatically applied there.

## Tenant Settings vs In-App Settings

Default load order:

* SDK defaults
* Tenant settings from backend (`/api/widget/settings`) when `useTenantSettings` is `true`
* Persisted in-app customization

For `GtatethHelpCenter`:

* Branding auto-uses tenant widget appearance colors by default
* Persisted in-app `HELP CENTER` customization overrides those defaults
* Optional `theme` prop can still override specific colors directly

## Prop Reference

### `GtatethChatWidget` (main props)

* `config: WidgetClientConfig` required
* `sessionId?: string`
* `customer?: { firstName?: string; lastName?: string; email?: string; phone?: string; company?: string }`
* `context?: ChatContext`
* `settings?: Partial<ChatWidgetSettings>`
* `theme?: Partial<ChatTheme>`
* `useTenantSettings?: boolean` default `true`
* `allowInAppCustomization?: boolean` default `false`
* `persistInAppCustomization?: boolean` default `true`
* `customizationStorageKey?: string`
* `enableRealtime?: boolean` default `true`
* `onBackPress?: () => void`
* `backLabel?: string` default `BACK`
* `onReady?: (conversationId: string) => void`
* `onError?: (error: string) => void`

### `GtatethHelpCenter` (main props)

* `config: WidgetClientConfig` required
* `title?: string`
* `subtitle?: string`
* `chatLabel?: string`
* `helpCenterLabel?: string`
* `launcherLabel?: string` (kept for compatibility)
* `useTenantSettings?: boolean` default `true`
* `customizationStorageKey?: string`
* `theme?: Partial<HelpCenterTheme>`
* `onStartChat?: () => void | Promise<void>`
* `onError?: (error: string) => void`

## Recommended Debug Hooks

Use callbacks during integration:

```tsx theme={null}
<GtatethChatWidget
  config={config}
  onReady={(conversationId) => console.log("Widget ready:", conversationId)}
  onError={(error) => console.log("Widget error:", error)}
/>
```

## Local Testing (React Native)

If backend runs locally:

* Android emulator base URL: `http://10.0.2.2:3001`
* iOS simulator base URL: `http://localhost:3001`
* Physical device base URL: `http://<your-laptop-lan-ip>:3001`

Example:

```tsx theme={null}
const config = {
  baseUrl: "http://10.0.2.2:3001",
  tenantDomain: "your-tenant-domain.com"
};
```

## Local SDK Reinstall Flow

When testing local SDK changes:

```bash theme={null}
cd <repo>/sdks/react-native
npm run build
npm pack
```

Then in client app:

```bash theme={null}
npm uninstall gtateth-react-native-sdk
npm install "file:../path/to/gtateth-react-native-sdk-0.1.5.tgz"
```

Restart Metro with cache clear:

```bash theme={null}
npx expo start -c --lan
```

## Expo / Android Connectivity Checklist

If Expo Go shows `Cannot connect to Expo CLI`:

* Stop old Expo terminals
* Run `adb reverse --remove-all`
* Run `adb shell pm clear host.exp.exponent`
* Start Expo again with `npx expo start -c --lan`
* Press `a` to open Android
* Verify emulator appears in `adb devices`

If using localhost mode, also forward ports:

```bash theme={null}
adb reverse tcp:8081 tcp:8081
adb reverse tcp:19000 tcp:19000
```

## Realtime Notes

Realtime now tries:

* `websocket`
* fallback `polling`
* HTTP message refresh fallback when realtime is temporarily offline

So if websocket is blocked by network/proxy, chat can still connect via polling.

## Common Issues

* `Tenant not found`

* Use the exact `tenantDomain` or `tenantId` provided during onboarding.

* Endless loading spinner on chat init

* Confirm backend reachable from device/emulator.

* Verify `baseUrl` format for your environment.

* Use `onError` callback to inspect failure text.

* `Error: websocket error`

* Usually infra/network websocket upgrade issue.

* Fallback polling should recover after SDK update.

* Black/blank screen in Expo

* Use package-root imports only.

* Avoid deep imports like `.../dist/ui/...`.

* Clear Expo Go app data and restart Metro with `-c`.

* Help center customization not visible in settings

* Enable `allowInAppCustomization` on `GtatethChatWidget`.

* Open settings and use the `HELP CENTER` tab.

## Best Practices

* Keep `SafeAreaView` with `flex: 1` around SDK components.
* Pass stable `sessionId` if you want continuity across remounts.
* Keep `useTenantSettings` enabled for tenant-managed branding/behavior unless explicitly overriding.