@jokkoo/sdk-react-native
v1.3.9
Published
Jokkoo client embed SDK for React Native (iOS and Android)
Readme
@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-contextInstall (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 installConfigure 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:androidFor 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.
Contextual conversations
Open support from a transaction, order, or any other entity. The API reuses the signed-in user's non-closed thread for that entity, or creates a new one.
import { useJokkooContext } from "@jokkoo/sdk-react-native/ui"
const { openConversation } = useJokkooContext()
void openConversation({
contextType: "transaction",
contextId: "XYZ",
prefillMessage: "I have an issue with transaction XYZ",
autoSend: false,
attributes: [
{ label: "Amount", value: 100 },
{ label: "Operator", value: "Wave" },
],
})Full guide: contextual-conversations.md.
Theming
Pass a JokkooThemeOverride to override only the tokens you need. Unspecified tokens keep SDK defaults.
<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:
import { mergeTheme } from "@jokkoo/sdk-react-native/ui"
const theme = mergeTheme({ colors: { primary: "#0057FF" } })Locales
Supported locales: "fr" (default) and "en". Set via the locale prop on JokkooProvider.
Features
- Contextual conversations (
openConversation) linked to a business entity - 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 downFor 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 (openChat, openConversation, closeChat, goBack), 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 a JokkooThemeOverride 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 | JokkooThemeOverride — only listed tokens replace defaults |
| queryClient | No | Shared React Query client |
| showHeader | No | Show list/conversation header (default true). When false, the host owns title and navigation via closeChat / goBack on useJokkooContext(). |
Set showHeader={false} to embed the sheet under your own navigation. The drag handle, backdrop tap, and Android hardware back still work.
JokkooButton props
| Prop | Default | Description |
| ---- | ------- | ----------- |
| position | "bottom-right" | top-left, top-right, middle-left, middle-right, bottom-left, or bottom-right |
| margin | — | Optional { top, right, bottom, left }. A provided side replaces the default inset (theme.spacing.lg, 24px). 0 is flush to that edge. |
| size | 56 | Button diameter in pixels |
| color | theme primary | Background color |
| style | — | Additional container styles |
| icon | chat icon | Custom icon render prop |
<JokkooButton position="middle-right" margin={{ right: 12 }} />
<JokkooButton position="bottom-left" margin={{ left: 16, bottom: 48 }} />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 testLicense
Apache-2.0
