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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

Logout

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)

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:

<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:

<!-- 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:

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:

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.