diff --git a/ANDROID-DOCS-AUDIT.md b/ANDROID-DOCS-AUDIT.md new file mode 100644 index 000000000..a84ef5f89 --- /dev/null +++ b/ANDROID-DOCS-AUDIT.md @@ -0,0 +1,418 @@ +# Android docs audit — UI Kit v6 + Chat SDK v5 + +Every entry below was found by **mechanically diffing the docs against the shipped source**, not by +reading. Each row names the source file + line that proves it. Raised while building the Android +skill pack (Linear ENG-38207). + +## Source of truth used +| Surface | Repo / artifact | Version | +|---|---|---| +| UI Kit v6 | `cometchat-team/uikit-android` — `chatuikit-kotlin`, `chatuikit-compose`, `chatuikit-core` | 6.0.5 (`master-v6`) | +| Chat SDK v5 | `cometchat-team/chat-sdk-android` (+ installed AAR) | 5.0.5 | + +**Method:** extract every `.setX(...)` call from each page's `Kotlin (XML Views)` tab → check it +against every `fun` declared in the three kit modules → subtract Android-framework methods. 120 +documented setters checked; the misses below are what remained. + +**Reproduce:** `python3` extractor in the ENG-38207 working notes; re-runnable against any kit tag. + +--- + +## A. Wrong method name — documented call does not compile +| # | Page | Docs say | Shipped 6.0.5 | Evidence | +|---|---|---|---|---| +| A1 | `ui-kit/android/incoming-call` | `setOnAcceptClick { }` | `setOnAcceptClickListener(OnClick?)` | `chatuikit-kotlin/.../incomingcall/CometChatIncomingCall.kt:489` | +| A2 | `ui-kit/android/incoming-call` | `setOnRejectClick { }` | `setOnRejectClickListener(OnClick?)` | `…/incomingcall/CometChatIncomingCall.kt:507` | +| A3 | `ui-kit/android/outgoing-call` | `setOnEndCallClick { }` | `setOnEndCallClickListener(OnClick?)` | `…/outgoingcall/CometChatOutgoingCall.kt:493` | +| A4 | `ui-kit/android/message-composer` | `setAuxiliaryButtonView(...)` | `setAuxiliaryButtonViewListener(MessageComposerViewHolderListener)` | `…/messagecomposer/ui/CometChatMessageComposer.kt:5627` | +| A5 | `ui-kit/android/guide-ai-agent` | `messageHeader.setNewChatButtonClick { }` | `setOnNewChatClick(() -> Unit)` | `…/messageheader/ui/CometChatMessageHeader.kt:627` | +| A6 | `ui-kit/android/guide-ai-agent` | `messageHeader.setChatHistoryButtonClick { }` | `setOnChatHistoryClick(() -> Unit)` | `…/messageheader/ui/CometChatMessageHeader.kt:631` | +| A7 | `ui-kit/android/guide-threaded-messages` | `messageList.setParentMessage(it.id)` | `setParentMessageId(Long)` | `…/messagelist/ui/CometChatMessageList.kt:1709` | +| A8 | `ui-kit/android/message-list` | `mentionFormatter.setMessageListMentionTextStyle(context, style)` | no such method — use `setIncomingBubbleMentionTextStyle` / `setOutgoingBubbleMentionTextStyle` | `…/shared/formatters/CometChatMentionsFormatter.kt:166,182` | + +## B. Wrong signature — right name, wrong arity/params +| # | Page | Docs say | Shipped 6.0.5 | Evidence | +|---|---|---|---|---| +| B1 | `guide-threaded-messages`, `message-list` | `setOnThreadRepliesClick { context, baseMessage, template -> }` (3 args) | `((BaseMessage) -> Unit)?` — **one** arg | `…/messagelist/ui/CometChatMessageList.kt:3727` | +| B2 | `ui-kit/android/message-composer` | `setOnSendButtonClick { context, baseMessage -> }` | `(String) -> Unit` — the typed text | `…/messagecomposer/ui/CometChatMessageComposer.kt:5395` | +| B3 | `ui-kit/android/message-composer` (Compose tab) | `onError = { context, exception -> }` | `((CometChatException) -> Unit)` — one arg | `chatuikit-compose/.../CometChatMessageComposer.kt` | + +## C. Removed API — page documents a v5 surface that no longer ships +| # | Page | Issue | Replacement in v6 | Evidence | +|---|---|---|---|---| +| C1 | `ui-kit/android/message-template` | **The whole page.** `CometChatMessageTemplate()`, `setType`, `setCategory`, `setBubbleView`, `setMessageReceipt`, `setTemplates` — none exist in 6.0.5 (only the unrelated `UIKitConstants.MessageTemplateId`) | **`BubbleFactory`** — subclass it (`getCategory()`, `getType()`, `createContentView()`, `bindContentView()`) and register with `messageList.setBubbleFactories(listOf(...))` | `chatuikit-kotlin/.../shared/messagebubble/BubbleFactory.kt`; registration at `…/messagelist/ui/CometChatMessageList.kt:3475` | + +## D. Stale guidance — compiles, but teaches the wrong default +| # | Page | Issue | Should be | +|---|---|---|---| +| D1 | `getting-started-kotlin`, `getting-started-jetpack` | Teach `UIKitSettings.UIKitSettingsBuilder()` + `CometChatUIKit.init(...)` with `APP_ID`/`AUTH_KEY` as **hardcoded source constants** | `CometChatUIKit.initFromSettings(context, callback)` reading a **gitignored** `app/src/main/assets/cometchat-settings.json`. The shipped kit implements it (`chatuikit-core/.../CometChatUIKit.kt:121`) and it persists `integrationSource` telemetry + auto-inits the Calls SDK. Hardcoded credentials in a sample are also a security-guidance problem. | +| D2 | `ui-kit/android/*` component pages | Most v6 component pages have **no "AI Integration Quick Reference"** accordion (35 of 68 pages do) | Backfill, so AI agents get prop/param tables without parsing prose | +| D3 | `sdk/android/v5/*` | **Zero** of the 61 v5 SDK pages carry the accordion (all 46 that exist are on the v4 root tree) | Backfill for v5 | + +## E. Missing artifacts +| # | Item | Status | +|---|---|---| +| E1 | `ui-kit/android/llms-android-v6.mdx` — scoped LLM index for the v6 UI Kit | **Added** (this branch) | +| E2 | `sdk/android/v5/llms-android-v5.mdx` — scoped LLM index for the v5 SDK | **Added** (this branch) | + +--- + +## New findings (added during the fix pass) +| # | Page | Docs say | Shipped 6.0.5 / SDK 5.0.5 | Evidence | +|---|---|---|---|---| +| A9 | `ui-kit/android/upgrading-from-v5` | `conversations.setViewModelFactory(factory)` | `setViewModel(viewModel)` — build the VM with `ViewModelProvider(this, factory)` | `…/conversations/ui/CometChatConversations.kt:887` | +| A10 | `ui-kit/android/upgrading-from-v5` | repository interface `ConversationsRepository` with `fetchConversations()` | `ConversationListRepository` with `getConversations(...)`, `deleteConversation(...)`, `markAsDelivered(...)`, `hasMoreConversations()` | `chatuikit-core/.../domain/repository/ConversationListRepository.kt:13` | +| B4 | `ui-kit/android/upgrading-from-v5` | V6 block: `composer.setOnSendButtonClick { context, message -> }` | `(String) -> Unit` | `…/CometChatMessageComposer.kt:5395` | +| A11 | `ui-kit/android/theme-introduction` (Compose tab) | `CometChatColorScheme.light().copy(...)` / `.dark().copy(...)` | **`lightColorScheme(...)` / `darkColorScheme(...)`** — top-level factories in `com.cometchat.uikit.compose.theme`, configured by **named params**; `CometChatColorScheme` is a plain class with no `.copy()`. Setting `primary` derives the whole extended ramp. | `chatuikit-compose/.../theme/CometChatColorScheme.kt:190,325` | +| S1 | `sdk/android/v5/typing-indicators` | `CometChat.endtyping(...)` — lowercase `t`, does not compile | `CometChat.endTyping(...)` | SDK source API index | +| S2 | `sdk/android/v5/typing-indicators` | 8 tab titles read `"Strat Typing"`; the stop-typing section was also mislabelled "Start" | `Start Typing` (§send) / `Stop Typing` (§end) | copy-edit | + +--- + +## Fix log — all applied on this branch +| # | Page | Change | Verified against | +|---|---|---|---| +| A1 | `incoming-call` | `setOnAcceptClick` → `setOnAcceptClickListener` (Views only; Compose `onAcceptClick` was already correct) | source + shipped AAR | +| A2 | `incoming-call` | `setOnRejectClick` → `setOnRejectClickListener` | source | +| A3 | `outgoing-call` | `setOnEndCallClick` → `setOnEndCallClickListener` | source | +| A4 | `message-composer` | `setAuxiliaryButtonView(view)` → `setAuxiliaryButtonViewListener(object : MessageComposerViewHolderListener { createView(context, user, group) })` | `:5627` + `MessageComposerViewHolderListener.kt:39` | +| A5 | `guide-ai-agent` | `setNewChatButtonClick` → `setOnNewChatClick` | source | +| A6 | `guide-ai-agent` | `setChatHistoryButtonClick` → `setOnChatHistoryClick` | source | +| A7 | `guide-threaded-messages` | `messageList.setParentMessage(id)` → `setParentMessageId(id)` (×2; `viewModel.`/`header.setParentMessage` left alone — both correct) | source | +| A8 | `message-list` | `setMessageListMentionTextStyle` → `setIncomingBubbleMentionTextStyle` + `setOutgoingBubbleMentionTextStyle` | `CometChatMentionsFormatter.kt:166,182` | +| A9 | `upgrading-from-v5` | `setViewModelFactory(factory)` → `ViewModelProvider(this, factory)` + `setViewModel(vm)` | source | +| A10 | `upgrading-from-v5` | `ConversationsRepository.fetchConversations()` → `ConversationListRepository.getConversations()` | source | +| B1 | `guide-threaded-messages`, `message-list`, `upgrading-from-v5` | thread callback 3-arg → **1-arg** `{ baseMessage -> }` in **both** cohorts (V5 Java "before" blocks left intact) | Views `:3727`, Compose `:604` | +| B2 | `message-composer` | Views `setOnSendButtonClick { context, baseMessage -> }` → `{ text -> }` (Compose 2-arg form is correct, untouched) | `:5395` / Compose `:268` | +| B4 | `upgrading-from-v5` | same fix in the V6 "after" block | `:5395` | +| C1 | `message-template` | Added a verified `` — the page's API is absent from the shipped artifact; documented the real `BubbleFactory` + `setBubbleFactories` replacement with a source-accurate example. **Full page rewrite still owed.** | shipped AAR: no `MessageTemplate`, has `BubbleFactory` | +| S1 | `sdk/.../typing-indicators` | `CometChat.endtyping` → `endTyping` | SDK source | +| S2 | `sdk/.../typing-indicators` | `"Strat Typing"` → `Start`/`Stop Typing` (8 titles) | copy-edit | +| A11 | `theme-introduction` | `CometChatColorScheme.light()/.dark()` + `.copy()` → `lightColorScheme(...)`/`darkColorScheme(...)` with named params (4 sites) | source + **compile-proved** in harness fixture `skill-compose-families` | + +## Behaviour gaps (found by the SKILL⇄DOCS⇄SOURCE audit, not by compiling) +| # | Page | Gap | Fix | +|---|---|---|---| +| BEH-1 | `ui-kit/android/group-members` | The kit enforces a **member permission matrix** before opening the long-press menu (owner/admin/moderator/participant, plus "a moderator cannot assign admin"). The page documented scope *filtering* and *badges* but never the matrix — unknowable from the docs alone. | Added a **"Member Permissions"** section with the matrix, the scope constants, and a `` about `updateGroupMemberScope(UID, GUID, …)` vs `transferGroupOwnership(GUID, UID, …)` having **reversed** parameter order. | + +Tracked with the skill-side fixes in `cometchat-skills/THREE-WAY-AUDIT.md`. + +--- + +## Round 2 — the three-way audit (skills ↔ docs ↔ source) + +`test-suite/scripts/three-way-audit.mjs` in the skills repo compares three independent claims about +the same API. **Source is the arbiter** — the installed UI Kit, Chat SDK, Calls SDK and Cards SDK. + +| Disagreement | Meaning | Who fixes | +|---|---|---| +| in SOURCE + DOCS, not in SKILLS | skill under-teaches a real API | skill | +| in SOURCE + SKILLS, not in DOCS | docs under-teach a real API | docs | +| in DOCS or SKILLS, **not in SOURCE** | **phantom** — taught but ships nowhere | whoever teaches it | + +### Phantoms fixed in this round +| # | Page | Docs said | Shipped | Evidence | +|---|---|---|---|---| +| R1 | `ui-kit/android/group-members` | `getSelectedGroupMembers()` | **`getSelectedMembers()`** (+ `setOnSelection {}` to observe) | `CometChatGroupMembers.kt:772,1211` | +| R2 | `ui-kit/android/custom-text-formatter-guide`, `shortcut-formatter-guide`, `message-composer` | `CometChatUIKit.getDataSource().getTextFormatters(...)` / `.getAuxiliaryOption(...)` | **`getDataSource()` was removed after V5** — build the formatter list yourself and pass it to `setTextFormatters(...)`; the auxiliary slot has no "fetch the defaults" API, an override REPLACES them | `javap` on the shipped `chatuikit-core` AAR: no `getDataSource` | +| R3 | `sdk/android/v5/delivery-read-receipts` | `message.getReceiverUID()` **and** `message.getRecieverUID()` — two different wrong spellings on one page | **`getReceiverUid()`** | `BaseMessage.java:297` | +| R4 | `sdk/android/v5/additional-message-filtering` | `.setAttachmemnt(...)` (typo) on a `MessagesRequestBuilder` | **`setAttachmentTypes(...)`** — matching the page's own prose | `MessagesRequest.java:1127` | +| R5 | `sdk/android/v5/flag-message` | `reason.getReason()` | **`reason.getName()`** (`FlagReason` has `getId`/`getName`/`getDescription`) | `FlagReason.java:194` | + +### False positives the audit itself had to learn (recorded so the next platform doesn't repeat them) +- **Calls SDK / Cards SDK.** `setCallCategory`, `setCardSchema`, `setThemeMode`, `setActionCallback` + are real — they ship in `calls-sdk-android` / `cards-android`, which the first pass didn't scan. + Without that, correct docs would have been "fixed" into incorrect ones. +- **V5 "before" blocks.** A ` ```java title="V5" ` fence in `upgrading-from-v5` *should* name removed + APIs; the audit now skips them. +- **Comment lines.** Warning that "X was removed" is documentation, not a claim X exists. +- **`sdk/android/v5/` is the CURRENT SDK.** An early version of the version filter excluded it and + silently audited **zero** SDK pages — which is why R3–R5 were invisible in round 1. + +### Standing result +`PHANTOM in SKILLS = 0` — no Android skill teaches an API that does not ship. The only remaining +docs phantoms are the four in `message-template.mdx`, the page already flagged (C1) for rewrite. + +### Skill gaps (not defects) +The audit reports ~216 real APIs the docs teach that the skills never name. That is the intended +**bake-vs-fetch** split: skills bake the hot path and route everything else to the docs `.md` twin +via `core/references/docs-map.md`. Listed for visibility, not as a backlog. + +--- + +## Round 3 — the fresh-app run (built + executed on an emulator) + +A NEW app was scaffolded from nothing, following **only** the skills, installed on a booted emulator +and driven by hand. Static audits cannot find these: they only appear when the app runs. + +| # | Symptom on a real device | Root cause | Docs fix | Skill fix | +|---|---|---|---|---| +| F1 | **Build fails**, ~40 `Duplicate class org.jetbrains.annotations.*` at dexing | The kit's own transitive chain: `chatuikit-kotlin-android` → `io.noties.markwon:syntax-highlight` → `io.noties:prism4j:2.0.0` → `org.jetbrains:annotations-java5:17.0.0`, colliding with `org.jetbrains:annotations:23.0.0` from AndroidX/Kotlin | `` + `exclude(group="org.jetbrains", module="annotations-java5")` added to **both** getting-started pages | added to the core skill's install block, marked REQUIRED | +| F2 | UI Kit toolbar renders **under the status bar** — "Chats" overlaps the clock | Every recipe calls `enableEdgeToEdge()` and **nothing** consumes the insets. Docs had **zero** occurrences of `setOnApplyWindowInsetsListener` | `` + the runnable inset snippet added to `conversation-message-view` and `one-to-one-chat` | core skill's Sizing section now carries the **code**, not just the words "+ inset padding" | +| F3 | `Intent(this, …)` inside the login callback **does not compile** | Inside `object : CometChat.CallbackListener()`, `this` binds to the listener, not the Activity. The skill's snippet only had `/* unlock the chat UI */`, so it never showed the navigation a consumer writes next | — (docs don't show navigation from the callback) | core skill now shows `this@MainActivity` with an inline warning | + +**Verified working after the fixes**, on device: `init OK → login OK` → conversations list renders +with real data (avatars, unread badges, receipts, presence) → tap opens the message screen for the +right entity → back returns → keyboard opens with the composer above it → **a message sends and is +delivered**. The `cometchatPrimaryColor` from the customization skill is visibly applied. + +F1 and F2 are worth raising with the kit team too: F1 is a dependency-hygiene issue in the published +artifact (a consumer should not need to know about `prism4j`), and F2 means every published Android +recipe produces a visibly broken status bar. + +--- + +## Round 4 — component-wise acceptance on the emulator + +Each drop-in was hosted alone, sized exactly as the skills prescribe, and driven on a booted +emulator. Evidence is the UI hierarchy (`uiautomator dump`), not a screenshot impression. + +| Component | Verdict | Evidence | +|---|---|---| +| `CometChatConversations` | ✅ renders | real rows, avatars, unread badges, receipts, presence dot | +| `CometChatUsers` | ✅ renders | title, `et_search`, real users (Bob Bob, Susan Marie) | +| `CometChatGroups` | ✅ renders | `groups_item_container`, `groups_avatar`, "CometChat Team Meeting" | +| `CometChatGroupMembers` | ✅ compiles + renders | emitted by a skills-only agent; see round 5 | +| `CometChatSearch` | ✅ renders | `chip_group` (Unread/Groups/Photos), `iv_back`, `initial_state_view` | +| `CometChatNotificationFeed` | ✅ renders | "Notifications" | +| `CometChatMessageHeader/List/Composer` | ✅ renders + sends | polls, image bubbles, moderation notice; message sent + delivered | +| **`CometChatCallLogs`** | ❌ **CRASHES** | see C-1 | + +### C-1 — `CometChatCallLogs` requires the Calls SDK **and** calling to be initialized (DOCS gap) +``` +java.lang.NoClassDefFoundError: Failed resolution of: + Lcom/cometchat/calls/core/CallLogRequest$CallLogRequestBuilder; + at com.cometchat.uikit.core.viewmodel.CometChatCallLogsViewModel.(CometChatCallLogsViewModel.kt:97) +``` +**This is a documentation gap, NOT a product defect.** Two distinct runtime states, both expected: + +| Calls artifact | `uiKit.enableCalling` | Result | +|---|---|---| +| absent | anything | `NoClassDefFoundError` — correct JVM behaviour for a missing dependency | +| present | `false` | `RuntimeException: Please call the CometChatCalls.init() method …` — thrown **deliberately by the Calls SDK** (`com.cometchat.calls.core.ApiConnection.getInstance`) as actionable guidance | +| present | `true` | renders | + +Neither is the UI Kit misbehaving: a missing library cannot work, and the Calls SDK's message names +its own fix. The defect is that **`call-logs.mdx` documented the component with zero mention that the +Calls SDK is required at all** — a reader following only that page hits a runtime failure with no +warning. It compiles fine in every state, so no build gate can warn either. + +The non-obvious part worth documenting: with the UI Kit you do **not** call `CometChatCalls.init()` +yourself — `initFromSettings` does it, but **only** when `"uiKit": { "enableCalling": true }` is set +in `cometchat-settings.json`. A developer who adds the artifact and expects it to work will hit +state 2 and has no reason to connect it to a JSON flag they never set. + +| Where | Before | Now | +|---|---|---| +| `ui-kit/android/call-logs` | **zero** mentions of `calls-sdk-android` or any dependency requirement | `` with the exact stack trace + the Gradle line | +| components skills (both cohorts) | a parenthetical "(needs the calls artifact)" | explicit crash warning: compiles fine, fails at runtime | + +*(An earlier revision of this audit framed C-1 as a kit defect and recommended escalation. That was +wrong — the exception originates in the Calls SDK as intentional guidance, and a missing dependency +failing is correct behaviour. Corrected: docs-only.)* + +--- + +## Round 5 — the Compose fresh-app run + +A second fresh app, Jetpack Compose cohort, built from the `…-compose-*` skills only and run on the +emulator. The Compose recipes **compiled first time and rendered correctly** — theming +(`lightColorScheme(primary = …)`), `Scaffold(contentWindowInsets = WindowInsets.statusBars)`, +`weight(1f)` + `imePadding()` all behaved as the skills describe. One severe finding, and it is +**not** Compose-specific — it sits in the shared init path: + +### F4 — `enableCalling: true` without the Calls artifact kills the app at LAUNCH +``` +java.lang.NoClassDefFoundError: Failed resolution of: + Lcom/cometchat/calls/core/CometChatCalls$SessionSettingsBuilder; + at com.cometchat.uikit.core.CometChatUIKit.initCometChatCalls(CometChatUIKit.kt:229) + at com.cometchat.uikit.core.CometChatUIKit$initFromSettings$1.onSuccess(CometChatUIKit.kt:196) + at com.example.composechat.MainActivity.onCreate(MainActivity.kt:38) +``` +`initFromSettings` auto-initializes the Calls SDK when the flag is set. Without the dependency the +throw lands in **`onCreate`, before any UI renders** — so the symptom (app won't start at all) is +maximally distant from the cause (a boolean in a JSON file). Setting `enableCalling: false` with no +other change: `init OK → login OK`, app runs. + +This is worse than C-1: C-1 fails when you *use* a calling component; F4 fails when you *launch the +app*, whether or not calling is ever used. It is trivially hit by copying a settings file between +projects — which is exactly how it was found. + +| Where | Fix | +|---|---| +| `getting-started-kotlin`, `getting-started-jetpack`, `calling-integration` | `` with the stack trace + "change the flag and the dependency together" | +| core skill | warning beside the settings-file JSON block | +| builder-settings skill | `enableCalling` re-described: setting it `true` makes the dependency **mandatory** | +| calls skill | the flag and the artifact documented as a **pair**, with both failure directions | + +The two directions, together: + +| Artifact | `enableCalling` | Result | +|---|---|---| +| absent | `true` | **app crashes at launch** (F4) | +| present | `false` | calling components crash when used (C-1) | +| absent | `false` | fine — until a calling component is used (C-1) | +| present | `true` | correct | + +--- + +## Round 6 — Chat SDK v5 device run (headless, no UI Kit) + +A third fresh app depending on **only** `com.cometchat:chat-sdk-android:5.0.+`, built from +`cometchat-android-v5-sdk` alone. Verified on the emulator: + +``` +1 init OK ← CometChat.initFromSettings (reads the same assets JSON) +2 login OK cometchat-uid-1 ← init-then-login ordering, getLoggedInUser guard +3 message listener registered ← listener-register-with-id +4 conversations fetched: 5 ← pagination-via-request-builder +5 sent id=384770 "sdk-skill-test-2197" ← send-message + sdk-error-handling +6 history fetched: 5 message(s) ← MessagesRequestBuilder.fetchPrevious +7 listener removed (onDestroy) ← listener-remove-on-teardown +``` +No crashes. `CometChat.initFromSettings` reads the same `assets/cometchat-settings.json` as the UI +Kit — confirmed working without the UI Kit present. + +### S-3 — the SDK skill conflated two DIFFERENT `login` overloads (SKILL bug, now fixed) +The shipped SDK has: + +| Overload | Use | +|---|---| +| `login(uid, apiKey, listener)` | dev — **uid required** | +| `login(authToken, listener)` | production — **NO uid**; the server-minted token carries the identity | + +The skill wrote it as `login(uid, authKeyOrToken, …)`, which reads as "put either credential in the +middle slot". Following that for the **production** path passes a token where an apiKey is expected +— the wrong overload, and it fails at auth rather than at compile time. Fixed: both overloads are +now named explicitly, with the trap in Common pitfalls. Docs were correct here; the skill was not. + +--- + +## Round 7 — found by RUNNING the review harness on a device + +The review harness executed on a booted emulator for the first time (skills repo `AUDIT-086`). +The first kit view it inflated crashed, and the cause is a documentation gap: + +| # | Page | Gap | Fix | +|---|---|---|---| +| T1 | `ui-kit/android/getting-started-kotlin` | Neither getting-started page states that the app theme **must** descend from `Theme.MaterialComponents`. The kit's views are Material components, so on a stock `Theme.AppCompat.*` the first CometChat view inflated throws `IllegalArgumentException: The style on this component requires your app theme to be Theme.MaterialComponents (or a descendant)`. It is a **launch crash on the chat screen**, not a styling glitch, and it is the very first thing a developer following the page hits. `troubleshooting` and `theme-introduction` mention Material, but a reader only reaches those AFTER it has already crashed. | Added a `` to `getting-started-kotlin` next to the existing dependency-exclude warning: inherit `CometChatTheme.DayNight` in `res/values/themes.xml` and point `` at it. | + +**Scoped to Views on purpose.** `getting-started-jetpack` was deliberately left alone: the Compose +cohort themes through the `CometChatTheme` **composable** +(`chatuikit-compose/.../theme/Theme.kt:13`), so it does not inflate Material Views and the XML +theme requirement does not apply to it. Adding the same warning there would have been a new docs +bug, not a fix. + +**Reproduced, then fixed, in the harness itself:** `test-suite/harness/android` ran on +`Theme.AppCompat.DayNight.NoActionBar` and every emit died at `attach()` with exactly this +exception; it now inherits `CometChatTheme.DayNight` like any integrating app must. + +--- + +## ROOT CAUSE — a v5 UI Kit checkout is vendored inside the docs repo + +`/.cometchat-uikit-android/` is a **shallow clone of `cometchat/cometchat-uikit-android` at tag +`v5.2.9`** (26 MB, its own `.git`, untracked and NOT gitignored). It is a working artifact, not docs +content — and it is the **wrong major** for the v6 pages it sits beside. + +Every "phantom API" found in the v6 docs exists in that v5 checkout: + +| API taught on a v6 page | In shipped v6 (6.0.5)? | In the vendored v5.2.9 clone? | +|---|---|---| +| `CometChatMessageTemplate` | ❌ | ✅ | +| `setTemplates` | ❌ | ✅ | +| `CometChatUIKit.getDataSource()` | ❌ | ✅ | +| `getAuxiliaryOption` | ❌ | ✅ | +| `getSelectedGroupMembers` | ❌ | ✅ | +| `setOnBackButtonPressed` | ❌ | ✅ | + +**6 of 6.** These pages are not randomly wrong — they are **correctly documenting v5** under a v6 +heading. The most economical explanation is that they were written or verified against this +checkout. (Correlation + physical presence in the repo, not proof of intent — but the pattern is +exact, and the fix is the same either way.) + +Note the v5 module layout differs too: this clone has a single `chatuikit/` module, whereas v6 ships +`chatuikit-core` + `chatuikit-kotlin` + `chatuikit-compose`. Anyone checking "does this API exist?" +against it gets a confident, wrong answer. + +### Recommended +1. **Remove it from the docs repo** (or at minimum add it to `.gitignore` — today it is 26 MB of + untracked noise in every `git status`, and a nested `.git` inside a repo invites accidental + commits). +2. If a reference checkout is genuinely wanted for docs authoring, it must be the **v6** source — + `cometchat-team/uikit-android` @ `master-v6` — and it should be pinned to the version the docs + claim, with the version stated in the path or a README beside it. +3. Better still: verify against the **published artifact** (the `.aar` Gradle already resolves), which + cannot drift from what customers actually install. That is what caught all six of these. + +The remaining docs bugs are NOT explained by this and are ordinary copy errors: `endtyping`, +`"Strat Typing"`, `getRecieverUID`, `setAttachmemnt`, `getReason`. + +## Still owed (not fixed here) +- **C1 full rewrite** of `message-template.mdx` (636 lines) against `BubbleFactory` — needs docs-team authoring; a banner is not a substitute. +- **D1** `getting-started-*` → `initFromSettings` + gitignored settings file instead of hardcoded `APP_ID`/`AUTH_KEY` constants. Behaviour change; wants product sign-off. +- **D2/D3** AI Integration Quick Reference accordion backfill (v6 components, all of SDK v5). + +--- + +## Round 8 — phantom CALLBACK TYPES on the search page (three-way audit) + +Surfaced by `three-way-audit.mjs` after the skills started teaching `CometChatSearch`. The page +documents the right method NAMES, but types every callback with a class that **does not exist in +6.0.5**. This sits in the machine-readable "AI Integration Quick Reference" accordion — the block +an AI agent reads first — so an agent would emit v5-Java-style SAM construction +(`new OnItemClick() { … }`) that cannot compile against v6. + +| # | Page | Docs said | Shipped 6.0.5 | +|---|---|---|---| +| P1 | `ui-kit/android/search` | `OnItemClick` / `OnItemClick` | `((Conversation) -> Unit)?` / `((BaseMessage) -> Unit)?` | +| P2 | `ui-kit/android/search` | `OnBackPress` · `OnError` · `OnEmpty` | `(() -> Unit)?` · `((CometChatException) -> Unit)?` · `(() -> Unit)?` | +| P3 | `ui-kit/android/search` | `OnLoad` / `OnLoad` | `((List) -> Unit)?` / `((List) -> Unit)?` | +| P4 | `ui-kit/android/search` | two Kotlin fences calling `setOnLoad*(OnLoad { … })` | trailing lambda: `setOnLoadMessages { list -> … }` | + +**Verified absent from the kit:** `OnItemClick`, `OnBackPress`, `OnError`, `OnEmpty`, `OnLoad` are +not declared anywhere in `chatuikit-kotlin` / `chatuikit-core`. The only such type that IS real is +`OnClick` (used by e.g. `setOnAcceptClickListener(OnClick?)`), which is why the family reads +plausible. 13 sites fixed on this branch. + +**Deliberately NOT changed:** the same `OnItemClick` spelling in `upgrading-from-v5.mdx` is +inside fences labelled `title="V5 — …"`. Those are BEFORE examples of the old v5 Java API, where +the name is correct — "fixing" them would break the migration story. + +**Also confirmed, not a bug:** `setOnConversationClicked` / `setOnMessageClicked` (past tense) DO +ship — they are aliases of `setOnConversationClick` / `setOnMessageClick` +(`CometChatSearch.kt:2431,2436`). Only their declared TYPES were wrong. + +--- + +--- + +## Round 9 — the drift gate wired into CI, and what it then found + +`three-way-audit.mjs` is now a CI gate on the skills side (`npm run verify:sync:android-v6`, folded +into `verify:ci:android`) — the Android equivalent of what RN did with `sync-check.mjs`. Wiring it +up meant fixing it first: it read **only ```kotlin/java fences**, so an API documented in a props +table or in the "AI Integration Quick Reference" accordion counted as undocumented. It now also +reads inline-code mentions and accordion JSON keys — which immediately exposed six phantoms that +fence-scanning could never see. + +| # | Page | Docs said | Shipped | Kind | +|---|---|---|---|---| +| R1 | `ui-kit/android/guide-ai-agent` | `setAIAssistantTools()` | **`setAiAssistantTools()`** (`CometChatMessageList.kt:2446`, `HashMap`) | casing — feature IS real | +| R2 | `ui-kit/android/troubleshooting` | `setAuxiliaryButtonView()` | `setAuxiliaryButtonViewListener()` — the A4 fix never reached this page | wrong name | +| R3 | `sdk/android/v5/edit-message` | `onSucess()` | `onSuccess()` | typo | +| R4 | `sdk/android/v5/send-message` | `setSubtype()` | **`setSubType()`** (`CustomMessage.java:113`) | casing — will not compile | +| R5 | `ui-kit/android/message-template` | the whole 676-line page taught v5's `MessageTemplate` | **rewritten** against `BubbleFactory` (both cohorts), 164 lines | C1 closed | +| R6 | `ui-kit/android/search`, `guide-search-messages` | **8** examples calling `setOnConversationClicked`/`setOnMessageClicked` with a **3-arg** lambda `{ view, position, x -> }` | **ONE** arg — `((Conversation) -> Unit)?` / `((BaseMessage) -> Unit)?` (`CometChatSearch.kt:1790,1797,2431,2436`) | arity — will not compile | + +R6 is the same defect class as B1 (the 3-arg thread callback) on a different page — evidence the +v5 listener idiom is still being carried into v6 pages by hand. + +**Result: `PHANTOM in DOCS` and `PHANTOM in SKILLS` are both 0** under the wider scan. + +**Still advisory, not defects:** the gate's `DOCS GAP (2)` names `setOnConversationClick` / +`setOnMessageClick` — the docs use the `…Clicked` aliases while the skills teach the canonical +names. **Both ship** (the aliases are real, `CometChatSearch.kt:2431,2436`), so this is a naming +inconsistency to settle, not broken code. `SKILL GAP (333)` is long-tail by design: the pack is +deliberately thin and fetches the long tail from docs at runtime. + diff --git a/REPRO-enableCalling-launch-crash.md b/REPRO-enableCalling-launch-crash.md new file mode 100644 index 000000000..fab77234d --- /dev/null +++ b/REPRO-enableCalling-launch-crash.md @@ -0,0 +1,75 @@ +# Repro — `enableCalling: true` without the Calls SDK crashes the app at launch + +**Kit:** `com.cometchat:chatuikit-compose-android:6.0.5` (crash path is in the shared +`chatuikit-core`, so `chatuikit-kotlin-android` is affected identically) +**Device:** Pixel 8 emulator, API 36 · **Observed:** 2026-08-21 + +## Steps + +1. New Android app, `minSdk 28`, Kotlin DSL. Add the CometChat maven to `settings.gradle.kts`: + ```kotlin + maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/") + ``` +2. Add **only** the UI Kit — deliberately **no** `calls-sdk-android`: + ```kotlin + dependencies { implementation("com.cometchat:chatuikit-compose-android:6.0.+") } + configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") } + ``` +3. Create `app/src/main/assets/cometchat-settings.json` with **valid** credentials and the calling + flag ON. Credentials must be valid — the crash occurs *after* chat init succeeds: + ```json + { + "appId": "", + "region": "", + "credentials": { "authKey": "" }, + "uiKit": { "subscribePresenceForAllUsers": true, "enableCalling": true } + } + ``` +4. In `MainActivity.onCreate`, call init — nothing else is required: + ```kotlin + CometChatUIKit.initFromSettings(this, object : CometChat.CallbackListener() { + override fun onSuccess(result: String) { /* never reached */ } + override fun onError(e: CometChatException?) { /* never reached */ } + }) + ``` +5. Build, install, launch. + +## Expected +Either init succeeds with calling silently unavailable, or `onError` fires with an actionable +message naming the missing dependency. + +## Actual +Process dies in `onCreate`, before any UI renders. Neither `onSuccess` nor `onError` is called — +the throw escapes the callback. + +``` +FATAL EXCEPTION: main +java.lang.NoClassDefFoundError: Failed resolution of: + Lcom/cometchat/calls/core/CometChatCalls$SessionSettingsBuilder; + at com.cometchat.uikit.core.CometChatUIKit.initCometChatCalls(CometChatUIKit.kt:229) + at com.cometchat.uikit.core.CometChatUIKit.access$initCometChatCalls(CometChatUIKit.kt:40) + at com.cometchat.uikit.core.CometChatUIKit$initFromSettings$1.onSuccess(CometChatUIKit.kt:196) + at com.cometchat.uikit.core.CometChatUIKit$initFromSettings$1.onSuccess(CometChatUIKit.kt:187) + at com.cometchat.chat.core.CometChat.init(CometChat.java:63) + at com.cometchat.chat.core.CometChat.initFromSettings(CometChat.java:138) + at com.cometchat.uikit.core.CometChatUIKit.initFromSettings(CometChatUIKit.kt:185) + at com.example.composechat.MainActivity.onCreate(MainActivity.kt:38) +``` + +## Confirming the cause +Set `"enableCalling": false`, change nothing else, rebuild → `init OK` then `login OK`, app runs +normally. Flip it back → crash returns. + +## Why it matters +- The symptom (app will not start at all) is maximally distant from the cause (one boolean in a + JSON asset). Nothing in the flag's name implies a Gradle dependency. +- It **compiles cleanly**, so no build-time gate can catch it. +- It is trivially hit by copying `cometchat-settings.json` between projects — which is how it was + found here. +- `onError` is not invoked, so an app that correctly handles init failure still dies. + +## Suggested fix +Guard `initCometChatCalls` so a missing Calls SDK routes to `callbackListener.onError(...)` with a +message naming the required dependency, rather than propagating `NoClassDefFoundError`. Unlike the +`CometChatCallLogs` case (where a missing dependency legitimately cannot work), here calling is an +*optional* feature the app may never use — a launch crash is disproportionate. diff --git a/prompt/documentation-improvement-guidelines.md b/prompt/documentation-improvement-guidelines.md new file mode 100644 index 000000000..30217caae --- /dev/null +++ b/prompt/documentation-improvement-guidelines.md @@ -0,0 +1,1163 @@ +# CometChat SDK Documentation Improvement Guidelines + +These guidelines document the patterns, standards, and improvements applied to SDK documentation. Use this as a reference when improving documentation for any SDK technology (JavaScript, Android, iOS, Flutter, React Native) with AI assistance. + +## Table of Contents + +1. [Quick Reference Blocks](#1-quick-reference-blocks) +2. [Available Via Notes](#2-available-via-notes) +3. [Code Examples: Tab Conventions](#3-code-examples-tab-conventions) +4. [Tab Naming Standards](#4-tab-naming-standards) +5. [Mintlify Components](#5-mintlify-components) +6. [Next Steps Navigation](#6-next-steps-navigation) +7. [Page Structure Templates](#7-page-structure-templates) +8. [Feature Page Anatomy](#8-feature-page-anatomy) +9. [Navigation Organization](#9-navigation-organization) +10. [Integration Guides](#10-integration-guides) +11. [Glossary & Key Concepts](#11-glossary--key-concepts) +12. [Security & Init Warnings](#12-security--init-warnings) +13. [Cross-Linking & References](#13-cross-linking--references) +14. [What NOT to Do](#14-what-not-to-do) +15. [File Classification](#15-file-classification) +16. [File-by-File Checklist](#16-file-by-file-checklist) +17. [Prompt Template for AI Assistants](#17-prompt-template-for-ai-assistants) + +--- + +## 1. Quick Reference Blocks + +Every content page should have a Quick Reference block at the very top, immediately after the frontmatter. + +**Why:** AI agents parsing docs need a fast, copy-paste-ready summary. Developers scanning docs want the TL;DR. + +### Feature Pages (Messaging, Users, Groups, Calling, etc.) + +Show the most common API calls for that feature: + +```mdx +{/* TL;DR for Agents and Quick Reference */} + +**Quick Reference for AI Agents & Developers** + +```javascript +// Send text message to user +const msg = new CometChat.TextMessage("UID", "Hello!", CometChat.RECEIVER_TYPE.USER); +await CometChat.sendMessage(msg); + +// Send to group +const msg = new CometChat.TextMessage("GUID", "Hello!", CometChat.RECEIVER_TYPE.GROUP); +await CometChat.sendMessage(msg); + +// Media message +const msg = new CometChat.MediaMessage("UID", file, CometChat.MESSAGE_TYPE.IMAGE, CometChat.RECEIVER_TYPE.USER); +await CometChat.sendMediaMessage(msg); +``` + +``` + +### Overview/Hub Pages + +For overview pages that link to sub-pages, list the paths instead of code: + +```mdx + +**Quick Reference for AI Agents & Developers** + +Choose your path: +- **Chat Only** → [guide-chat-only](/sdk/javascript/guide-chat-only) - Text, media, groups +- **Calls Only** → [guide-calls-only](/sdk/javascript/guide-calls-only) - Standalone video/audio +- **Chat + Calls** → [guide-chat-calls](/sdk/javascript/guide-chat-calls) - Full communication + +``` + +### Setup/Getting Started Pages + +Show install + init + login in one block: + +```mdx + +**Quick Setup Reference** + +```bash +# Install +npm install @cometchat/chat-sdk-javascript + +# Initialize (run once at app start) +CometChat.init(APP_ID, appSettings) + +# Login (after init) +CometChat.login(UID, AUTH_KEY) # Dev only +CometChat.login(AUTH_TOKEN) # Production +``` + +**Required Credentials:** App ID, Region, Auth Key (dev) or Auth Token (prod) +**Get from:** [CometChat Dashboard](https://app.cometchat.com) → Your App → API & Auth Keys + +``` + +### Reference Pages (Listeners, Message Structure, Key Concepts) + +Show the most-used API calls or constants: + +```mdx + +**Quick Reference for AI Agents & Developers** + +```javascript +// Add message listener +CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({ + onTextMessageReceived: (message) => { }, + onMediaMessageReceived: (message) => { } +})); + +// Remove listener +CometChat.removeMessageListener("LISTENER_ID"); +``` + +``` + +### Rules (all page types) + +- Add necessary code examples +- Show the most common use cases +- Use real method names and constants — no pseudocode +- Include comments explaining what each snippet does +- Use `await` style for brevity (async/await is most readable) + +--- + +## 2. Available Via Notes + +Add an "Available via" note on **feature pages only** — pages that document a user-facing capability. + +### What qualifies as a feature page + +- Messaging: `send-message`, `receive-message`, `edit-message`, `delete-message`, `threaded-messages`, `reactions`, `mentions`, `interactive-messages`, `transient-messages` +- Users: `user-presence`, `block-users`, `retrieve-users`, `user-management` +- Groups: `groups-overview`, `create-group`, `join-group`, `leave-group`, `delete-group`, `update-group`, `retrieve-groups`, `retrieve-group-members`, `group-add-members`, `group-kick-ban-members`, `group-change-member-scope`, `transfer-group-ownership` +- Conversations: `retrieve-conversations`, `delete-conversation` +- Receipts & indicators: `delivery-read-receipts`, `typing-indicators` +- Calling: `default-call`/`default-calling`, `direct-call`/`direct-calling`, `call-logs`, `recording` +- AI: `ai-agents`, `ai-chatbots-overview`, `ai-moderation`, `ai-user-copilot-overview` +- Other: `flag-message`, `mentions` + +### What does NOT get "Available via" + +- Setup/installation pages (`overview`, `setup`, `setup-sdk`, `calling-setup`) +- Configuration pages (`managing-web-sockets-connections-manually`, `session-timeout`, `connection-status`) +- Styling/customization pages (`custom-css`, `video-view-customisation`, `virtual-background`, `presenter-mode`) +- Reference pages (`all-real-time-listeners`, `message-structure-and-hierarchy`, `key-concepts`, `login-listener`) +- Guide pages (`guide-chat-only`, `guide-calls-only`, `guide-chat-calls`, `guide-moderation`, `guide-notifications`, `guides`) +- Overview/hub pages that just link to sub-pages (`messaging-overview`, `users-overview`, `calling-overview`, `advanced-overview`, `resources-overview`, `extensions-overview`) +- Migration pages (`upgrading-from-v3`, `upgrading-from-v2`) +- Framework-specific pages (`react-overview`, `angular-overview`, `vue-overview`) +- Changelog, rate limits, webhooks overview +- Standalone calling (implementation approach, not a feature) + +### Pattern + +```mdx + +**Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [UI Kits](/ui-kit/react/overview) + +``` + +### Common combinations + +| Feature Type | Available Via | +| --- | --- | +| Messaging features (send, receive, edit, delete, threads, reactions) | SDK \| REST API \| UI Kits | +| Calling features (ringing, direct call) | SDK \| UI Kits | +| User/Group management | SDK \| REST API \| UI Kits | +| Conversations (retrieve, delete) | SDK \| REST API \| UI Kits | +| Receipts, typing indicators | SDK \| REST API \| UI Kits | +| AI features (moderation, agents, copilot) | SDK \| REST API \| UI Kits \| Dashboard | +| Call logs | SDK \| REST API \| Dashboard | +| Flag/report message | SDK \| REST API \| Dashboard | +| Recording | SDK \| Dashboard | +| Advanced filtering | SDK \| REST API | + +### Placement + +Right after the introductory sentence/paragraph, before the first `##` section heading. + +--- + +## 3. Code Examples: Tab Conventions + +Every code example should provide multiple language variants in tabs. The tabs differ by SDK technology. + +### JavaScript SDK + +```mdx + + +```javascript +CometChat.sendMessage(textMessage).then( + (message) => console.log("Sent:", message), + (error) => console.log("Error:", error) +); +``` + + +```typescript +CometChat.sendMessage(textMessage).then( + (message: CometChat.TextMessage) => console.log("Sent:", message), + (error: CometChat.CometChatException) => console.log("Error:", error) +); +``` + + +```javascript +try { + const message = await CometChat.sendMessage(textMessage); + console.log("Sent:", message); +} catch (error) { + console.log("Error:", error); +} +``` + + +``` + +### Android SDK + +```mdx + + +```kotlin +CometChat.sendMessage(textMessage, object : CometChat.CallbackListener() { + override fun onSuccess(message: TextMessage) { + Log.d(TAG, "Message sent: ${message.text}") + } + override fun onError(e: CometChatException) { + Log.e(TAG, "Error: ${e.message}") + } +}) +``` + + +```java +CometChat.sendMessage(textMessage, new CometChat.CallbackListener() { + @Override + public void onSuccess(TextMessage message) { + Log.d(TAG, "Message sent: " + message.getText()); + } + @Override + public void onError(CometChatException e) { + Log.e(TAG, "Error: " + e.getMessage()); + } +}); +``` + + +``` + +### iOS SDK + +```mdx + + +```swift +CometChat.sendTextMessage(message: textMessage, onSuccess: { message in + print("Message sent: \(message.text)") +}, onError: { error in + print("Error: \(error?.errorDescription)") +}) +``` + + +``` + +### Flutter SDK + +```mdx + + +```dart +CometChat.sendMessage(textMessage, onSuccess: (TextMessage message) { + debugPrint("Message sent: ${message.text}"); +}, onError: (CometChatException e) { + debugPrint("Error: ${e.message}"); +}); +``` + + +``` + +### React Native SDK + +```mdx + + +```javascript +CometChat.sendMessage(textMessage).then( + (message) => console.log("Sent:", message), + (error) => console.log("Error:", error) +); +``` + + +```typescript +CometChat.sendMessage(textMessage).then( + (message: CometChat.TextMessage) => console.log("Sent:", message), + (error: CometChat.CometChatException) => console.log("Error:", error) +); +``` + + +``` + +### Contextual tabs (all platforms) + +When showing alternative approaches (not language variants), use descriptive tab titles: + +```mdx + + + + + + + + +``` + +```mdx + +... +... +... +... + +``` + +### Rules + +- Every major code block should have language tabs — don't leave single-language examples +- TypeScript tabs should add proper type annotations, not just rename the file +- Async/Await tab (JavaScript SDK) should show try/catch pattern +- Simple one-liners (e.g., `CometChat.disconnect()`) can skip tabs — use a single block +- Keep code copy-paste ready: include variable declarations, imports where needed +- Use realistic placeholder values: `"user_uid"`, `"group_guid"`, `"YOUR_APP_ID"` +- For "To User" / "To Group" tabs, show the same operation for both receiver types + +--- + +## 4. Tab Naming Standards + +Use consistent tab titles across all pages. Never use arbitrary or inconsistent titles. + +### Correct tab titles by platform + +| Platform | Primary Tab | Secondary Tab | Tertiary Tab | +| --- | --- | --- | --- | +| JavaScript SDK | `JavaScript` | `TypeScript` | `Async/Await` | +| Android SDK | `Kotlin` | `Java` | — | +| iOS SDK | `Swift` | `Objective-C` (if supported) | — | +| Flutter SDK | `Dart` | — | — | +| React Native SDK | `JavaScript` | `TypeScript` | — | + +### Contextual tab titles (all platforms) + +| Tab Content | Title | +| --- | --- | +| Send to user | `To User` | +| Send to group | `To Group` | +| npm install | `npm` | +| yarn install | `yarn` | +| pnpm install | `pnpm` | +| CDN script tag | `CDN` | +| ES Module import | `ES Modules` | +| CommonJS require | `CommonJS` | +| Dashboard setup | `Dashboard (Testing)` | +| REST API setup | `REST API (Production)` | +| SDK setup | `SDK (On-the-fly)` | +| All users presence | `All Users` | +| By role presence | `By Role` | +| Friends only presence | `Friends Only` | +| File input upload | `From File Input` | +| URL upload | `From URLs` | +| Users only filter | `Users Only` | +| Groups only filter | `Groups Only` | +| Hide AI agents | `Hide AI Agents` | +| Only AI agents | `Only AI Agents` | + +### When to use language tabs vs contextual tabs + +- **Language tabs** (JavaScript/TypeScript/Async/Await): When showing the same code in different language styles +- **Contextual tabs** (To User/To Group, npm/yarn): When showing alternative approaches or configurations +- **Framework tabs** (React/Next.js/Vue/Angular/Nuxt): When showing framework-specific implementations + +--- + +## 5. Mintlify Components + +Use these Mintlify components consistently across all pages: + +### Steps — For sequential procedures + +```mdx + + + npm install @cometchat/chat-sdk-javascript + + + CometChat.init(appID, appSettings); + + +``` + +**Use for:** Setup flows, multi-step procedures, getting started guides, authentication flows. + +### Tabs — For code variants and alternative approaches + +**Use for:** Language variants (JS/TS/Async), package manager options (npm/yarn), platform-specific code, alternative approaches (To User/To Group), framework-specific implementations (React/Vue/Angular). + +### CardGroup + Card — For navigation and next steps + +```mdx + + + Send text, media, and custom messages + + +``` + +**Use for:** Next Steps sections, feature overviews, choosing between options, guide hub pages. + +### AccordionGroup + Accordion — For supplementary info + +```mdx + + + Explanation of the best practice. + + +``` + +**Use for:** Best practices, FAQs, troubleshooting tips, edge cases, common errors, framework-specific patterns. + +### Note, Warning, Info — For callouts + +```mdx +Informational callout — general tips and context. +Critical warning — data loss, security, breaking changes. +Highlighted info — quick references, availability, requirements. +``` + +**Use for:** + +- `` — Prerequisites, tips, general information, "Available via" notes, test user info +- `` — Destructive operations, security concerns (Auth Key in production), init-before-login, mutually exclusive options +- `` — Quick references, feature requirements, plan restrictions, feature flags + +### Frame — For images/screenshots + +```mdx + + + +``` + +**Use for:** Architecture diagrams, flow diagrams, dashboard screenshots. + +### Mermaid — For flow diagrams + +```mdx +```mermaid +sequenceDiagram + participant User + participant App + participant CometChat + User->>App: Login + App->>CometChat: CometChat.login() +``` +``` + +**Use for:** Authentication flows, message delivery flows, call signaling flows. Preserve existing mermaid diagrams — never remove them. + +--- + +## 6. Next Steps Navigation + +Every content page should end with a `## Next Steps` section using CardGroup. + +### Pattern + +```mdx +--- + +## Next Steps + + + + One-line description of what they'll learn + + + One-line description + + +``` + +### Rules + +- Always use `cols={2}` for consistency +- Include 2–4 cards (not more) +- Link to logically next topics (what would the developer need after this?) +- Use descriptive FontAwesome icon names +- Keep descriptions to one short sentence +- Use `## Next Steps` as the heading — not `## Next Steps & Further Reading` or other variants +- Do NOT include bullet-list links alongside the CardGroup — the cards are sufficient + +### Logical next step patterns + +| Current Page | Suggested Next Steps | +| --- | --- | +| Overview | Setup SDK, Key Concepts | +| Setup SDK | Authentication, Send First Message | +| Authentication | Send Message, User Management | +| Send Message | Receive Messages, Edit Message, Interactive Messages | +| Receive Message | Delivery Receipts, Typing Indicators | +| Edit Message | Delete Message, Send Message | +| Delete Message | Edit Message, Receive Message | +| Threaded Messages | Send Message, Receive Message | +| Reactions | Send Message, Receive Message | +| Mentions | Send Message, Receive Message | +| Users Overview | Retrieve Users, User Presence, Block Users | +| User Presence | Retrieve Users, Connection Status | +| Block Users | Retrieve Users, User Management | +| Groups Overview | Create Group, Retrieve Groups | +| Create Group | Join Group, Add Members | +| Join Group | Leave Group, Retrieve Members | +| Retrieve Conversations | Delete Conversation, Typing Indicators, Read Receipts | +| Calling Overview | Calling Setup, Default Call | +| Default Call (Ringing) | Direct Call, Call Logs, Recording | +| Direct Call | Default Call, Recording | +| Call Logs | Default Call, Recording | +| AI Agents | AI Chatbots, AI Moderation | +| Guides Hub | Individual guides | +| Key Concepts | Setup SDK, Send Message | + +--- + +## 7. Page Structure Templates + +### Feature Page Structure + +```text +1. Frontmatter (title, sidebarTitle, description) +2. Quick Reference block (Info component with code) +3. Introductory sentence (1-2 lines, what this feature does) +4. Available Via note (feature pages only) +5. Main content sections with code examples in tabs +6. Parameter tables after code examples +7. Common Use Cases / Examples +8. Real-Time Events / Listeners (if applicable) +9. Best Practices (AccordionGroup) — if applicable +10. Troubleshooting (AccordionGroup) — if applicable +11. Next Steps (CardGroup) +``` + +### Overview/Hub Page Structure + +```text +1. Frontmatter (title, sidebarTitle, description) +2. Quick Reference block (Info with links to sub-pages) +3. Introductory paragraph +4. Available Via note (if this is a feature overview like Groups Overview) +5. Key concepts / types / constants tables +6. Quick Start examples +7. Sub-feature CardGroups (management, membership, etc.) +8. Object properties table +9. Common Use Cases with code +10. Real-Time Events +11. Next Steps (CardGroup) +``` + +### Setup/Getting Started Page Structure + +```text +1. Frontmatter (title, sidebarTitle, description) +2. Quick Reference block (Info with install + init + login) +3. Intro paragraph +4. Prerequisites (Steps component) +5. Installation (Tabs for npm/yarn/pnpm/CDN) +6. Import (Tabs for ES Modules/CommonJS/CDN) +7. Initialize CometChat (Tabs for JS/TS/Async) +8. Complete Quick Start example +9. Configuration Options (tables + code) +10. Framework Integration (Tabs for React/Next.js/Vue/Angular/Nuxt) +11. Next Steps (CardGroup) +``` + +### Authentication Page Structure + +```text +1. Frontmatter (title, sidebarTitle, description) +2. Quick Reference block (Info with login methods) +3. Intro paragraph + note about user management +4. Authentication Flow (mermaid diagram) +5. Choose Your Method (CardGroup: Auth Key vs Auth Token) +6. Create a User (Tabs: Dashboard/REST API/SDK) +7. Login with Auth Key (Tabs: JS/TS/Async) + Warning +8. Login with Auth Token (Tabs: JS/TS/Async) + Steps +9. Check Login Status +10. Logout +11. Server-Side Token Generation (Tabs: Node.js/Python) +12. User Object properties table +13. Login Listeners +14. Best Practices (AccordionGroup) +15. Troubleshooting (AccordionGroup) +16. Next Steps (CardGroup) +``` + +### Guide Page Structure + +```text +1. Frontmatter (title, sidebarTitle, description) +2. Quick Reference block (Info with guide path links) +3. What you'll build (outcome) +4. Prerequisites (accounts, keys, dependencies) +5. Step-by-step implementation (Steps component) +6. Complete working code at the end +7. Integration Checklist +8. Next Steps (CardGroup — related guides + feature docs) +``` + +### Migration Page Structure + +```text +1. Frontmatter (title, description) +2. Quick Reference block (Info with summary of key changes) +3. Breaking changes list +4. Migration steps +5. API changes tables +6. Next Steps (CardGroup) +``` + +### Frontmatter template + +```yaml +--- +title: "Human-Readable Title" +sidebarTitle: "Short Sidebar Name" # Optional, only if title is too long for sidebar +description: "One sentence describing what this page covers" +--- +``` + +--- + +## 8. Feature Page Anatomy + +Every SDK feature page follows a consistent structure. When improving these pages, enhance each section without changing the order. + +### 1. Quick Reference + Intro + +- Quick Reference block with copy-paste ready code +- 1–2 sentence description of what the feature does +- "Available via" note (feature pages only) +- Type/method overview table (if multiple operations exist) + +### 2. Main Operations + +Each operation gets its own `##` section with: +- Code examples in language tabs (JS/TS/Async or platform equivalents) +- Contextual tabs where applicable (To User / To Group) +- Parameter table after the code +- Optional features (metadata, tags, etc.) as sub-sections + +### 3. Response/Object Properties + +- Table showing the returned object's properties +- Getter methods and their return types +- Example code accessing properties + +### 4. Filtering / Request Builders + +- `RequestBuilder` pattern with all available methods +- Filter options table +- Pagination examples (`fetchNext()` pattern) + +### 5. Real-Time Events / Listeners + +- Listener registration code +- All event callbacks documented +- Cleanup/removal code +- Link to full listeners reference + +### 6. Common Use Cases + +- Complete working examples for typical scenarios +- Framework-specific examples (React hooks, Vue composables, etc.) + +### 7. Best Practices & Troubleshooting + +- AccordionGroup with best practices +- AccordionGroup with common errors and solutions + +### 8. Next Steps + +- CardGroup with 2-4 related pages + +### Adding Missing Tabs + +When improving existing pages: + +- If a code block shows `.then()` pattern → add TypeScript and Async/Await tabs +- If a code block shows only Async/Await → add JavaScript (.then()) and TypeScript tabs +- If a code block shows only TypeScript → add JavaScript and Async/Await tabs +- For Android: if only Java → add Kotlin tab; if only Kotlin → add Java tab +- Do NOT convert existing single-tab examples to no-tab code blocks — always keep tabs + +### Parameter Table Format + +The existing SDK docs use this table format: + +```markdown +| Parameter | Type | Description | +| --- | --- | --- | +| `receiverID` | string | UID of user or GUID of group | +| `messageText` | string | The text content | +| `receiverType` | string | `CometChat.RECEIVER_TYPE.USER` or `GROUP` | +``` + +Preserve this format. When adding new parameters, follow the same pattern. + +### Object Properties Table Format + +```markdown +| Property | Method | Description | +| --- | --- | --- | +| ID | `getConversationId()` | Unique conversation identifier | +| Type | `getConversationType()` | `user` or `group` | +| Last Message | `getLastMessage()` | Most recent message object | +``` + +### Filter Options Table Format + +```markdown +| Method | Description | +| --- | --- | +| `setLimit(limit)` | Number of results (max 50) | +| `setSearchKeyword(keyword)` | Search by name | +| `setTags(tags)` | Filter by tags | +``` + +--- + +## 9. Navigation Organization + +The SDK sidebar should follow this structure (adapt per technology): + +```text +SDK v4 +├── Overview +├── Setup +├── Key Concepts +├── Authentication +│ └── Login, Logout, Auth Tokens +├── Messaging +│ ├── Overview +│ ├── Send Message +│ ├── Receive Message +│ ├── Edit / Delete Message +│ ├── Threaded Messages +│ ├── Reactions +│ ├── Mentions +│ ├── Message Structure & Hierarchy +│ ├── Interactive Messages +│ ├── Transient Messages +│ └── Additional Message Filtering +├── Users +│ ├── Overview +│ ├── Retrieve Users +│ ├── User Presence +│ ├── Block Users +│ └── User Management +├── Groups +│ ├── Overview +│ ├── Create / Update / Delete Group +│ ├── Join / Leave Group +│ ├── Retrieve Groups / Members +│ ├── Add Members / Kick-Ban +│ ├── Change Scope / Transfer Ownership +├── Conversations +│ ├── Retrieve Conversations +│ └── Delete Conversation +├── Receipts & Indicators +│ ├── Delivery & Read Receipts +│ ├── Typing Indicators +│ └── Flag Message +├── Calling +│ ├── Overview +│ ├── Setup +│ ├── Default Calling (Ringing) +│ ├── Direct Calling +│ ├── Standalone Calling +│ ├── Recording +│ ├── Call Logs +│ ├── Session Timeout +│ ├── Presenter Mode +│ ├── Virtual Background +│ ├── Video View Customisation +│ └── Custom CSS +├── AI Features +│ ├── AI Agents +│ ├── AI Chatbots +│ ├── AI Moderation +│ └── AI User Copilot +├── Advanced +│ ├── Connection Status +│ ├── WebSocket Management +│ ├── Login Listeners +│ ├── All Real-Time Listeners +│ └── Webhooks +├── Integration Guides +│ ├── Hub Page +│ ├── Chat Only +│ ├── Calls Only +│ ├── Chat + Calls +│ ├── Moderation +│ └── Notifications +├── Framework Guides (JavaScript SDK only) +│ ├── React +│ ├── Angular +│ └── Vue +├── Resources +│ ├── Rate Limits +│ ├── Extensions +│ └── Changelog +└── Migration Guide +``` + +--- + +## 10. Integration Guides + +The SDK should have step-by-step integration guides for common scenarios. These are separate from feature docs — they walk through a complete implementation from zero. + +### Guides to have + +- **Chat Only** — Text + media + groups (no calling) +- **Calls Only** — Standalone video/audio (no chat SDK) +- **Chat + Calls** — Full communication suite +- **Moderation** — Content filtering setup +- **Notifications** — Push alerts + +### Guide structure + +```text +1. What you'll build (outcome) +2. Prerequisites (accounts, keys, dependencies) +3. Step-by-step implementation (Steps component) +4. Complete working code at the end +5. Integration checklist +6. Next steps / what to add +``` + +### Rules + +- Every step must have copy-paste ready code +- Include expected output or what the developer should see +- Link back to detailed feature docs for customization +- Keep guides focused — one scenario per guide +- Include a "Quick Decision Guide" table on the hub page + +--- + +## 11. Glossary & Key Concepts + +SDK-specific terms that should be defined or linked when first used: + +| Term | Definition | +| --- | --- | +| UID | Unique User Identifier — alphanumeric string you assign to each user | +| GUID | Group Unique Identifier — alphanumeric string you assign to each group | +| Auth Key | Development-only credential for quick testing. Never use in production | +| Auth Token | Secure, per-user token generated via REST API. Use in production | +| REST API Key | Server-side credential for REST API calls. Never expose in client code | +| Receiver Type | Specifies if a message target is a `user` or `group` | +| Scope | Group member role: `admin`, `moderator`, or `participant` | +| Listener | Callback handler for real-time events (messages, presence, calls, groups) | +| Conversation | A chat thread between two users or within a group | +| Metadata | Custom JSON data attached to users, groups, or messages | +| Tags | String labels for categorizing users, groups, conversations, or messages | +| RequestBuilder | Builder pattern class for constructing filtered/paginated queries | +| AppSettings | Configuration object for initializing the SDK (App ID, Region, presence) | +| Transient Message | Ephemeral message not stored on server (typing indicators, live reactions) | +| Interactive Message | Message with actionable UI elements (forms, cards, buttons) | + +Include 10–20 terms. Define acronyms. Link to relevant pages where the concept is explained in detail. + +--- + +## 12. Security & Init Warnings + +### Init Warning + +```mdx + +`CometChat.init()` must be called before any other SDK method. Calling `login()`, `sendMessage()`, or registering listeners before `init()` will fail. + +``` + +### Auth Key Warning + +```mdx + +**Auth Key** is for development/testing only. In production, generate **Auth Tokens** on your server using the REST API and pass them to the client. Never expose Auth Keys in production client code. + +``` + +### SSR/Framework Note (JavaScript SDK only) + +```mdx + +**Server-Side Rendering (SSR):** CometChat SDK requires browser APIs (`window`, `WebSocket`). For Next.js, Nuxt, or other SSR frameworks, initialize the SDK only on the client side using dynamic imports or `useEffect`. See the [Framework Integration](/sdk/javascript/setup-sdk#framework-integration) section. + +``` + +### Listener Cleanup Warning + +```mdx + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + +``` + +### Destructive Operation Warning + +```mdx + +This operation is irreversible. Deleted [messages/groups/conversations] cannot be recovered. + +``` + +### Placement + +- Init + Auth Key warnings: on `overview` and `setup` pages +- SSR note: on `overview` and framework-specific pages (JavaScript SDK only) +- Listener cleanup: on any page that registers listeners +- Destructive warnings: on delete pages (`delete-message`, `delete-group`, `delete-conversation`) + +--- + +## 13. Cross-Linking & References + +Link related concepts together. When a page references a concept explained elsewhere, add an inline link. + +### Standard cross-links + +- On messaging pages: "For a deeper understanding of how messages are structured, see [Message Structure & Hierarchy](/sdk/[tech]/message-structure-and-hierarchy)." +- On any page using listeners: "Remember to [remove listeners](/sdk/[tech]/all-real-time-listeners) when they're no longer needed." +- On pages using RequestBuilders: "See [Additional Message Filtering](/sdk/[tech]/additional-message-filtering) for all builder options." +- On feature pages: Link to the REST API equivalent when available. +- On calling pages: Link to [Calling Setup](/sdk/[tech]/calling-setup) for SDK installation. +- On AI pages: Link to Dashboard for enabling features. + +### Related feature links + +- Send Message → Receive Message, Edit Message, Delete Message +- Receive Message → Delivery Receipts, Typing Indicators +- Create Group → Join Group, Add Members, Retrieve Groups +- Groups Overview → all group sub-pages +- Users Overview → all user sub-pages +- Default Call ↔ Direct Call ↔ Standalone Calling +- Retrieve Conversations → Delete Conversation, Typing Indicators + +--- + +## 14. What NOT to Do + +Lessons learned from the SDK documentation improvement process: + +1. **Do NOT remove existing prose or explanatory text.** Even if it seems verbose, developers rely on explanations. Only add — never subtract content. + +2. **Do NOT remove code examples.** Every code snippet exists for a reason. Add more variants (TypeScript, Async/Await, Kotlin) but never remove existing ones. + +3. **Do NOT remove mermaid diagrams or flow charts.** Visual aids help developers understand authentication flows, message delivery, and call signaling. + +4. **Do NOT remove framework-specific guides.** React, Angular, Vue, Next.js, Nuxt guides are all valuable even if they seem redundant. + +5. **Do NOT minimize or condense docs.** The goal is comprehensive, not concise. More detail is better than less. + +6. **Do NOT add "Available via" to non-feature pages.** Setup guides, configuration pages, reference pages, guide pages, and migration pages should not have availability notes. + +7. **Do NOT change section headings** that developers may have bookmarked or that other pages link to. + +8. **Do NOT restructure content within pages** unless explicitly asked. Navigation reorganization (sidebar order) is fine; content reorganization within pages is risky. + +9. **Do NOT remove AccordionGroup sections** (best practices, troubleshooting, common errors). These are high-value for developers debugging issues. + +10. **Do NOT remove server-side code examples** (Node.js, Python token generation). These are critical for production implementations. + +11. **Do NOT add UI Kit component code to SDK docs.** SDK docs show raw API calls. UI Kit component rendering belongs in UI Kit docs. + +12. **Do NOT remove "Complete Working Example" sections.** These end-to-end examples are the most valuable part of many pages. + +--- + +## 15. File Classification + +### Full Treatment (Quick Reference + Available Via + Next Steps) + +**Messaging feature pages:** +- `send-message`, `receive-message`, `edit-message`, `delete-message` +- `threaded-messages`, `reactions`, `mentions` +- `interactive-messages`, `transient-messages` +- `delivery-read-receipts`, `typing-indicators` +- `flag-message` + +**User feature pages:** +- `user-presence`, `block-users`, `retrieve-users`, `user-management` + +**Group feature pages:** +- `groups-overview`, `create-group`, `join-group`, `leave-group`, `delete-group`, `update-group` +- `retrieve-groups`, `retrieve-group-members` +- `group-add-members`, `group-kick-ban-members` / `group-kick-member` +- `group-change-member-scope`, `transfer-group-ownership` + +**Conversation feature pages:** +- `retrieve-conversations`, `delete-conversation` + +**Calling feature pages:** +- `default-call` / `default-calling`, `direct-call` / `direct-calling` +- `call-logs`, `recording` + +**AI feature pages:** +- `ai-agents`, `ai-chatbots-overview`, `ai-moderation`, `ai-user-copilot-overview` + +### Quick Reference + Next Steps Only (No "Available Via") + +**Setup/config pages:** +- `overview`, `setup` / `setup-sdk`, `calling-setup` +- `key-concepts`, `authentication-overview` + +**Reference pages:** +- `all-real-time-listeners` / `all-real-time-delegates-listeners` +- `message-structure-and-hierarchy` +- `additional-message-filtering` +- `connection-status`, `session-timeout` +- `managing-web-sockets-connections-manually` / `managing-web-socket-connections-manually` +- `login-listener` / `login-listeners` + +**Calling config/customization pages:** +- `standalone-calling`, `presenter-mode`, `virtual-background` +- `video-view-customisation`, `custom-css` + +**Overview/hub pages:** +- `messaging-overview`, `users-overview`, `groups-overview` (gets Available Via), `calling-overview` +- `advanced-overview`, `resources-overview`, `extensions-overview` +- `ai-user-copilot-overview` (gets Available Via — it's a feature) + +**Guide pages:** +- `guides`, `guide-chat-only`, `guide-calls-only`, `guide-chat-calls` +- `guide-moderation`, `guide-notifications` + +**Framework pages (JavaScript SDK only):** +- `react-overview`, `angular-overview`, `vue-overview` + +**Migration pages:** +- `upgrading-from-v3`, `upgrading-from-v2`, `upgrading-from-v3-to-v4` + +**Platform-specific pages:** +- `android-overview`, `ios-overview` +- `publishing-app-on-playstore`, `publishing-app-on-appstore` +- `connection-behaviour`, `web-socket-connection-behaviour` +- Platform-specific push notification pages (iOS) + +**Resource pages:** +- `rate-limits`, `webhooks-overview` + +### Skip Entirely + +- `changelog` (auto-generated or link page) +- Legacy version folders (`2.0/`, `3.0/`) +- `research.md` (internal notes) + +--- + +## 16. File-by-File Checklist + +Use this checklist when improving each SDK documentation file: + +```text +[ ] Frontmatter has title, description (and sidebarTitle if needed) +[ ] Quick Reference block present at top (Info component with code) +[ ] "Available via" note present (ONLY if this is a feature page) +[ ] Introductory sentence explains what the feature does +[ ] All code examples have language tabs (JS/TS/Async or platform equivalents) +[ ] Tab titles use standard names (JavaScript/TypeScript/Async/Await, Kotlin/Java, Swift, Dart) +[ ] Parameter tables follow code examples where applicable +[ ] Object properties tables present for returned objects +[ ] Filter options table present for RequestBuilder pages +[ ] Pagination example shown for list/fetch operations +[ ] Real-time listeners documented with register + cleanup code +[ ] Best Practices section (AccordionGroup) where applicable +[ ] Troubleshooting section (AccordionGroup) where applicable +[ ] Next Steps section at bottom with CardGroup (2-4 relevant links) +[ ] Next Steps uses ## Next Steps heading (not variants) +[ ] No bullet-list links alongside CardGroup in Next Steps +[ ] Cross-links to related pages where concepts are referenced +[ ] Security warnings where applicable (init, auth keys, destructive operations) +[ ] Listener cleanup warnings on pages that register listeners +[ ] No content, code examples, diagrams, or explanatory text removed +[ ] Code is copy-paste ready with realistic placeholders +[ ] Mermaid diagrams preserved (never removed) +[ ] Framework-specific examples preserved +[ ] Server-side code examples preserved +[ ] Page reads naturally from top to bottom — journey feels logical +``` + +--- + +## 17. Prompt Template for AI Assistants + +When asking an AI assistant to improve SDK docs for any technology, use this prompt: + +```text +Improve the [TECHNOLOGY] SDK documentation files following these guidelines: + +1. Add a Quick Reference block at the top of every content page using component + with copy-paste ready code snippets (5-15 lines, most common use cases) + +2. Add "Available via: SDK | REST API | UI Kits" notes on FEATURE PAGES ONLY + (not setup, config, reference, guide, or migration pages) + +3. Ensure all code examples have language tabs: + - For JavaScript: JavaScript | TypeScript | Async/Await + - For Android: Kotlin | Java + - For iOS: Swift + - For Flutter: Dart + - For React Native: JavaScript | TypeScript + +4. Use standard tab titles: "JavaScript", "TypeScript", "Async/Await", "Kotlin", "Java", etc. + Use contextual titles for approach tabs: "To User", "To Group", "npm", "yarn" + +5. Add a description field to frontmatter on every page + +6. Add Next Steps navigation at the bottom of every page using + with 2-4 cards linking to logically next topics. Use ## Next Steps heading only. + +7. Use Mintlify components: , , , , + , , , , , + +8. CRITICAL: Do NOT remove any existing content, code examples, mermaid diagrams, + framework guides, server-side examples, or explanatory text. Only ADD improvements. + +9. Add cross-links between related feature pages + +10. Add security warnings on init/login pages + (Auth Key for dev only, Auth Token for production) + +11. Add listener cleanup warnings on pages that register listeners + +12. Add Best Practices and Troubleshooting AccordionGroups where applicable + +13. Preserve existing mermaid diagrams and flow charts + +Reference: sdk/documentation-improvement-guidelines.md +``` + +--- \ No newline at end of file diff --git a/sdk/android/v5/additional-message-filtering.mdx b/sdk/android/v5/additional-message-filtering.mdx index 6532fb806..a32f60db7 100644 --- a/sdk/android/v5/additional-message-filtering.mdx +++ b/sdk/android/v5/additional-message-filtering.mdx @@ -1263,7 +1263,7 @@ val UID = "cometchat-uid-1" val messagesRequest = MessagesRequestBuilder() .setLimit(50) .setUID(UID) - .setAttachmemnt(attachmentTypes) + .setAttachmentTypes(attachmentTypes) .build() ``` diff --git a/sdk/android/v5/delivery-read-receipts.mdx b/sdk/android/v5/delivery-read-receipts.mdx index 93f59de93..315f0e6c4 100644 --- a/sdk/android/v5/delivery-read-receipts.mdx +++ b/sdk/android/v5/delivery-read-receipts.mdx @@ -225,7 +225,7 @@ CometChat.markAsRead(message.id, message.sender.uid, CometChatConstants.RECEIVER ```java -CometChat.markAsRead(message.getId(), message.getReceiverUID(), CometChatConstants.RECEIVER_TYPE_GROUP,message.getSender().getUid()) +CometChat.markAsRead(message.getId(), message.getReceiverUid(), CometChatConstants.RECEIVER_TYPE_GROUP,message.getSender().getUid()) ``` @@ -263,7 +263,7 @@ CometChat.markAsRead(message.getId(), message.getSender().getUid(),CometChatCons ```java -CometChat.markAsRead(message.getId(), message.getRecieverUID(), CometChatConstants.RECEIVER_TYPE_USER, message.getSender().getUid(), new CometChat.CallbackListener() { +CometChat.markAsRead(message.getId(), message.getReceiverUid(), CometChatConstants.RECEIVER_TYPE_USER, message.getSender().getUid(), new CometChat.CallbackListener() { @Override public void onSuccess(Void unused) { Log.e(TAG, "markAsRead : " + "Success"); diff --git a/sdk/android/v5/edit-message.mdx b/sdk/android/v5/edit-message.mdx index a710c009c..73cc2f039 100644 --- a/sdk/android/v5/edit-message.mdx +++ b/sdk/android/v5/edit-message.mdx @@ -87,7 +87,7 @@ CometChat.editMessage(updatedMessage, object: CometChat.CallbackListener -The object of the edited message will be returned in the `onSucess()` callback method of the listener. The message object will contain the `editedAt` field set with the timestamp of the time the message was edited. This will help you identify if the message was edited while iterating through the list of messages. The `editedBy` field is also set to the `UID` of the user who edited the message. +The object of the edited message will be returned in the `onSuccess()` callback method of the listener. The message object will contain the `editedAt` field set with the timestamp of the time the message was edited. This will help you identify if the message was edited while iterating through the list of messages. The `editedBy` field is also set to the `UID` of the user who edited the message. By default, CometChat allows certain roles to edit a message. diff --git a/sdk/android/v5/flag-message.mdx b/sdk/android/v5/flag-message.mdx index 0843d2902..ea962c80d 100644 --- a/sdk/android/v5/flag-message.mdx +++ b/sdk/android/v5/flag-message.mdx @@ -69,7 +69,7 @@ Before flagging a message, retrieve the list of available flag reasons configure Log.d(TAG, "Flag reasons fetched: " + reasons); // Use reasons to populate your report dialog UI for (FlagReason reason : reasons) { - Log.d(TAG, "Reason ID: " + reason.getId() + ", Title: " + reason.getReason()); + Log.d(TAG, "Reason ID: " + reason.getId() + ", Title: " + reason.getName()); } } diff --git a/sdk/android/v5/llms-android-v5.mdx b/sdk/android/v5/llms-android-v5.mdx new file mode 100644 index 000000000..1aed991bb --- /dev/null +++ b/sdk/android/v5/llms-android-v5.mdx @@ -0,0 +1,139 @@ +--- +title: "Android Chat SDK v5 — LLM docs index" +description: "Machine-readable, Android-SDK-v5-scoped index of every SDK page as a clean .md twin. Built for AI coding agents; kept out of the human sidebar." +--- + +{/* + SCOPED LLM INDEX for the Android Chat SDK v5. + - UNLISTED, NOT hidden: intentionally omitted from docs.json navigation so it never shows in + the human sidebar — but it IS built, served as a clean .md twin, and INDEXED for search + + AI assistants (so AI tools, and this pack's skill via its docs-map, can discover and read it). + - We deliberately do NOT use `hidden: true`/`noindex` here: in Mintlify `hidden` auto-applies + noindex, which would drop this page from search AND the auto global llms.txt / AI context. + We want it discoverable, so it stays indexable. + - Fetch this file's own .md twin as a lightweight, Android-SDK-only routing index instead of + the site-wide /docs/llms.txt (which spans every product and is far larger). + - URL NOTE: Android SDK v5 pages live under the versioned path /sdk/android/v5/... — + the unversioned /sdk/android/... tree is v4. Do not mix them. +*/} + +# Android Chat SDK v5 — LLM docs index (Latest) + +> Low-level Android (Kotlin/Java) chat + calling client. Gradle coordinate +> `com.cometchat:chat-sdk-android:5.+` (calls add `com.cometchat:calls-sdk-android:5.+`). This +> page is an **Android-SDK-v5-only** routing index for AI agents — a scoped alternative to the +> site-wide `/docs/llms.txt`. + +## How to use this index +Each link points to the docs page; **append `.md`** to its URL to fetch the clean Markdown twin +(verbatim code + method signatures, parameters, and listener contracts). Pick the page for the +intent, then read the API there. +- Convention: any docs page URL + `.md` → raw Markdown. +- Fallback: if a `.md` twin 404s, fetch the same URL **without** `.md` (HTML). Never answer + APIs from memory. +- Pages show Kotlin and Java variants side by side where they differ. + +## Hot path — usually no fetch needed +For a plain "add chat" the Gradle setup, `init → login`, and the core send/receive listener flow +are stable; a well-built agent skill bakes them. Fetch below only for exhaustive parameters, +long-tail methods, group/user management, calling, or edge-case listeners. +- Setup: [Integration / Setup](/sdk/android/v5/setup) +- Auth/lifecycle: [Authentication](/sdk/android/v5/authentication-overview) +- Core send/receive: [Send a Message](/sdk/android/v5/send-message) · [Receive Messages](/sdk/android/v5/receive-messages) · [Real-time Listeners](/sdk/android/v5/real-time-listeners) + +## Getting started / integration +- [Android SDK — Overview](/sdk/android/v5/android-overview) +- [Overview](/sdk/android/v5/overview) +- [Integration / Setup](/sdk/android/v5/setup) +- [Key Concepts](/sdk/android/v5/key-concepts) +- [Authentication](/sdk/android/v5/authentication-overview) +- [Login Listeners](/sdk/android/v5/login-listeners) + +## Messaging +- [Messaging — Overview](/sdk/android/v5/messaging-overview) +- [Send a Message](/sdk/android/v5/send-message) +- [Media & File Messages](/sdk/android/v5/upload-files) +- [Receive Messages](/sdk/android/v5/receive-messages) +- [Additional Message Filtering](/sdk/android/v5/additional-message-filtering) +- [Retrieve Conversations](/sdk/android/v5/retrieve-conversations) +- [Threaded Messages](/sdk/android/v5/threaded-messages) +- [Edit a Message](/sdk/android/v5/edit-message) +- [Delete a Message](/sdk/android/v5/delete-message) +- [Flag a Message](/sdk/android/v5/flag-message) +- [Delete a Conversation](/sdk/android/v5/delete-conversation) +- [Typing Indicators](/sdk/android/v5/typing-indicators) +- [Delivery & Read Receipts](/sdk/android/v5/delivery-read-receipts) +- [Transient Messages](/sdk/android/v5/transient-messages) +- [Mentions](/sdk/android/v5/mentions) +- [Reactions](/sdk/android/v5/reactions) + +## Calling +- [Calling — Overview](/sdk/android/v5/calling-overview) + +## Users +- [Users — Overview](/sdk/android/v5/users-overview) +- [Retrieve Users](/sdk/android/v5/retrieve-users) +- [User Management](/sdk/android/v5/user-management) +- [Block Users](/sdk/android/v5/block-users) +- [User Presence](/sdk/android/v5/user-presence) + +## Groups +- [Groups — Overview](/sdk/android/v5/groups-overview) +- [Retrieve Groups](/sdk/android/v5/retrieve-groups) +- [Create a Group](/sdk/android/v5/create-group) +- [Update a Group](/sdk/android/v5/update-group) +- [Join a Group](/sdk/android/v5/join-group) +- [Leave a Group](/sdk/android/v5/leave-group) +- [Delete a Group](/sdk/android/v5/delete-group) +- [Retrieve Group Members](/sdk/android/v5/retrieve-group-members) +- [Add Group Members](/sdk/android/v5/group-add-members) +- [Kick / Ban Members](/sdk/android/v5/group-kick-member) +- [Change Member Scope](/sdk/android/v5/group-change-member-scope) +- [Transfer Group Ownership](/sdk/android/v5/transfer-group-ownership) + +## AI & advanced features +- [AI Moderation](/sdk/android/v5/ai-moderation) +- [AI Agents](/sdk/android/v5/ai-agents) +- [AI User Copilot — Overview](/sdk/android/v5/ai-user-copilot-overview) +- [AI Chatbots — Overview](/sdk/android/v5/ai-chatbots-overview) +- [Campaigns](/sdk/android/v5/campaigns) +- [Extensions — Overview](/sdk/android/v5/extensions-overview) +- [Webhooks — Overview](/sdk/android/v5/webhooks-overview) + +## Resources & listeners +- [Resources — Overview](/sdk/android/v5/resources-overview) +- [Real-time Listeners](/sdk/android/v5/real-time-listeners) +- [Message Structure & Hierarchy](/sdk/android/v5/message-structure-and-hierarchy) +- [Rate Limits](/sdk/android/v5/rate-limits) + +## Advanced +- [Advanced — Overview](/sdk/android/v5/advanced-overview) +- [Connection Status](/sdk/android/v5/connection-status) +- [Connection Behaviour](/sdk/android/v5/connection-behaviour) +- [Publishing your app on the Play Store](/sdk/android/v5/publishing-app-on-playstore) + +## Want ready-made UI instead? — the Android UI Kit +This SDK is headless: it gives you data and methods, no screens. If the app needs a conversation +list, a message list or a composer, the UI Kit already ships them (and sits on this SDK, so +`init`/`login` are shared — never initialise twice). +- **Android UI Kit v6 — scoped LLM index:** [llms-android-v6](/ui-kit/android/llms-android-v6) +- Use the SDK directly for what the kit has no component for: unread counts, webhooks, low-level + presence/connection, granular group management, ban/unban round-trips. + +## Feature switched on OUTSIDE the app — dashboard, extensions, AI +Sending the right SDK call is not enough when the capability is dashboard-gated. These pages are +outside the SDK tree: +- Start here: [Extensions overview](/fundamentals/extensions-overview) · [Key concepts](/fundamentals/key-concepts) +- **Message extensions:** [Polls](/fundamentals/polls) · [Stickers](/fundamentals/stickers) · [Collaborative whiteboard](/fundamentals/collaborative-whiteboard) · [Collaborative document](/fundamentals/collaborative-document) · [Link preview](/fundamentals/link-preview) · [Message translation](/fundamentals/message-translation) · [Thumbnail generation](/fundamentals/thumbnail-generation) +- **AI (user copilot):** [Overview](/fundamentals/ai-user-copilot/overview) · [Smart replies](/fundamentals/ai-user-copilot/smart-replies) · [Conversation starter](/fundamentals/ai-user-copilot/conversation-starter) · [Conversation summary](/fundamentals/ai-user-copilot/conversation-summary) · [AI agents](/ai-agents) +- **Moderation:** [Moderation extensions](/fundamentals/moderation-extensions) · [Overview](/moderation/overview) · [Getting started](/moderation/getting-started) · [Rules](/moderation/rules-management) · [Lists](/moderation/lists-management) · [Flagged messages](/moderation/flagged-messages) + +## Push, campaigns, auth & webhooks +- **Push (Android):** [Push overview](/notifications/push-overview) · [**Android push notifications**](/notifications/android-push-notifications) · [Badge count](/notifications/badge-count) · [Limits](/notifications/constraints-and-limits) · [Notification extensions](/fundamentals/notification-extensions) +- **Campaigns:** [Campaigns](/campaigns/campaigns) · [Templates](/campaigns/templates) · [Channels](/campaigns/channels) +- **Auth & permissions:** [User auth](/fundamentals/user-auth) · [Roles & permissions](/fundamentals/user-roles-and-permissions) · [Mentions](/fundamentals/mentions) +- **Server-side hooks:** [Webhooks overview](/fundamentals/webhooks-overview) · [Call webhooks](/calls/webhooks) · [Ringing webhooks](/calls/webhooks-ringing) + +## Migration & misc +- [Upgrading from v4](/sdk/android/v5/upgrading-from-v4) +- [Changelog](/sdk/android/v5/changelog) diff --git a/sdk/android/v5/send-message.mdx b/sdk/android/v5/send-message.mdx index aa799028a..1f27bd8a6 100644 --- a/sdk/android/v5/send-message.mdx +++ b/sdk/android/v5/send-message.mdx @@ -795,7 +795,7 @@ The parameters involved are: 3. `customType` - custom message type that you need to set 4. `customData` - The data to be passed as the message in the form of a JSONObject. -You can also use the subType field of the `CustomMessage` class to set a specific type for the custom message. This can be achieved using the `setSubtype()` method. +You can also use the subType field of the `CustomMessage` class to set a specific type for the custom message. This can be achieved using the `setSubType()` method. ### Add Tags diff --git a/sdk/android/v5/typing-indicators.mdx b/sdk/android/v5/typing-indicators.mdx index 452fd1f4a..6e7ae3489 100644 --- a/sdk/android/v5/typing-indicators.mdx +++ b/sdk/android/v5/typing-indicators.mdx @@ -13,7 +13,7 @@ title: "Typing Indicators" You can use the `startTyping()` method to inform the receiver that the logged in user has started typing. The receiver will receive this information in the `onTypingStarted()` method of the `MessageListener` class. In order to send the typing indicator, you need to use the `TypingIndicator` class. - + ```java TypingIndicator typingIndicator = new TypingIndicator(UID, CometChatConstants.RECEIVER_TYPE_USER); @@ -22,7 +22,7 @@ CometChat.startTyping(typingIndicator); - + ```kotlin val typingIndicator =TypingIndicator(UID,CometChatConstants.RECEIVER_TYPE_USER) @@ -31,7 +31,7 @@ CometChat.startTyping(typingIndicator) - + ```java TypingIndicator typingIndicator = new TypingIndicator(GUID, CometChatConstants.RECEIVER_TYPE_GROUP); @@ -40,7 +40,7 @@ CometChat.startTyping(typingIndicator); - + ```kotlin val typingIndicator = TypingIndicator(GUID,CometChatConstants.RECEIVER_TYPE_GROUP) @@ -56,16 +56,16 @@ CometChat.startTyping(typingIndicator) You can use the `endTyping()` method to inform the receiver that the logged in user has stopped typing. The receiver will receive this information in the `onTypingEnded()` method of the `MessageListener` class. In order to send the typing indicator, you need to use the `TypingIndicator` class. - + ```java TypingIndicator typingIndicator = new TypingIndicator(UID, CometChatConstants.RECEIVER_TYPE_USER); -CometChat.endtyping(typingIndicator); +CometChat.endTyping(typingIndicator); ``` - + ```kotlin val typingIndicator = TypingIndicator(UID,CometChatConstants.RECEIVER_TYPE_USER) @@ -74,7 +74,7 @@ CometChat.endTyping(typingIndicator) - + ```java TypingIndicator typingIndicator = new TypingIndicator(GUID, CometChatConstants.RECEIVER_TYPE_GROUP); @@ -83,7 +83,7 @@ CometChat.endTyping(typingIndicator); - + ```kotlin val typingIndicator = TypingIndicator(GUID,CometChatConstants.RECEIVER_TYPE_GROUP) diff --git a/ui-kit/android/call-logs.mdx b/ui-kit/android/call-logs.mdx index c6aa9ff42..34d6381d8 100644 --- a/ui-kit/android/call-logs.mdx +++ b/ui-kit/android/call-logs.mdx @@ -11,6 +11,33 @@ description: "Scrollable list of call logs for the logged-in user with caller na --- + + +**Requires the Calls SDK AND calling to be initialized — this component CRASHES otherwise.** +`CometChatCallLogs` builds a `CallLogRequest` in its ViewModel's `init {}`, with **no availability +check**, so simply placing it on a screen is fatal unless both conditions hold. Verified on device: + +| Calls artifact | `uiKit.enableCalling` | Result | +|---|---|---| +| absent | anything | `java.lang.NoClassDefFoundError: …CallLogRequest$CallLogRequestBuilder` | +| present | `false` | `java.lang.RuntimeException: Please call the CometChatCalls.init() method …` | +| present | `true` | renders (empty/error state when there are no logs) | + +Both are required: + +```kotlin +// app/build.gradle.kts +implementation("com.cometchat:calls-sdk-android:5.0.+") +``` +```json +// app/src/main/assets/cometchat-settings.json — this is what makes the UI Kit init CometChatCalls +{ "uiKit": { "enableCalling": true } } +``` + +The component **compiles fine** in every case — the failure is runtime-only, so a build cannot warn +you. The same applies to the other calling components. + + ## Where It Fits `CometChatCallLogs` is a list component. It renders the user's call history and emits the selected `CallLog` via `onItemClick`. Use it as a standalone call history screen or as a tab in a tabbed layout alongside conversations and contacts. diff --git a/ui-kit/android/calling-integration.mdx b/ui-kit/android/calling-integration.mdx index 5a8914a00..ea501b9d4 100644 --- a/ui-kit/android/calling-integration.mdx +++ b/ui-kit/android/calling-integration.mdx @@ -11,6 +11,23 @@ This guide walks you through adding voice and video calling capabilities to your Make sure you've completed the [Getting Started](/ui-kit/android/getting-started) guide before proceeding. + + +**`enableCalling: true` makes the Calls SDK dependency mandatory — otherwise the app crashes at +launch.** With the flag set, `CometChatUIKit.initFromSettings()` calls `initCometChatCalls()`, which +throws if `com.cometchat:calls-sdk-android` is absent: + +``` +java.lang.NoClassDefFoundError: Failed resolution of: + Lcom/cometchat/calls/core/CometChatCalls$SessionSettingsBuilder; + at com.cometchat.uikit.core.CometChatUIKit.initCometChatCalls(CometChatUIKit.kt:229) +``` + +The crash happens in `onCreate`, **before any UI renders** — the flag name gives no hint that a +dependency is implied. Change the flag and the dependency together, or leave `enableCalling` as +`false` in an app that does not use calling. + + ## Add the Calls SDK Add the CometChat Calls SDK dependency alongside your chosen UI Kit module: diff --git a/ui-kit/android/conversation-message-view.mdx b/ui-kit/android/conversation-message-view.mdx index 0218a4c47..5f7325e28 100644 --- a/ui-kit/android/conversation-message-view.mdx +++ b/ui-kit/android/conversation-message-view.mdx @@ -177,6 +177,22 @@ fun ConversationsScreen( --- + +**`enableEdgeToEdge()` alone is not enough.** It draws your layout edge-to-edge, so the UI Kit +toolbar renders **under the status bar** and the title collides with the clock. Give the layout root +an `android:id` and consume the insets (add `Type.ime()` on the message screen so the composer rides +above the keyboard): + +```kotlin +ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.root)) { v, insets -> + val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars()) + val ime = insets.getInsets(WindowInsetsCompat.Type.ime()) + v.setPadding(bars.left, bars.top, bars.right, maxOf(bars.bottom, ime.bottom)) + insets +} +``` + + ## Step 2: Set Up the Message Screen diff --git a/ui-kit/android/custom-text-formatter-guide.mdx b/ui-kit/android/custom-text-formatter-guide.mdx index 89c7b5070..354d8da38 100644 --- a/ui-kit/android/custom-text-formatter-guide.mdx +++ b/ui-kit/android/custom-text-formatter-guide.mdx @@ -108,19 +108,20 @@ override fun prepareRightMessageBubbleSpan( ```kotlin lines -import com.cometchat.uikit.core.CometChatUIKit -val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, messageComposer.additionParameter) -textFormatters.add(HashTagFormatter()) -messageComposer.setTextFormatters(textFormatters) +// V6: build the list yourself. The composer auto-adds a default CometChatMentionsFormatter, +// and setTextFormatters REPLACES the list — include the mentions formatter to keep @mentions. +messageComposer.setTextFormatters( + listOf(CometChatMentionsFormatter(this), HashTagFormatter()) +) ``` ```kotlin lines -import com.cometchat.uikit.core.CometChatUIKit // In your composable or ViewModel setup -val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(context, additionParameter) +// V6: build the list yourself — setTextFormatters REPLACES the default list. +val textFormatters = listOf(CometChatMentionsFormatter(context), HashTagFormatter()) textFormatters.add(HashTagFormatter()) CometChatMessageComposer( diff --git a/ui-kit/android/getting-started-jetpack.mdx b/ui-kit/android/getting-started-jetpack.mdx index e84b77251..535240723 100644 --- a/ui-kit/android/getting-started-jetpack.mdx +++ b/ui-kit/android/getting-started-jetpack.mdx @@ -45,6 +45,23 @@ Auth Key is for development only. In production, generate Auth Tokens server-sid --- + + +**`enableCalling: true` makes the Calls SDK dependency mandatory — otherwise the app crashes at +launch.** With the flag set, `CometChatUIKit.initFromSettings()` calls `initCometChatCalls()`, which +throws if `com.cometchat:calls-sdk-android` is absent: + +``` +java.lang.NoClassDefFoundError: Failed resolution of: + Lcom/cometchat/calls/core/CometChatCalls$SessionSettingsBuilder; + at com.cometchat.uikit.core.CometChatUIKit.initCometChatCalls(CometChatUIKit.kt:229) +``` + +The crash happens in `onCreate`, **before any UI renders** — the flag name gives no hint that a +dependency is implied. Change the flag and the dependency together, or leave `enableCalling` as +`false` in an app that does not use calling. + + ## Step 1 — Create an Android Project 1. Open Android Studio and start a new project. @@ -107,6 +124,19 @@ dependencies { --- + +**Required dependency exclude.** The UI Kit pulls `io.noties:prism4j`, which brings +`org.jetbrains:annotations-java5:17.0.0`. That duplicates `org.jetbrains:annotations:23.0.0` from +AndroidX/Kotlin and the build fails at dexing with ~40 `Duplicate class org.jetbrains.annotations.*` +errors. Add this to your app module: + +```kotlin +configurations.all { + exclude(group = "org.jetbrains", module = "annotations-java5") +} +``` + + ## Step 3 — Initialize and Login Create your `MainActivity.kt` with the CometChat initialization and login flow. Since Compose uses a declarative approach, we track the auth state and render UI conditionally: diff --git a/ui-kit/android/getting-started-kotlin.mdx b/ui-kit/android/getting-started-kotlin.mdx index 08fb97062..42a2f8e02 100644 --- a/ui-kit/android/getting-started-kotlin.mdx +++ b/ui-kit/android/getting-started-kotlin.mdx @@ -45,6 +45,23 @@ Auth Key is for development only. In production, generate Auth Tokens server-sid --- + + +**`enableCalling: true` makes the Calls SDK dependency mandatory — otherwise the app crashes at +launch.** With the flag set, `CometChatUIKit.initFromSettings()` calls `initCometChatCalls()`, which +throws if `com.cometchat:calls-sdk-android` is absent: + +``` +java.lang.NoClassDefFoundError: Failed resolution of: + Lcom/cometchat/calls/core/CometChatCalls$SessionSettingsBuilder; + at com.cometchat.uikit.core.CometChatUIKit.initCometChatCalls(CometChatUIKit.kt:229) +``` + +The crash happens in `onCreate`, **before any UI renders** — the flag name gives no hint that a +dependency is implied. Change the flag and the dependency together, or leave `enableCalling` as +`false` in an app that does not use calling. + + ## Step 1 — Create an Android Project 1. Open Android Studio and start a new project. @@ -110,6 +127,35 @@ android.enableJetifier=true --- + +**Required dependency exclude.** The UI Kit pulls `io.noties:prism4j`, which brings +`org.jetbrains:annotations-java5:17.0.0`. That duplicates `org.jetbrains:annotations:23.0.0` from +AndroidX/Kotlin and the build fails at dexing with ~40 `Duplicate class org.jetbrains.annotations.*` +errors. Add this to your app module: + +```kotlin +configurations.all { + exclude(group = "org.jetbrains", module = "annotations-java5") +} +``` + + + +**Required app theme.** The UI Kit's views are Material components, so on a non-Material theme the +first CometChat view you inflate throws `IllegalArgumentException: The style on this component +requires your app theme to be Theme.MaterialComponents (or a descendant)` — the app crashes on the +chat screen rather than rendering it unstyled. Inherit the kit's theme, which already descends from +Material: + +```xml res/values/themes.xml +