Skip to main content

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.

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

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

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. 
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: 
<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
Use callbacks during integration: 
<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: 
const config = {
  baseUrl: "http://10.0.2.2:3001",
  tenantDomain: "your-tenant-domain.com"
};

​
Local SDK Reinstall Flow

When testing local SDK changes: 
cd <repo>/sdks/react-native
npm run build
npm pack
Then in client app: 
npm uninstall gtateth-react-native-sdk
npm install "file:../path/to/gtateth-react-native-sdk-0.1.5.tgz"
Restart Metro with cache clear: 
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: 
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.