cometchat-android-v5-core

---
name: cometchat-android-v5-core
description: "Foundational rules for CometChat Android UI Kit v5. Initialization, login, UIKitSettings builder, dependency setup, and anti-patterns. Read this first."
license: "MIT"
compatibility: "Android 7.0+; Java 8+; Kotlin 1.8+; com.cometchat:chat-uikit-android:5.x"
metadata:
  author: "CometChat"
  version: "3.0.0"
  tags: "chat cometchat android core rules initialization login builder patterns"
---

> **Ground truth:** `com.cometchat:chat-uikit-android:5.x` (+ `chat-sdk-android:4.x`, `calls-sdk-android:5.x`) — `javap` the resolved AARs from the Gradle cache + `docs/ui-kit/android`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). V5 is legacy/maintenance-only (V6 is current); verify symbols against the resolved AAR.

> **Companion skills:** `cometchat-android-v5-components` provides the component
> catalog (what exists); `cometchat-android-v5-placement` covers where to put
> chat in your app; `cometchat-android-v5-theming` covers visual customization.

## Purpose

This is the foundational skill for every CometChat Android UI Kit v5 integration. It teaches how CometChat works on Android — initialization, login, the UIKitSettings builder, Gradle dependency setup, manifest permissions, and the anti-patterns that silently break integrations.

**Read this skill first, before any component or placement skill.**

---

## Use this skill when

- Setting up CometChat in a new Android project
- Initializing the SDK (`CometChatUIKit.init`)
- Logging in / logging out users
- Configuring `UIKitSettings` via the builder
- Adding Gradle dependencies
- Debugging init or login failures
- "How do I set up CometChat?"
- "CometChat isn't initializing"

## Do not use this skill when

- Customizing component appearance → use `cometchat-android-v5-theming`
- Adding a specific feature (calls, reactions) → use `cometchat-android-v5-features`
- Writing custom message templates → use `cometchat-android-v5-customization`
- Diagnosing runtime crashes → use `cometchat-android-v5-troubleshooting`

---

## 1. Gradle Dependencies

Add the CometChat UI Kit dependency to your app-level `build.gradle`:

```groovy
dependencies {
    implementation 'com.cometchat:chat-uikit-android:5.+'
}
```

The UI Kit transitively pulls in the CometChat Chat SDK. For voice/video calling, add the calling SDK separately:

```groovy
dependencies {
    implementation 'com.cometchat:chat-uikit-android:5.+'
    implementation 'com.cometchat:calls-sdk-android:5.0.+'  // optional — only for calls (V5 calls SDK = 5.x; matches cometchat-android-v5-calls)
}
```

Ensure your project-level `build.gradle` includes the CometChat Maven repository:

```groovy
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://dl.cloudsmith.io/public/cometchat/cometchat/maven/" }
    }
}
```

**Min SDK:** 24 (Android 7.0). **Compile SDK:** 34+. **Java:** 8+. **Kotlin:** 1.8+.

> **⚠️ Important:** Always use the published Maven artifact (`com.cometchat:chat-uikit-android:5.+`). Never use `implementation project(':chatuikit')` or other local module references — those are only for CometChat's own internal development. The Chat SDK (`com.cometchat:chat-sdk-android`) is transitively included by the UI Kit, so you do not need to add it separately.

### 1a. AndroidX + Jetifier (REQUIRED — non-negotiable)

The CometChat Chat SDK transitively depends on the legacy `com.android.support:support-compat` library. Modern Android Studio projects (Arctic Fox+) default to `androidx.core` instead. Without Jetifier, Gradle sees the same classes (`android.support.v4.os.ResultReceiver`, etc.) declared in both libraries and fails the build with:

```
Duplicate class android.support.v4.os.ResultReceiver$1 found in modules
  core-1.16.0.aar -> core-1.16.0-runtime (androidx.core:core:1.16.0)
  and support-compat-26.1.0.aar -> support-compat-26.1.0-runtime
  (com.android.support:support-compat:26.1.0)
```

**Add these two lines to `gradle.properties` at the project root** before any UI Kit code is wired in:

```properties
android.useAndroidX=true
android.enableJetifier=true
```

Both are **mandatory**. Jetifier rewrites the legacy `android.support.*` references in the CometChat SDK's transitive deps to their `androidx.*` equivalents at build time, so the duplicate-class error doesn't happen.

