@jokkoo/sdk-react-native

Official Jokkoo client embed SDK for React Native (iOS and Android). Works in Expo and bare React Native apps (React Native >= 0.72).

Full integration guide: developers.jokkoo.ai/docs/sdks/react-native

Requirements

• React Native >= 0.72
• React >= 18
• Expo SDK 55+ (recommended) or bare React Native
• Development build required — the SDK uses native modules (expo-audio, expo-image-picker, expo-document-picker, expo-file-system) and does not work in Expo Go

Install (Expo)

Install the SDK and its peer dependencies in one step:

npx expo install @jokkoo/sdk-react-native expo-audio expo-image-picker expo-document-picker expo-file-system @tanstack/react-query react-native-safe-area-context

Install (Bare React Native)

npm install @jokkoo/sdk-react-native @tanstack/react-query react-native-safe-area-context
npm install expo expo-audio expo-image-picker expo-document-picker expo-file-system
cd ios && pod install

Configure permissions manually — see Bare React Native permissions in the developer docs.

Expo config plugin

Add the SDK config plugin to app.json (or app.config.js) so photo, camera, microphone, and document permissions are configured automatically:

{
  "expo": {
    "plugins": ["@jokkoo/sdk-react-native"]
  }
}

Optional permission messages:

{
  "expo": {
    "plugins": [
      [
        "@jokkoo/sdk-react-native",
        {
          "photosPermission": "Allow $(PRODUCT_NAME) to access your photos for support attachments.",
          "cameraPermission": "Allow $(PRODUCT_NAME) to use the camera for support attachments.",
          "microphonePermission": "Allow $(PRODUCT_NAME) to access your microphone for voice messages."
        }
      ]
    ]
  }
}

Development build

After installing, create a development build once (native modules are compiled into your app):

npx expo run:ios
# or
npx expo run:android

For daily development, use npx expo start and open the installed dev client on your device or simulator.

Quick start

Wrap your app in JokkooProvider and add a support button. The SDK initializes internally — no useEffect boilerplate required. The SDK never holds your signing secret; only your backend does.

import { JokkooButton, JokkooProvider } from "@jokkoo/sdk-react-native/ui"

export default function App() {
  return (
    <JokkooProvider
      clientToken="your_sandbox_client_token"
      baseUrl="https://api.sandbox.jokkoo.ai"
      locale="fr"
      debug={__DEV__}
      userTokenProvider={async () => {
        const response = await fetch("https://your-api.example.com/jokkoo/token", {
          headers: { Authorization: `Bearer ${yourSessionToken}` },
        })
        const { userToken } = await response.json()
        return userToken
      }}
    >
      <YourApp />
      <JokkooButton position="bottom-right" />
    </JokkooProvider>
  )
}

userTokenProvider is called lazily when the user opens support or the SDK needs a fresh token — not at mount time. Mount JokkooProvider only after the user is authenticated, or use a closure that reads your current session when invoked.

See Authentication for the token model and Server SDK for signing user tokens on your backend.

Theming

Pass a partial theme to override colors, spacing, typography, or border radii:

<JokkooProvider
  clientToken="tok_..."
  userTokenProvider={fetchUserToken}
  theme={{
    colors: {
      primary: "#0057FF",
      chatHeaderBackground: "#0057FF",
    },
    bubbleBorderRadius: 16,
  }}
>
  <YourApp />
</JokkooProvider>

Export defaultTheme and mergeTheme from @jokkoo/sdk-react-native/ui if you need to extend the default palette programmatically.

Locales

Supported locales: "fr" (default) and "en". Set via the locale prop on JokkooProvider.

Features

• Support Center modal with conversation list and chat UI
• Real-time messaging via WebSocket
• Voice message recording and playback
• File and image attachments
• Satisfaction ratings
• Theming and localization

Advanced: imperative init

For non-React usage or manual lifecycle control:

import { Jokkoo } from "@jokkoo/sdk-react-native"

Jokkoo.init({
  clientToken: "your_sandbox_client_token",
  userTokenProvider: async () => fetchUserToken(),
  baseUrl: "https://api.sandbox.jokkoo.ai",
  debug: __DEV__,
})

// Remember to call Jokkoo.destroy() when tearing down

For React apps, prefer JokkooProvider — it handles init and cleanup automatically.

API

Core (@jokkoo/sdk-react-native)

| Export | Description | | ------ | ----------- | | Jokkoo | SDK singleton | | Jokkoo.init(config) | Initialize the SDK (advanced / non-React use) | | Jokkoo.destroy() | Tear down SDK state | | Jokkoo.isInitialized() | Returns whether the SDK is initialized | | Jokkoo.getState() | Returns current SDK state | | JokkooApiClient | REST API client | | JokkooRealtimeClient | WebSocket client | | TokenManager | JWT refresh and caching | | validateConfig | Validate SDK configuration | | REALTIME_EVENTS | Realtime event name constants | | NEW_CONVERSATION_ID | Sentinel ID for new conversations |

UI (@jokkoo/sdk-react-native/ui)

| Export | Description | | ------ | ----------- | | JokkooProvider | React context wrapper; initializes SDK and provides chat state | | JokkooButton | Floating action button to open support | | JokkooModal | Support Center modal (included in JokkooButton) | | RequestListScreen | Conversation list screen | | ConversationScreen | Chat / conversation screen | | useJokkooContext() | Theme, translations, navigation, chat open/close, unread count | | useConversations | Fetch conversation list (React Query) | | useMessages | Fetch messages with pagination (React Query) | | useRealtimeStatus | WebSocket connection status | | jokkooQueryKeys | React Query key factory | | defaultTheme | Default theme object | | mergeTheme | Deep-merge partial theme with defaults | | getTranslations | Resolve locale strings |

JokkooProvider props

| Prop | Required | Description | | ---- | -------- | ----------- | | clientToken | Yes | Public channel token from Jokkoo dashboard | | userTokenProvider | Yes | Async callback returning a user JWT from your backend | | baseUrl | No | API base URL (default: https://api.jokkoo.ai) | | locale | No | "fr" or "en" (default: "fr") | | debug | No | Enable debug logging (default: false) | | tokenRefreshBufferSeconds | No | Proactive refresh buffer (default: 60) | | theme | No | Partial theme override | | queryClient | No | Shared React Query client |

JokkooButton props

| Prop | Default | Description | | ---- | ------- | ----------- | | position | "bottom-right" | "bottom-right" or "bottom-left" | | size | 56 | Button diameter in pixels | | color | theme primary | Background color | | style | — | Additional container styles | | icon | chat icon | Custom icon render prop |

Troubleshooting

See React Native troubleshooting for common setup issues (Expo Go, native build mismatches, iOS signing, Metro resolution).

Development

cd typescript
pnpm install
pnpm --filter @jokkoo/sdk-react-native build
pnpm --filter @jokkoo/sdk-react-native test

License

Apache-2.0