Quick Start (React Native)

Get a working Qafka widget in your React Native app.

Prerequisites

• Node.js 20 or later
• React Native 0.72+ (Expo or bare)
• A Qafka account with a project created in the dashboard 

1. Install the CLI and log in

npm install -g qafka
 
cd your-react-native-project
qafka login
qafka init

qafka login opens a browser to authenticate. qafka init then:

• installs @qafka/react-native
• registers the Expo config plugin (Expo projects only)
• creates a TEST API key for your project and writes it to .qafka/qafka-runtime.js — this file is gitignored and never committed
• scaffolds a chat screen that imports Qafka and wires the dev config in automatically

Re-run qafka init any time; it’s idempotent and won’t overwrite files you’ve already changed.

If you’d rather install manually, see Manual installation below.

2. Add the required props

The CLI-scaffolded screen mounts <Qafka /> but currently does not fill in projectId — add it yourself. endUserId is also required, so replace the scaffolded placeholder if you haven’t already:

import React from 'react'
import { Qafka } from '@qafka/react-native'
 
// Dev-only: the CLI writes your TEST key here. Dead-code-eliminated from
// production builds, so nothing secret reaches the app bundle.
const qafkaDevConfig = __DEV__ ? require('../.qafka/qafka-runtime') : undefined
 
export default function ChatScreen() {
  return (
    <Qafka
      projectId="proj_abc123"
      endUserId="anonymous"
      devConfig={qafkaDevConfig}
    />
  )
}

• projectId — required. Find it in the dashboard: open your project and copy the id from the page URL (/dashboard/projects/<id>/...), or check qafka.config.d.ts at your project root after running qafka init — it lists every registered project id for autocomplete.
• endUserId — required. A stable identifier for the current user (their signed-in id, or a placeholder like "anonymous" before login). The backend uses it to group conversations and analytics per user.
• devConfig — only needed in development builds. In production the SDK authenticates via device attestation instead (see API Key Security), so no key ever ships in your bundle.

That’s it — theme, greeting, and tools for this project load automatically from the dashboard.

Manual installation

If you’d rather wire things up yourself instead of using the CLI:

npm install @qafka/react-native

Peer dependencies

npm install react-native react-native-safe-area-context

react-native-safe-area-context (>=4) only needs to provide a <SafeAreaProvider> somewhere above the widget — most RN and Expo starters already include one at the app root. @react-navigation/native (>=6) is optional; install it only if you want the SDK to navigate between screens for you.

Expo

Add the config plugin to app.json / app.config.js:

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

Then run npx expo prebuild (or rebuild your dev client) so the native attestation module is bundled. The plugin also adds the microphone permissions needed for voice mode on both platforms — iOS NSMicrophoneUsageDescription and Android RECORD_AUDIO.

Bare React Native

cd ios && pod install

Android autolinking handles the native module. If you plan to use voice mode, add the microphone permission to both platforms yourself — the Expo config plugin isn’t in play for bare projects, so nothing adds these for you:

android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

ios/<YourApp>/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Voice chat requires microphone access</string>

Development key without the CLI

Without qafka init, devConfig has nothing to load. Pass a config object built from a TEST key instead: create one from the dashboard’s API Keys page and save the value shown at creation, since it isn’t shown again. See Configuration for the full shape and how projectId resolves against it.

Next steps

• Configuration — full <Qafka> prop reference
• React Native Widget — customization and callbacks
• Theming — colors, fonts, and layout
• Context — personalizing answers with context and endUserData
• CLI — qafka init, qafka sync, and the rest of the CLI