A freshly-created Android Studio project usually has `android.useAndroidX=true` already (Arctic Fox+) but **Jetifier is OFF by default** since it's deprecated in newer SDK landscapes. The CometChat V5 SDK still needs it. If `gradle.properties` doesn't have either line, append both. If it has `useAndroidX=true` but no Jetifier line, add the Jetifier line. Idempotent.

---

## 2. Initialization

CometChat must be initialized exactly once before any UI component is used. Initialization is asynchronous and must complete fully before mounting any `CometChat*` view.

### The UIKitSettingsBuilder

**Java:**
```java
import com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit;
import com.cometchat.chatuikit.shared.cometchatuikit.UIKitSettings;

UIKitSettings uiKitSettings = new UIKitSettings.UIKitSettingsBuilder()
    .setAppId(APP_ID)           // Required. String from the CometChat dashboard.
    .setRegion(REGION)          // Required. "us", "eu", "in", etc.
    .setAuthKey(AUTH_KEY)       // Required for dev mode. Omit in production.
    .subscribePresenceForAllUsers()  // Optional — enables online/offline indicators.
    .build();
```

**Kotlin:**
```kotlin
import com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit
import com.cometchat.chatuikit.shared.cometchatuikit.UIKitSettings

val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
    .setAppId(APP_ID)
    .setRegion(REGION)
    .setAuthKey(AUTH_KEY)
    .subscribePresenceForAllUsers()
    .build()
```

### UIKitSettingsBuilder — full method reference

| Method | Type | Description |
|---|---|---|
| `setAppId(String)` | Required | CometChat App ID from the dashboard |
| `setRegion(String)` | Required | Region: `"us"`, `"eu"`, `"in"` |
| `setAuthKey(String)` | Dev only | Auth Key for client-side login. Omit in production. |
| `subscribePresenceForAllUsers()` | Optional | Subscribe to presence for all users |
| `subscribePresenceForFriends()` | Optional | Subscribe to presence for friends only |
| `subscribePresenceForRoles(List<String>)` | Optional | Subscribe to presence for specific roles |
| `setAutoEstablishSocketConnection(Boolean)` | Optional | Auto-connect WebSocket. Default: `true` |
| `setAIFeatures(List<AIExtensionDataSource>)` | Optional | Custom AI features list. Default: built-in AI features |
| `setExtensions(List<ExtensionsDataSource>)` | Optional | Custom extensions list. Default: built-in extensions |
| `setDateTimeFormatterCallback(DateTimeFormatterCallback)` | Optional | Custom date/time formatting |
| `overrideAdminHost(String)` | Advanced | Override admin API host |
| `overrideClientHost(String)` | Advanced | Override client API host |

### Init call

**Java:**
```java
CometChatUIKit.init(context, uiKitSettings, new CometChat.CallbackListener<String>() {
    @Override
    public void onSuccess(String s) {
        // SDK initialized — safe to login and use components
    }

    @Override
    public void onError(CometChatException e) {
        // Handle init failure
    }
});
```

**Kotlin:**
```kotlin
CometChatUIKit.init(context, uiKitSettings, object : CometChat.CallbackListener<String>() {
    override fun onSuccess(s: String) {
        // SDK initialized — safe to login and use components
    }

    override fun onError(e: CometChatException) {
        // Handle init failure
    }
})
```

### Init must happen once

Call `CometChatUIKit.init()` in your `Application.onCreate()` or your launcher `Activity.onCreate()`. Use `CometChatUIKit.isSDKInitialized()` to guard against double-init:

**Java:**
```java
if (!CometChatUIKit.isSDKInitialized()) {
    CometChatUIKit.init(this, uiKitSettings, new CometChat.CallbackListener<String>() {
        @Override
        public void onSuccess(String s) {
            // proceed to login
        }

        @Override
        public void onError(CometChatException e) {
            // show error
        }
    });
}
```

---

## 3. Login

### Development mode

Use `CometChatUIKit.login(uid, callback)` with a test UID. Every new CometChat app comes with five pre-created test users: `cometchat-uid-1` through `cometchat-uid-5`.

**Java:**
```java
if (CometChatUIKit.getLoggedInUser() == null) {
    CometChatUIKit.login("cometchat-uid-1", new CometChat.CallbackListener<User>() {
        @Override
        public void onSuccess(User user) {
            // Navigate to chat screen
        }

        @Override
        public void onError(CometChatException e) {
            // Handle login failure
        }
    });
}
```

