@worktual/react-native-ai-bot 1.0.4 → 1.0.5

package/README.md

@@ -21,7 +21,53 @@ For iOS:
 cd ios && pod install
 ```
 
-## Quick Start
+## Quick Start (Recommended - Instant Open)
+
+For the best user experience, mount the bot **hidden at your app root** so it pre-loads in the background. When the user taps your button, the bot opens **instantly** with zero loading time.
+
+```tsx
+import React, { useState } from "react";
+import { View, TouchableOpacity, Text, StyleSheet } from "react-native";
+import { WorktualAIBot } from "@worktual/react-native-ai-bot";
+
+const App = () => {
+  const [showBot, setShowBot] = useState(false);
+
+  return (
+    <View style={{ flex: 1 }}>
+      {/* Your app content */}
+      <TouchableOpacity onPress={() => setShowBot(true)}>
+        <Text>Open AI Chat</Text>
+      </TouchableOpacity>
+
+      {/* Bot is always mounted but hidden — pre-loads in background */}
+      <View
+        style={[
+          StyleSheet.absoluteFill,
+          {
+            zIndex: showBot ? 999 : -1,
+            opacity: showBot ? 1 : 0,
+          },
+        ]}
+        pointerEvents={showBot ? "auto" : "none"}
+      >
+        <WorktualAIBot
+          webchatId="YOUR_WEBCHAT_ID"
+          onClose={() => setShowBot(false)}
+        />
+      </View>
+    </View>
+  );
+};
+
+export default App;
+```
+
+**Why this works:** The WebView starts loading the bot HTML/JS/CSS as soon as your app renders. By the time the user taps the button, everything is already loaded. Toggling visibility is instant — no loading screen, no delay.
+
+## Alternative: Navigation-Based (Shows Loading Screen)
+
+If you prefer a separate screen approach, the bot will show a brief loading screen while the WebView downloads:
 
 ```tsx
 import React from "react";
@@ -45,7 +91,7 @@ Register it as a screen in your navigator:
 <Stack.Screen name="ChatBot" component={ChatBotScreen} />
 ```
 
-Then navigate to it from anywhere (e.g. a floating button):
+Then navigate to it:
 
 ```tsx
 <TouchableOpacity onPress={() => navigation.navigate("ChatBot")}>
@@ -53,8 +99,32 @@ Then navigate to it from anywhere (e.g. a floating button):
 </TouchableOpacity>
 ```
 
+> **Note:** This approach mounts a fresh WebView each time, so users will see a loading screen for 2-5 seconds while the bot downloads. Use the [recommended approach](#quick-start-recommended---instant-open) above for instant loading.
+
+## Preloader (For Navigation-Based Setup)
+
+If you use the navigation approach but still want faster loading, mount the `WorktualAIBotPreloader` early in your app tree. It pre-fetches and caches the bot resources in the background:
+
+```tsx
+import { WorktualAIBotPreloader } from "@worktual/react-native-ai-bot";
+
+// In your App.tsx or root layout
+const App = () => {
+  return (
+    <SafeAreaProvider>
+      <WorktualAIBotPreloader webchatId="YOUR_WEBCHAT_ID" />
+      <NavigationContainer>
+        {/* ... your screens */}
+      </NavigationContainer>
+    </SafeAreaProvider>
+  );
+};
+```
+
 ## Props
 
+### WorktualAIBot
+
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `webchatId` | `string` | Yes | — | Your unique webchat ID provided by Worktual |
@@ -71,6 +141,13 @@ Then navigate to it from anywhere (e.g. a floating button):
 | `onReady` | `() => void` | No | — | Called when chat content is fully loaded |
 | `onMessage` | `(data) => void` | No | — | Called on every message from the chat |
 
+### WorktualAIBotPreloader
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `webchatId` | `string` | Yes | — | Your unique webchat ID provided by Worktual |
+| `baseUrl` | `string` | No | Worktual production URL | Custom bot URL if self-hosted |
+
 ## Customisation Examples
 
 ### Custom logo on loading screen
@@ -80,7 +157,7 @@ Use a local image:
 ```tsx
 <WorktualAIBot
   webchatId="YOUR_WEBCHAT_ID"
-  onClose={() => navigation.goBack()}
+  onClose={() => setShowBot(false)}
   loadingLogo={require("./assets/my-logo.png")}
   loadingLogoWidth={120}
   loadingLogoHeight={120}
@@ -92,7 +169,7 @@ Or a remote URL:
 ```tsx
 <WorktualAIBot
   webchatId="YOUR_WEBCHAT_ID"
-  onClose={() => navigation.goBack()}
+  onClose={() => setShowBot(false)}
   loadingLogo={{ uri: "https://example.com/logo.png" }}
   loadingLogoWidth={100}
   loadingLogoHeight={100}
@@ -106,7 +183,7 @@ Or a remote URL:
 ```tsx
 <WorktualAIBot
   webchatId="YOUR_WEBCHAT_ID"
-  onClose={() => navigation.goBack()}
+  onClose={() => setShowBot(false)}
   loadingLogo={require("./assets/logo.png")}
   loadingTitle="Support Chat"
   loadingSubtitle="Connecting to an agent..."
@@ -142,7 +219,7 @@ const App = () => {
 ```tsx
 <WorktualAIBot
   webchatId="YOUR_WEBCHAT_ID"
-  onClose={() => navigation.goBack()}
+  onClose={() => setShowBot(false)}
   onReady={() => console.log("Bot is ready!")}
   onMessage={(data) => console.log("Bot event:", data)}
 />
@@ -150,11 +227,18 @@ const App = () => {
 
 ## How It Works
 
-1. Client taps a button → navigates to the bot screen
+### Recommended (Instant Open)
+1. Bot WebView is mounted hidden when your app loads
+2. HTML/JS/CSS downloads in the background automatically
+3. User taps button → bot becomes visible instantly (no loading screen)
+4. User closes chat → bot hides (stays mounted, ready for next open)
+
+### Navigation-Based (With Loading Screen)
+1. User taps button → navigates to bot screen
 2. A branded loading screen appears (with animated progress bar)
 3. The chat loads behind the loading screen
 4. Once chat content is rendered, the loader fades out smoothly
-5. When the user closes the chat (via the bot's close button), `onClose` is called
+5. User closes chat → `onClose` is called, navigates back
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worktual/react-native-ai-bot",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Worktual AI Bot - Embeddable AI chatbot for React Native apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",