Installation & Setup
| Symptom | Cause | Fix |
|---|---|---|
pod install fails | CocoaPods version too old or spec repo outdated | Run pod repo update and ensure CocoaPods 1.10+ |
| SPM resolution fails | Incorrect package URL or version | Verify the package URL and version in Xcode’s package dependencies |
init() fails silently | Invalid App ID or Region | Double-check credentials from the CometChat Dashboard |
| Linker errors after install | Missing frameworks | Ensure CometChatCallsSDK is added to “Frameworks, Libraries, and Embedded Content” |
Authentication
| Symptom | Cause | Fix |
|---|---|---|
login() fails with invalid UID | UID doesn’t exist in CometChat | Create the user via Dashboard or REST API first |
| Auth token expired | Token has a limited lifetime | Generate a new auth token and call login() again |
login() called before init() | SDK not initialized | Always call init() and wait for completion before calling login() |
Joining a Session
| Symptom | Cause | Fix |
|---|---|---|
generateToken() fails | User not logged in or invalid session ID | Ensure login() completes before generating a token |
| Session joins but no audio/video | Permissions not granted | Request camera and microphone permissions via AVCaptureDevice.requestAccess |
joinSession() throws error | Invalid or expired token | Generate a fresh token using generateToken() before joining |
Audio & Video
| Symptom | Cause | Fix |
|---|---|---|
| No audio from remote participants | Audio session category misconfigured | Ensure AVAudioSession category is set to .playAndRecord with .defaultToSpeaker |
| Camera not working | Missing NSCameraUsageDescription in Info.plist | Add camera usage description to your Info.plist |
| Microphone not working | Missing NSMicrophoneUsageDescription in Info.plist | Add microphone usage description to your Info.plist |
CallKit & VoIP
| Symptom | Cause | Fix |
|---|---|---|
| VoIP push notifications not received | Missing VoIP certificate or entitlement | Enable Push Notifications and Voice over IP in Xcode capabilities. See VoIP Calling |
| CallKit UI not showing | CallKit not configured | Implement CXProvider delegate and report incoming calls. See VoIP Calling |
| Call drops when app enters background | Background mode not enabled | Enable “Audio, AirPlay, and Picture in Picture” and “Voice over IP” background modes |