@ringg/react-native 0.3.0 → 0.4.0

package/README.md

@@ -20,13 +20,13 @@ views are native.
 npm install @ringg/react-native
 ```
 
-Then the peer dependencies, which must be installed in **your** app so there is
-exactly one autolinked copy of each native module:
+Then the three native modules. React Native autolinking only wires native code
+that resolves from **your** app's `node_modules`, so these cannot be ours:
 
 ```bash
-npx expo install @livekit/react-native @livekit/react-native-webrtc livekit-client react-native-svg
+npx expo install @livekit/react-native @livekit/react-native-webrtc react-native-svg
 # or, without Expo:
-npm install @livekit/react-native @livekit/react-native-webrtc livekit-client react-native-svg
+npm install @livekit/react-native @livekit/react-native-webrtc react-native-svg
 ```
 
 Requires React ≥ 18 · React Native ≥ 0.73.
@@ -36,109 +36,120 @@ Requires React ≥ 18 · React Native ≥ 0.73.
 
 ## Platform setup (required for voice)
 
-**Expo** — add the LiveKit plugin and the permissions to `app.json`:
+Voice calls need a microphone, background audio and LiveKit's manifest
+metadata. Text chat needs none of it.
+
+**Expo** — add the plugin to `app.json` and rebuild. It applies all of the
+above, including the native transport's own configuration:
+
+```json
+{
+  "expo": {
+    "plugins": ["@ringg/react-native"]
+  }
+}
+```
+
+To change the microphone prompt your users see:
 
 ```json
 {
   "expo": {
-    "plugins": ["@livekit/react-native-expo-plugin"],
-    "ios": {
-      "infoPlist": {
-        "NSMicrophoneUsageDescription": "Voice calls use the microphone.",
-        "UIBackgroundModes": ["audio"]
-      }
-    },
-    "android": {
-      "permissions": [
-        "android.permission.RECORD_AUDIO",
-        "android.permission.MODIFY_AUDIO_SETTINGS",
-        "android.permission.ACCESS_NETWORK_STATE",
-        "android.permission.BLUETOOTH_CONNECT"
-      ]
-    }
+    "plugins": [["@ringg/react-native", { "microphonePermissionText": "Talk to support." }]]
   }
 }
 ```
 
-**Bare React Native** — the same keys, by hand: `NSMicrophoneUsageDescription`
-and `UIBackgroundModes: [audio]` in `ios/<App>/Info.plist`, and the four
-permissions above in `android/app/src/main/AndroidManifest.xml`.
+**Bare React Native** — no config plugins, so the same values by hand.
 
-## Integrate in 3 steps
+`ios/<App>/Info.plist`:
 
-### 1 · Register the WebRTC globals
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>Voice calls use the microphone.</string>
+<key>UIBackgroundModes</key>
+<array><string>audio</string></array>
+```
 
-Once, at your app entry, **before** anything imports LiveKit:
+`android/app/src/main/AndroidManifest.xml`:
 
-```ts
-// index.js
-import { registerGlobals } from "@livekit/react-native";
-registerGlobals();
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
 ```
 
-### 2 · Build a transport and a controller
+## Integrate
 
 ```tsx
-import { useEffect, useMemo } from "react";
-import {
-  RinggWidget,
-  createLiveKitTransport,
-  createNativeMicPermission,
-  createRinggWidgetController,
-} from "@ringg/react-native";
-import { createStaticUrlResolver } from "@ringg/core";
-
-const URLS = {
-  dev: { backendUrl: "https://calling-dev.ringg.ai/ca/api/v0", livekitUrl: "wss://ringg-ai-dev-92tubwpz.livekit.cloud" },
-  stage: { backendUrl: "https://stage-api.ringg.ai/ca/api/v0", livekitUrl: "wss://mercury.webrtc-stage.ringg.ai" },
-  prod: { backendUrl: "https://prod-api.ringg.ai/ca/api/v0", livekitUrl: "wss://mercury.webrtc.ringg.ai" },
-};
+import { RinggWidget, appOrigin } from "@ringg/react-native";
+import { Platform } from "react-native";
+
+const BUNDLE_ID = Platform.OS === "android" ? "com.acme.app" : "com.acme.App";
 
-export const RinggSupport = () => {
-  const { controller, livekit } = useMemo(() => {
-    const livekit = createLiveKitTransport();
-    const controller = createRinggWidgetController(
-      {
+export const App = () => (
+  <View style={{ flex: 1 }}>
+    <YourApp />
+    <RinggWidget
+      config={{
         agentId: "<your-agent-id>",
         authorization: "Bearer <your-token>",
+        clientOrigin: appOrigin(BUNDLE_ID),
         title: "Support",
-        description: "How can we help?",
         defaultTab: "text", // or "audio"
-      },
-      {
-        transport: livekit.transport,
-        urlResolver: createStaticUrlResolver(URLS),
-        micPermission: createNativeMicPermission(),
-      },
-    );
-    return { controller, livekit };
-  }, []);
-
-  // Releases the microphone and the audio session — do not skip this.
-  useEffect(() => () => {
-    controller.destroy();
-    livekit.dispose();
-  }, [controller, livekit]);
-
-  return <RinggWidget controller={controller} room={livekit.room} />;
-};
+      }}
+    />
+  </View>
+);
 ```
 
-Passing `room` is optional; it only enables the in-call audio visualizer.
+That is the whole integration. The widget renders its own floating trigger and
+panel over whatever is behind it, so make it the **last child** of your root
+view. Tap the trigger and the chat or voice panel opens.
+
+Endpoints, the media transport and the microphone port are the package's
+business, not yours. `config.mode` (`dev` / `stage` / `prod`, default `prod`)
+picks the environment.
+
+### Reading events, or driving the panel yourself
+
+`onReady` hands back the controller the widget built:
+
+```tsx
+<RinggWidget config={config} onReady={(controller) => {
+  controller.eventBus.on("ringg:conversation_status", ({ status, callId }) => {
+    analytics.track(`call_${status}`, { callId });
+  });
+}} />
+```
 
