Fix common Alaznah Calling integration issues.
Troubleshooting
| Symptom | Likely fix |
|---|---|
checkDebugAarMetadata / androidx.core requires API 36 | Use @alaznah/calling that supports compileSdk 35/36, or see Compatibility. Do not needlessly bump past your RN default |
Unable to resolve module / Metro path errors | Rebuild; clear Metro cache (--reset-cache); ensure required peers are installed (react-native-webrtc, react-native-incall-manager, @react-native-community/netinfo, react-native-svg) — Installation |
| Native module missing / null | Rebuild the binary; Expo Go unsupported — Native Modules |
WebRTC adapters not found | Required peers missing — especially react-native-webrtc. npm: install @alaznah/calling, then npm install react-native-webrtc react-native-incall-manager @react-native-community/netinfo react-native-svg. Yarn / pnpm: one-line install in Installation. Then rebuild. CallKeep is optional and not needed for this error |
| Cannot connect | Reachable signalingUrl; device cannot use your laptop localhost without a tunnel |
| Auth / 401 | Token userId must match config.userId; mint a fresh token |
| No audio | Mic permission; check mute on both peers; physical device preferred |
| Black / no video | Camera permission; mediaType: 'video'; check videoEnabled |
| One-way media | Firewall / ICE — try iceTransportPolicy: 'relay' with working TURN |
| No ring in background | Console push credentials + registerPushToken + OS permissions |
| JS incoming flashes after native Accept | Call drainNativeIncomingAction() then syncPendingCalls() on AppState active |
| Accept “does nothing” on tap | By design — swipe up on the green control |
| Duplicate native + JS incoming | setNativeIncomingSuppressed(true) while in-app calling UI is mounted |
| iOS simulator CallKit crash | Do not enable CallKeep / CallKit paths that disallow simulator |
| iOS PiP never starts (simulator) | Expected — AVKit PiP is not available on iOS Simulator. Use a physical iPhone; in-app minimize bubble works — Picture in Picture |
| iOS PiP never starts (device) | Audio background mode + react-native-webrtc patch (postinstall) + rebuild — Native Modules |
| Android PiP never starts | Rebuild after SDK install. Do not copy PiP flags into the host manifest for a standard MainActivity — see Android PiP host manifest |
Console spam rn-webrtc:pc:DEBUG | Release (0.1.0+): silenced when __DEV__ is false. Dev: expected verbose WebRTC output in Metro |
displayName is required / startCall throws | Pass config.displayName and startCall({ calleeDisplayName }) — What's new |
| Wake Accept stuck on ringing | CallingProvider now always connect() + syncPendingCalls() on foreground; custom hosts must do the same |
Android PiP host manifest
You do not need to add these on the host launcher Activity for PiP to work:
android:supportsPictureInPicture="true"
android:resizeableActivity="true"| Attribute | Host app? |
|---|---|
supportsPictureInPicture="true" | No for standard RN MainActivity. The SDK merges it onto ${applicationId}.MainActivity. |
resizeableActivity="true" | No. Not merged onto MainActivity; Android already defaults this to true on API 24+. Minimize PiP uses SDK AlaznahPipActivity, which already has it. |
exported="true" | Yes on the launcher Activity (RN template). Unrelated to PiP. |
Add the PiP flags yourself only if the launcher Activity is not named MainActivity. Then rebuild the native app.
If Home PiP still never starts: confirm the merged manifest has supportsPictureInPicture on the real launcher class, you rebuilt after installing @alaznah/calling, and you are on Android 8+ with a connected video call — Picture in Picture.
Still stuck?
Contact support with:
- App ID / project id
- Platform + OS version
@alaznah/callingversion- Foreground vs background scenario
- Relevant logs (no secrets)