npm package: @jusbiz/offers-chatbot-sdk
Description: Native Offers Chatbot SDK for Android, iOS and React Native
Author: Juspay
Latest version: 1.0.0

# Offers SDK Integration Guide (Native)

This guide describes how to integrate the **Offers Chatbot SDK** directly into your native Android, iOS, and React Native applications. This is a **heavyweight SDK** that embeds the React Native runtime into your app for maximum performance and native UI experience.

---

## Table of Contents
1. [Prerequisites](#prerequisites)
2. [React Native Integration](#react-native-integration)
3. [Android Integration (Native)](#android-integration-native)
4. [iOS Integration (Native)](#ios-integration-native)
5. [Configuration & Theming](#configuration--theming)

---

## 1. Prerequisites

- **Host App Compatibility**: 
  - Android: API 21+
  - iOS: 13.0+

---

## 2. React Native Integration

If you are already using React Native, you can directly import the component.

### Installation
1. Copy the `src/sdk` and `src/components`, `src/hooks`, `src/api`, `src/constants`, `src/utils`, `src/types` directories into your project.
2. Ensure you have the following dependencies in your `package.json`:
   - `@tanstack/react-query`
   - `axios`
   - `expo-font`
   - `expo-linking`
   - `@react-native-community/netinfo`
   - `lottie-react-native`

### Usage
```tsx
import { ChatbotProvider, OffersChatbot } from './sdk';

const App = () => {
  return (
    <ChatbotProvider>
      <OffersChatbot 
        initialWebsite="deliveroo"
        initialMode="DYNAMIC"
      />
    </ChatbotProvider>
  );
};
```

---

## 3. Android Integration (Native)

To integrate into a purely native Android app, you will use **React Native as a Library**.

### A. Add React Native Dependency
Add the React Native and Expo unimodules to your `build.gradle`.

### B. Kotlin Integration (Android)

In your Kotlin-based Android app, create a `ChatbotActivity`. If you are using **PureScript**, you can trigger this Activity via an `Effect` or `FFI` call to the Kotlin layer.

```kotlin
// ChatbotActivity.kt
package com.yourcompany.app

import com.facebook.react.ReactActivity
import com.facebook.react.ReactActivityDelegate
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
import com.facebook.react.defaults.DefaultReactActivityDelegate

class ChatbotActivity : ReactActivity() {
    override fun getMainComponentName(): String = "OffersChatbot"

    override fun createReactActivityDelegate(): ReactActivityDelegate =
        DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
}
```

### C. Triggering from PureScript

If your business logic is in PureScript, use FFI to launch the Intent:

```purescript
-- Inside your PureScript FFI / Native layer
foreign import launchChatbot :: Effect Unit

-- Kotlin / FFI implementation
/* 
fun launchChatbot() {
    val intent = Intent(context, ChatbotActivity::class.java)
    context.startActivity(intent)
}
*/
```

### D. Initialization (MainApplication.kt)
Initialize the React Native runtime in your Application class:

```kotlin
class MainApplication : Application(), ReactApplication {
    override val reactNativeHost: ReactNativeHost = object : DefaultReactNativeHost(this) {
        override fun getPackages(): List<ReactPackage> = PackageList(this).packages
        override fun getJSMainModuleName(): String = "SDK/index"
        override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
    }
}
```

---

## 4. iOS Integration (Native)

To integrate into a native iOS app using CocoaPods.

### A. Podfile Configuration
Include React and its dependencies in your `Podfile`.

```ruby
pod 'React', :path => '../node_modules/react-native'
pod 'React-Core', :path => '../node_modules/react-native'
# ... add other required pods
```

### B. Swift Integration (iOS)

In your Swift app, you can present the chatbot as a `UIViewController`.

```swift
import UIKit
import React

class ChatbotManager {
    static func getChatbotView(sessionToken: String) -> UIView {
        let props: [String: Any] = [
            "initialWebsite": "deliveroo",
            "authToken": sessionToken
        ]
        
        let jsCodeLocation = Bundle.main.url(forResource: "main", withExtension: "jsbundle")!
        
        let rootView = RCTRootView(
            bundleURL: jsCodeLocation,
            moduleName: "OffersChatbot",
            initialProperties: props,
            launchOptions: nil
        )
        
        return rootView
    }
}

// usage in a ViewController
func openChat() {
    let chatbotView = ChatbotManager.getChatbotView(sessionToken: "your_token")
    let vc = UIViewController()
    vc.view = chatbotView
    self.present(vc, animated: true)
}
```

---

## 5. Configuration & Theming

The `OffersChatbot` component supports the following props for customization:

| Prop | Type | Description |
|------|------|-------------|
| `initialWebsite` | `WebsiteID` | 'deliveroo', 'wildhoney', 'hotels' |
| `initialMode` | `ChatMode` | 'DYNAMIC', 'DEMO' |
| `onClearChat` | `() => void` | Callback for chat reset events |
| `onError` | `(msg: string) => void` | Callback for handling errors |

### Passing Data from Native to Chatbot
Use the `initialProperties` (iOS) or `getLaunchOptions` (Android) to pass user-specific tokens and branding configurations during initialization.

### Deep Linking
The SDK supports deep links for payment redirects and specific offers. Host apps should forward deep links to the SDK:
- **Scheme**: `chatbotdemo://`
- **Host**: `chatbotdemo.juspay.in`

---
**Support**: Contact Juspay Agentic Team for integration support.