cometchat-android-v5-calls-sdk

Ground truth: com.cometchat:calls-sdk-android:5.0.4 + catalog android-calls-v5.json (the CLOSED list, javap-verified on the installed AAR). Docs: /calls/android/** = v5 · Docs MCP. Fetch builder options, callback lists and filters from the docs (references/docs-map.md) — never memory. ⚠️ Where docs and AAR disagree, the AAR wins (drift list in references/pitfalls.md). APPEND to the user's app — additive wiring only (RULES.md). HEADLESS path (no UI Kit); for the prebuilt call UI use cometchat-android-v6-calls.

Companion skills (read first)

• Standalone/headless entry — owns its own artifact (the Calls SDK), no -core sibling.
• 1:1 RINGING only also drives the Chat SDK (com.cometchat:chat-sdk-android:5.0.5) for signaling — references/ringing.md; deeper Chat-SDK usage: cometchat-android-v5-sdk.
• Prefer the UI Kit? Chat + a prebuilt call UI ⇒ cometchat-android-v6-core + cometchat-android-v6-calls, not this skill.

Use this skill when

"add calling from scratch / without the UI Kit", "standalone voice/video on Android", "build my own call screen", "headless calls SDK", "meeting room join by session id", "one-on-one ringing call". Precondition: the caller chose the from-scratch / standalone path (prebuilt call UI ⇒ see Companion skills).

Prerequisites & install

// settings.gradle(.kts) → dependencyResolutionManagement.repositories
maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
// app/build.gradle.kts
implementation("com.cometchat:calls-sdk-android:5.0.4")    // meet-style needs ONLY this (+ the two RN lines below)
implementation("com.cometchat:chat-sdk-android:5.0.5")     // + this for 1:1 RINGING (signaling)
implementation("com.facebook.react:react-android:0.77.2")  // the SDK's embedded RN runtime — see "SoLoader" below
implementation("com.facebook.soloader:soloader:0.12.1")    // (versions = what calls-sdk-android 5.0.4 pulls)

# gradle.properties — REQUIRED for the 1:1 RINGING path (chat-sdk-android 5.0.5 still pulls android.arch.lifecycle:extensions:1.1.1 → support-compat 26.1.0)
android.useAndroidX=true
android.enableJetifier=true
org.gradle.jvmargs=-Xmx4096m   # REQUIRED: Jetifier transforms the embedded react-android AAR — the AS-default -Xmx2048m OOMs (AUDIT-225)

<!-- AndroidManifest.xml, inside <application> — REQUIRED for background handling: the AAR declares NO <service> -->
<service android:name="com.cometchat.calls.services.CometChatOngoingCallService"
    android:exported="false"
    android:foregroundServiceType="camera|microphone|mediaPlayback" />

Full error-text evidence for the four build gates below (minSdk, <service>, Jetifier, heap): references/build-truth.md.

• minSdk 26 — the manifest merge is the floor. calls-sdk-android:5.0.4 pulls react-native-svg at minSdkVersion 26; a 24/25 app fails process*MainManifest. Docs now agree (AUDIT-229) — raise minSdk first.
• The <service> above is REQUIRED. The 5.0.4 AAR merges permissions only; without YOUR declaration CometChatOngoingCallService.launch(activity) fails silently (call dies on Home). Docs ship the <service> block (corrected upstream, verified 2026-09-09).
• Jetifier (ringing only). Without android.enableJetifier=true, an AndroidX app + chat-sdk-android fails checkDebugDuplicateClasses. Meet-style needs none.
• ⚠️ Gradle heap -Xmx4096m (MANDATORY — the FIRST build OOMs, meet-style too, AUDIT-225). The AS-default -Xmx2048m OOMs Jetifier transforming the embedded react-android AAR; the gradle.properties line above fixes it.
• ⚠️ SoLoader (MANDATORY on 5.0.x; a REQUIRED skill step — the SDK doesn't self-init on the joinSession path). The call surface is an embedded React Native 0.77; without the merged-mapping init joinSession crashes the process (UnsatisfiedLinkError: … "libhermes_executor.so" not found). Add ONCE, first in Application.onCreate() (hence the two RN artifacts on YOUR compile classpath):

  import com.cometchat.calls.core.CometChatCalls
  import com.facebook.react.soloader.OpenSourceMergedSoMapping
  import com.facebook.soloader.SoLoader
  
  SoLoader.init(this, OpenSourceMergedSoMapping)   // Application.onCreate(), BEFORE CometChatCalls.initFromSettings — idempotent
  

• Manifest: the AAR merges the call permissions (INTERNET, CAMERA, RECORD_AUDIO, FOREGROUND_SERVICE_*, POST_NOTIFICATIONS, …) — but NOT the <service> above. Java 11 compileOptions.
• Runtime permissions are YOURS to request (API 23+): CAMERA + RECORD_AUDIO (video) / RECORD_AUDIO (voice) before joinSession. Denied ⇒ tell the user; never join silently muted.
• Credentials: App ID · Region · Auth Key (dev only) live in the gitignored app/src/main/assets/cometchat-settings.json (same file the chat core uses; shape → references/docs-map.md § DOCS-GAP). Fetch via the CLI — npx @cometchat/skills-cli@3 auth login → provision use --app-id <id> --json (@3 pins the CLI major that matches the v5 skills) — or paste from Dashboard → Credentials. Mint auth tokens server-side for production; never ship the Auth Key.