**Kotlin:**
```kotlin
if (CometChatUIKit.getLoggedInUser() == null) {
    CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
        override fun onSuccess(user: User) {
            // Navigate to chat screen
        }

        override fun onError(e: CometChatException) {
            // Handle login failure
        }
    })
}
```

### Production mode

Use `CometChatUIKit.loginWithAuthToken(token, callback)` with a token obtained from your backend. The backend generates the token using the CometChat REST API with your REST API Key (not the client-side Auth Key).

**Java:**
```java
CometChatUIKit.loginWithAuthToken(authToken, new CometChat.CallbackListener<User>() {
    @Override
    public void onSuccess(User user) {
        // Navigate to chat screen
    }

    @Override
    public void onError(CometChatException e) {
        // Handle login failure
    }
});
```

### Getting the current logged-in user

```java
User currentUser = CometChatUIKit.getLoggedInUser();
if (currentUser != null) {
    String uid = currentUser.getUid();
}
```

### Logout

**Java:**
```java
CometChatUIKit.logout(new CometChat.CallbackListener<String>() {
    @Override
    public void onSuccess(String s) {
        // Navigate to login screen
    }

    @Override
    public void onError(CometChatException e) {
        // Handle logout failure
    }
});
```

### Create user (dev mode only)

```java
User user = new User();
user.setUid("user-123");
user.setName("John Doe");

CometChatUIKit.createUser(user, new CometChat.CallbackListener<User>() {
    @Override
    public void onSuccess(User user) { }

    @Override
    public void onError(CometChatException e) { }
});
```

---

## 4. CometChatUIKit — full public API

| Method | Signature | Description |
|---|---|---|
| `init` | `static void init(Context, UIKitSettings, CallbackListener<String>)` | Initialize the SDK |
| `login` | `static void login(String uid, CallbackListener<User>)` | Login with UID (dev mode) |
| `loginWithAuthToken` | `static void loginWithAuthToken(String token, CallbackListener<User>)` | Login with auth token (production) |
| `logout` | `static void logout(CallbackListener<String>)` | Logout current user |
| `getLoggedInUser` | `static User getLoggedInUser()` | Get current logged-in user (null if none) |
| `isSDKInitialized` | `static boolean isSDKInitialized()` | Check if SDK is initialized |
| `createUser` | `static void createUser(User, CallbackListener<User>)` | Create a new user (dev mode) |
| `sendTextMessage` | `static void sendTextMessage(TextMessage, CallbackListener<TextMessage>)` | Send a text message |
| `sendMediaMessage` | `static void sendMediaMessage(MediaMessage, CallbackListener<MediaMessage>)` | Send a media message |
| `sendCustomMessage` | `static void sendCustomMessage(CustomMessage, CallbackListener<CustomMessage>)` | Send a custom message |
| `sendFormMessage` | `static void sendFormMessage(FormMessage, boolean, CallbackListener<FormMessage>)` | Send a form message |
| `sendSchedulerMessage` | `static void sendSchedulerMessage(SchedulerMessage, boolean, CallbackListener<SchedulerMessage>)` | Send a scheduler message |

---

## 5. Manifest Permissions

Add these to your `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- For media messages -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

<!-- For voice notes and calls -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.CAMERA" />

<!-- For push notifications (Android 13+) -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

---

## 5b. App Theme Requirement

CometChat UI Kit v5 ships its own theme (`CometChatTheme.DayNight`) which itself inherits from `Theme.MaterialComponents.DayNight.NoActionBar` (Material 2 — see the kit's own `chatuikit/src/main/res/values/themes.xml`). Your app's theme **must** inherit from `CometChatTheme.DayNight` so the kit's attribute set is in scope. Using `Theme.AppCompat.*` (which lacks Material attributes the kit relies on) leads to attribute-resolution failures at inflate time.

**Recommended — use CometChat's built-in theme as parent:**
```xml
<!-- res/values/themes.xml -->
<style name="AppTheme" parent="CometChatTheme.DayNight">
    <!-- Your customizations -->
    <item name="colorPrimary">@color/your_brand_color</item>
