Prerequisites

  • Node.js 18+ and yarn 4
  • React Native 0.79 or later (bare workflow; managed Expo will be provided in future releases)
  • Xcode 14+ with Command Line Tools (for iOS)
  • Android Studio with SDK 27+ and JDK 17+ (for Android)

1. Add the Plugin to Your App

From your React Native project root, add the tarball as a dependency:

yarn add file:/path/to/keenasr-react-native-CUSTOMER-vVERSION-HASH.tgz

or, using npm:

npm install /path/to/keenasr-react-native-CUSTOMER-vVERSION-HASH.tgz

The tarball contains:

  • The TypeScript API (src/) and compiled JS (lib/)
  • iOS SDK (KeenASR.xcframework) and Android SDK (KeenASR.aar)
  • The ASR bundle you configured at build time
  • An example app and an EdTech POC app
  • A helper script (scripts/run-example.sh) you can use to validate the install before integrating

2. iOS Setup

Install pods:

cd ios
pod install

The plugin’s podspec links KeenASR.xcframework into your app automatically. No manual framework drag-and-drop is required.

The ASR bundle that the plugin was built with is included automatically in the app bundle. To add a different (or additional) ASR bundle, drag its directory into your Xcode project and ensure “Copy items if needed” and your app target are selected; then reference it by name at runtime via KeenASR.initialize('your-bundle-name'). Alternatively, if the bundle is downloaded at runtime to a writable location, use KeenASR.initializeWithPath('/absolute/path/to/bundle').

Microphone permission: TODO, confirm whether the podspec / plugin sets NSMicrophoneUsageDescription automatically or whether you need to add it to your app’s Info.plist. If the plugin does not handle it, add an entry similar to:

<key>NSMicrophoneUsageDescription</key>
<string>Your app uses the microphone for speech recognition.</string>

3. Android Setup

The Android SDK (KeenASR.aar) is included in the tarball under android/repo/ and is linked into your build via the plugin’s build.gradle. No additional Gradle changes are required for a standard React Native project.

The ASR bundle that the plugin was built with is included automatically in android/app/src/main/assets/. To add a different ASR bundle, drop its directory into android/app/src/main/assets/ and reference it by name at runtime via KeenASR.initialize('your-bundle-name'). If the bundle is downloaded at runtime to a writable location, use KeenASR.initializeWithPath('/absolute/path/to/bundle').

Microphone permission: TODO, confirm whether the plugin’s AndroidManifest.xml declares RECORD_AUDIO automatically. The permission is also runtime-prompted on Android 6+; request it before calling KeenASR.startListening(). A common pattern uses PermissionsAndroid.request(...) from React Native.

Minimum SDK: Android 8.1 (API 27) or later, matching the native SDK floor. Ensure android/build.gradle has minSdkVersion >= 27.

4. Verify the Setup

The tarball ships with two ready-to-run apps you can use to verify the install end-to-end:

# iOS (default), with Apple Silicon simulator
./scripts/run-example.sh --simulator="iPhone 16 Pro"

# Android emulator
./scripts/run-example.sh --platform=android

The example app shows a Start Listening button. Tap it, say one of the configured phrases, and the recognized text appears on screen. The EdTech POC app demonstrates pronunciation scoring and oral reading with TextAligner.

If startup fails, check that:

  • The ASR bundle is included in the iOS app bundle / android/app/src/main/assets/ and the name passed to initialize(...) matches the bundle directory name exactly.
  • Microphone permission is granted (both at the OS level and at runtime on Android).
  • The recognizer is awaited: every method on KeenASR returns a Promise; await them or chain .then(...).

5. Upgrading

When upgrading to a new tarball, remove the previously installed package first to avoid stale native artifacts:

yarn remove keenasr-react-native
yarn add file:/path/to/keenasr-react-native-CUSTOMER-vNEWVERSION-HASH.tgz
cd ios && pod install

Platform Notes

iOS:

  • The plugin is a Turbo Module; the New Architecture is required.
  • KeenASR.xcframework is automatically linked by the podspec; no manual framework embedding is required.
  • Hot-reload caveat: the native singleton survives a Metro reload. If a subsequent initialize() from JS fails after a reload, restart the app (rebuild on iOS) to start with a clean native state.

Android:

  • The plugin is a Turbo Module; the New Architecture is required.
  • Hot-reload caveat: the native singleton survives a Metro reload. If initialize() fails after a reload, use adb shell am force-stop <pkg> to restart with a clean native state.