Installation

@alaznah/calling is published on the public npm registry.

Requirements

• React Native 0.76+ (see Compatibility for the full matrix)
• Android compileSdk 35 or 36 · minSdk 24
• iOS 13+
• React Native CLI app, or Expo development build
• Working mic (and camera for video) on a physical device for real call tests

Expo Go will not load the native calling modules.

Full version table (RN ↔ compileSdk ↔ New Architecture): Compatibility.

1. Install the package

@alaznah/calling ships native modules as peer dependencies — they must live in your app (single React Native copy / autolinking). Pick your package manager:

npm install @alaznah/calling

# Required peers
npm install react-native-webrtc react-native-incall-manager @react-native-community/netinfo react-native-svg

That installs @alaznah/calling and its dependency @alaznah/protocol. Required peers:

REQUIRED

These stay as peers on purpose — the SDK does not bundle WebRTC, NetInfo, InCall Manager, or SVG. Your app already has react and react-native. The same peer set is required for voice and video (there is no separate voice-only package).

OPTIONAL

Optional CallKeep (only if you enable that integration):

npm install react-native-callkeep

Without react-native-webrtc, startCall fails with WebRTC adapters not found — see Troubleshooting.

2. iOS

Pods

cd ios && pod install && cd ..

Info.plist (copy-paste)

Edit ios/<AppName>/Info.plist (or Xcode → Info):

<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for audio and video calls.</string>

<!-- Add if you use video calls -->
<key>NSCameraUsageDescription</key>
<string>Camera access is required for video calls.</string>

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>voip</string>
  <string>remote-notification</string>
</array>

Xcode → Signing & Capabilities: enable Background Modes (Audio + Voice over IP) and Push Notifications if you need background / kill-state ringing — Push Notifications.

Full matrices: Permissions.

3. Android

Use compileSdk 35 (RN 0.76–0.80) or 36 (RN 0.81+) — Compatibility. You should not need to bump past your RN template default for Alaznah.

AndroidManifest.xml (copy-paste)

In android/app/src/main/AndroidManifest.xml, inside <manifest> (before <application>):

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

<!-- Video (or apps that offer both voice and video) -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Recommended: notifications, Bluetooth, incoming UI -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />

More detail: Permissions.

4. Expo (development build)

Expo Go is not supported. In app.json / app.config:

{
  "expo": {
    "plugins": ["@alaznah/calling"]
  }
}

Then:

npx expo prebuild
# or EAS development build
eas build --profile development

Still verify generated plist / manifest after prebuild.

5. Rebuild native binaries

After install or plist/manifest changes, rebuild (Xcode / Gradle / EAS). Metro reload alone is not enough.

# iOS
npx react-native run-ios

# Android
npx react-native run-android

6. Verify import

import {
  CallingProvider,
  CallingScreen,
  requestCallPermissions,
  DEFAULT_HOSTED_SIGNALING_URL,
} from '@alaznah/calling';

UI deep imports (optional):

import { CallingUI } from '@alaznah/calling';
import { IncomingCallScreen, ActiveCallScreen } from '@alaznah/calling/ui';

Next

• Permissions — full iOS / Android matrices
• Compatibility — RN / Android / iOS versions
• Quick Start — first call
• Authentication — tokens
• Troubleshooting