</style>
```

**Do NOT inherit from `Theme.AppCompat.*`** — it doesn't pull in the Material attributes the UI Kit reads at inflate time, and you'll see `UnsupportedOperationException: Failed to resolve attribute`. Inheriting directly from `Theme.MaterialComponents.*` works at runtime but you lose the kit's preconfigured color tokens — prefer `CometChatTheme.DayNight` so both the kit's defaults and your overrides apply cleanly.

> **Material 2 vs Material 3.** The kit currently parents on Material 2 (`Theme.MaterialComponents.DayNight.NoActionBar`). Do NOT switch to `Theme.Material3.*` as your app theme parent — the kit's resource attrs are resolved against the Material 2 namespace; mixing in Material 3 leaves some attributes undefined and triggers the same `UnsupportedOperationException` at inflate.

---

## 6. Typical init + login flow (complete example)

This is the pattern used in the sample apps. Place it in your launcher Activity:

**Java:**
```java
public class SplashActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        UIKitSettings uiKitSettings = new UIKitSettings.UIKitSettingsBuilder()
            .setAppId("YOUR_APP_ID")
            .setRegion("us")
            .setAuthKey("YOUR_AUTH_KEY")
            .subscribePresenceForAllUsers()
            .build();

        CometChatUIKit.init(this, uiKitSettings, new CometChat.CallbackListener<String>() {
            @Override
            public void onSuccess(String s) {
                if (CometChatUIKit.getLoggedInUser() != null) {
                    startActivity(new Intent(SplashActivity.this, HomeActivity.class));
                    finish();
                } else {
                    startActivity(new Intent(SplashActivity.this, LoginActivity.class));
                    finish();
                }
            }

            @Override
            public void onError(CometChatException e) {
                Toast.makeText(SplashActivity.this, "Init failed: " + e.getMessage(), Toast.LENGTH_LONG).show();
            }
        });
    }
}
```

**Kotlin:**
```kotlin
class SplashActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
            .setAppId("YOUR_APP_ID")
            .setRegion("us")
            .setAuthKey("YOUR_AUTH_KEY")
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(this, uiKitSettings, object : CometChat.CallbackListener<String>() {
            override fun onSuccess(s: String) {
                if (CometChatUIKit.getLoggedInUser() != null) {
                    startActivity(Intent(this@SplashActivity, HomeActivity::class.java))
                } else {
                    startActivity(Intent(this@SplashActivity, LoginActivity::class.java))
                }
                finish()
            }

            override fun onError(e: CometChatException) {
                Toast.makeText(this@SplashActivity, "Init failed: ${e.message}", Toast.LENGTH_LONG).show()
            }
        })
    }
}
```

---

## 7. Anti-patterns

| Anti-pattern | Why it breaks | Fix |
|---|---|---|
| Calling `login()` before `init()` completes | SDK not ready, login silently fails or throws | Always call `login()` inside `init()`'s `onSuccess` |
| Double `init()` calls | Wastes resources, can cause race conditions | Guard with `CometChatUIKit.isSDKInitialized()` |
| Hardcoding Auth Key in production | Anyone can decompile your APK and login as any user | Use `loginWithAuthToken()` with server-minted tokens |
| Using UI components before login | Components require a logged-in user to fetch data | Always verify `getLoggedInUser() != null` before showing chat UI |
| Missing INTERNET permission | SDK can't reach CometChat servers | Add `<uses-permission android:name="android.permission.INTERNET" />` |
| Wrong region string | SDK connects to wrong datacenter, gets 404s | Use exact region from dashboard: `"us"`, `"eu"`, `"in"` |
| Calling `init()` in every Activity | Redundant, wastes network calls | Call once in `Application.onCreate()` or launcher Activity |
| Using `Theme.AppCompat.*` or `Theme.Material3.*` as app theme | The kit's attrs are resolved against Material 2 (which `CometChatTheme.DayNight` inherits from); mixing namespaces fails with `UnsupportedOperationException` at inflate time | Inherit from `CometChatTheme.DayNight` |
| Using `implementation project(':chatuikit')` for the UI Kit dependency | Local module references only work inside CometChat's own monorepo; external apps can't resolve the module | Use `implementation 'com.cometchat:chat-uikit-android:5.+'` from the CometChat Maven repository |
| Forgetting `android.useAndroidX=true` + `android.enableJetifier=true` in `gradle.properties` | CometChat SDK's transitive `com.android.support` deps collide with the project's `androidx.core` → "Duplicate class android.support.v4.os.ResultReceiver$1" build failure | See § 1a — both lines mandatory in every greenfield Android Studio integration |

---

## Hard rules

- **Init once, login once.** `CometChatUIKit.init()` must be called exactly once before any UI component is used. `login()` must be called inside `init()`'s `onSuccess`.
- **Always check `getLoggedInUser()`.** Before navigating to any chat screen, verify the user is logged in.
- **Never hardcode Auth Key in production.** Use `loginWithAuthToken()` with server-side token generation.
- **INTERNET permission is mandatory.** Without it, the SDK silently fails.
- **All UI components require a logged-in user.** Mounting `CometChatConversations`, `CometChatMessageList`, etc. without a logged-in user results in empty views or crashes.
- **App theme must inherit from `CometChatTheme.DayNight`.** The kit itself parents on `Theme.MaterialComponents.DayNight.NoActionBar` (Material 2). Inheriting from `Theme.AppCompat.*` or `Theme.Material3.*` triggers `UnsupportedOperationException: Failed to resolve attribute` at inflate time.
- **Always use the published Maven artifact for dependencies, never local project modules.** Use `implementation 'com.cometchat:chat-uikit-android:5.+'` — never `implementation project(':chatuikit')`. Local module references only apply to CometChat's own internal sample apps. External apps must always depend on the published artifact from the CometChat Maven repository.
- **`gradle.properties` MUST contain `android.useAndroidX=true` AND `android.enableJetifier=true`.** Both lines, no exceptions. The CometChat V5 Android SDK transitively depends on the legacy `com.android.support:support-compat`. Without Jetifier rewriting those references to `androidx.*` at build time, Gradle hits "Duplicate class android.support.v4.os.ResultReceiver$1" and the build fails. Modern Android Studio scaffolds set `useAndroidX=true` by default but leave Jetifier off — the integration must add the Jetifier line. Idempotent — if both lines are already present, no change.

## Visual Builder integration

**Android V5 is the primary home for Visual Builder integration.** The canonical repo at the Android Visual Builder ZIP (download from https://preview.cometchat.com/downloads/cometchat-builder-android.zip) ships **V5-shaped code** — `com.cometchat:chat-uikit-android:5.2.6` + `com.cometchat:calls-sdk-android:4.3.1`. The Gradle plugin `com.cometchat.builder.settings:5.0.1` auto-generates a `CometChatBuilderSettings` constants class from `cometchat-builder-settings.json` at build time. The plugin's output is plain Kotlin `object` declarations — usable from both V5 Views (the canonical path) and V6 Compose / Kotlin Views code, though V6 deps need to be added separately to a V6 project.

> **➡️ FOLLOW THE FULL RECIPE IN `cometchat-android-v6-core` §"Visual Builder integration" AS-IS.** That page holds the complete validated content (`builder export` flow, the Place + patch table, the F50/F51 `BuilderSettingsHelper.kt` transforms, the default Views `MessagesActivity` surface, the Files-patched table). Both skills reference the same V5-shaped canonical, so V5 customers follow it verbatim — it targets V5 deps natively (no shim needed). The only V5-specific deltas are listed under "Differences" below.

Validated 2026-05-21 against builder-plugin 5.0.1: `./gradlew :chat-builder:assembleDebug` produces `chat-builder-debug.apk` after applying:
- **`settings.gradle.kts` — add the Cloudsmith Maven repo `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to BOTH `pluginManagement.repositories` AND `dependencyResolutionManagement.repositories`.** Without it in `pluginManagement`, the `com.cometchat.builder.settings:5.0.1` plugin fails to resolve (`Plugin [id: 'com.cometchat.builder.settings', version: '5.0.1'] was not found`); without it in `dependencyResolutionManagement`, the `chat-uikit-android` / `calls-sdk-android` artifacts fail to resolve. This matches the canonical repo's `settings.gradle.kts` (Cloudsmith present in both blocks).
- Envelope-wrapped `cometchat-builder-settings.json` (`{ builderId, name, settings: {...} }` — NOT raw settings blob)
- Two missing-field defaults injected pre-write: `chatFeatures.deeperUserEngagement.mentionAll: true` + `chatFeatures.inAppSounds: { incomingMessageSound: true, outgoingMessageSound: true }`
- `android.enableJetifier=true` in `gradle.properties`
- `@style/CometChat.Builder.Theme` set on `<application>` in `AndroidManifest.xml`

Differences from the V6 page's recipe text:
- V5 calls integration uses `cometchat-android-v5-calls` patterns (see [[project_v6_calls_sdk_still_required]] for context — V5 customers don't hit the V6-specific workarounds, but the calls SDK requirement is the same).
- The Compose stack split (`chatuikit-compose-android` vs `chatuikit-kotlin-android`) doesn't apply to V5 — the V5 UI Kit is Kotlin Views only.