-### 3 · Mount it over your app
+### Owning the lifecycle yourself
 
-`RinggWidget` renders its own floating trigger and panel over whatever is
-behind it, so make it the **last child** of your root view:
+Pass `ports` to override anything the widget would wire by default — a mock
+transport in tests, your own `urlResolver`, a notification player, a handler for
+agent-triggered app actions:
 
 ```tsx
-<View style={{ flex: 1 }}>
-  <YourApp />
-  <RinggSupport />
-</View>
+<RinggWidget config={config} ports={{ onDomAction: dispatcher }} />
 ```
 
-Tap the trigger → the chat/voice panel opens. That is the whole integration.
+Or build the controller yourself and pass it instead of `config`, when the
+widget cannot own the transport (a shared room, a custom adapter, several views
+on one controller):
+
+```tsx
+const livekit = createLiveKitTransport();
+const controller = createRinggWidgetController(config, {
+  transport: livekit.transport,
+  urlResolver: defaultUrlResolver,
+  micPermission: createNativeMicPermission(),
+});
+
+<RinggWidget controller={controller} room={livekit.room} />;
+// You built it, so you destroy it: controller.destroy(); livekit.dispose();
+```
 
 ## Configuration
 
@@ -243,8 +254,7 @@ every integrator. Wire whichever player your app already has:
 
 ```ts
 import { createAudioPlayer } from "expo-audio";
-import { createNotificationPlayer } from "@ringg/react-native";
-import { DEFAULT_CONFIG } from "@ringg/core";
+import { createNotificationPlayer, DEFAULT_CONFIG } from "@ringg/react-native";
 
 const notification = createNotificationPlayer(DEFAULT_CONFIG.notificationTuneUrl, (url) => createAudioPlayer(url).play());
 ```

package/app.plugin.js

@@ -0,0 +1,73 @@
+/**
+ * Expo config plugin — the whole native setup, in one entry.
+ *
+ * Voice calls need a microphone, background audio and the LiveKit native
+ * module's own manifest metadata. Making integrators assemble that themselves
+ * meant three separate things in their `app.json`: our transport's plugin, a
+ * list of Android permissions, and two `Info.plist` keys. Those are our
+ * requirements, so they are our job:
+ *
+ *   { "expo": { "plugins": ["@ringg/react-native"] } }
+ *
+ * Bare React Native apps have no config plugins and still edit `Info.plist`
+ * and `AndroidManifest.xml` by hand; the values are in the README.
+ *
+ * Plain JS on purpose: Expo resolves `app.plugin.js` from the package root
+ * before any bundler runs, so it cannot be part of the tsup build.
+ */
+
+const { AndroidConfig, withInfoPlist, withPlugins } = require("@expo/config-plugins");
+
+// The subpath, not the package: `main` is deliberately empty there, and the
+// plugin lives at the `app.plugin.js` entry Expo looks for by convention.
+// Requiring it from here (rather than passing the package name for Expo to
+// resolve) keeps it working under pnpm and Yarn PnP, where a dependency of a
+// dependency is not resolvable from the app root.
+const liveKitPlugin = require("@livekit/react-native-expo-plugin/app.plugin");
+const withLiveKit = liveKitPlugin.default ?? liveKitPlugin;
+
+/**
+ * Bluetooth is listed without `maxSdkVersion` filtering: Expo's permission
+ * helper writes plain `uses-permission` entries, and the legacy-only variants
+ * (`BLUETOOTH`, `BLUETOOTH_ADMIN`) are harmless on modern Android. Apps that
+ * care can strip them with their own `withAndroidManifest` plugin.
+ */
+const ANDROID_PERMISSIONS = [
+  "android.permission.INTERNET",
+  "android.permission.RECORD_AUDIO",
+  "android.permission.MODIFY_AUDIO_SETTINGS",
+  "android.permission.ACCESS_NETWORK_STATE",
+  "android.permission.BLUETOOTH_CONNECT",
+];
+
+const DEFAULT_MICROPHONE_TEXT = "Voice calls with the assistant use the microphone.";
+
+/** iOS: the permission prompt copy, and the background mode a live call needs. */
+const withRinggIos = (config, props) =>
+  withInfoPlist(config, (iosConfig) => {
+    // An app that already declares its own copy keeps it: the prompt is user
+    // facing, and ours is a fallback rather than a correction.
+    iosConfig.modResults.NSMicrophoneUsageDescription = props.microphonePermissionText ?? iosConfig.modResults.NSMicrophoneUsageDescription ?? DEFAULT_MICROPHONE_TEXT;
+
+    const backgroundModes = new Set(iosConfig.modResults.UIBackgroundModes ?? []);
+    backgroundModes.add("audio");
+    iosConfig.modResults.UIBackgroundModes = Array.from(backgroundModes);
+
+    return iosConfig;
+  });
+
+/**
+ * @param {object} config Expo config
+ * @param {{ microphonePermissionText?: string }} [props]
+ */
+const withRingg = (config, props = {}) =>
+  withPlugins(config, [
+    // `communication` routes audio to the earpiece/Bluetooth like a phone call
+    // rather than the media stream. A call played through the media channel is
+    // the wrong volume slider and the wrong speaker.
+    [withLiveKit, { android: { audioType: "communication" } }],
+    [AndroidConfig.Permissions.withPermissions, ANDROID_PERMISSIONS],
+    [withRinggIos, props],
+  ]);
+
+module.exports = withRingg;