diff --git a/jetpack_to_android.md b/jetpack_to_android.md new file mode 100644 index 0000000000..e8c09b4cd4 --- /dev/null +++ b/jetpack_to_android.md @@ -0,0 +1,407 @@ +# Implementation Plan: Migrate `jetpack` snippet annotation to `chat_android` + +## Problem Statement + +The current branch (`fix/jetpack-snippets-for-android`) has already renamed `` ```jetpack `` code block annotations to `` ```android `` in chat MDX pages (commit `853cb94ff`). However, this creates a **conflict** because `android` already exists as a language identifier with `syntaxHighlighterKey: "java"`, while the Jetpack Compose snippets need `syntaxHighlighterKey: "kotlin"`. + +### The Conflict + +| Identifier | Label | Icon | syntaxHighlighterKey | Used In | +|---|---|---|---|---| +| `android` (existing) | Android | `icon-tech-android-head` | `java` | `` in API reference pages (push-admin, push, types) | +| `jetpack` (original) | Jetpack Compose | `icon-tech-jetpack` | `kotlin` | Chat product code blocks + `` | +| `android` (current branch) | Android | `icon-tech-android-head` | `java` | ❌ Kotlin code gets Java highlighting | + +The current branch's `` ```android `` code blocks hit the existing `android` entry in [`languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts:118) which applies `java` syntax highlighting to Kotlin code. Additionally, the `` tags (52 occurrences) were **NOT updated** in the branch commit. + +### Current State of the Branch + +- **Code blocks**: All 78 occurrences of `` ```jetpack `` have been changed to `` ```android `` across 13 chat MDX files +- **`` tags**: All 52 occurrences of `` / `` are **still unchanged** +- **Language config files**: `types.ts`, `languageInfo.ts`, `languageData.ts` still reference `jetpack` + +## Recommended Approach: Use `chat_android` prefix for code blocks + +### Why `chat_android`? + +The codebase has a well-established pattern for product-scoped language prefixes: + +- `realtime_javascript`, `realtime_python`, etc. — used in Pub/Sub pages to differentiate Realtime vs REST SDK variants +- `rest_javascript`, `rest_php`, etc. — same pattern for REST SDK + +The prefix system works as follows: + +1. **[`onCreatePage.ts`](data/onCreatePage.ts:39)** extracts language identifiers from `` ```language `` annotations via regex (`/```(\w+)/g`) and stores them in `pageContext.languages` +2. **[`layout-context.tsx`](src/contexts/layout-context.tsx:63)** calls `stripSdkType()` to remove the prefix when building the language selector (e.g., `realtime_javascript` → `javascript`) +3. **[`CodeSnippet.tsx`](../ably-ui/src/core/CodeSnippet.tsx:202)** detects `realtime_` and `rest_` prefixes to show the SDK type selector (Realtime/REST toggle) +4. **[`languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts:135)** `stripSdkType()` currently only strips `realtime_` and `rest_` prefixes +5. **[`getLanguageInfo()`](../ably-ui/src/core/CodeSnippet/languages.ts:143)** strips the prefix first, then looks up label, icon, and `syntaxHighlighterKey` +6. **[`LanguageSelector.tsx`](../ably-ui/src/core/CodeSnippet/LanguageSelector.tsx:22)** calls `getLanguageInfo(lang)` with the **full** language key (e.g., `chat_android`) to get label and icon for tabs + +Using `chat_android` follows this same convention — it's a product-scoped variant of `android` that can have its own `syntaxHighlighterKey: "kotlin"`. + +### Why NOT just change `android`'s `syntaxHighlighterKey` to `kotlin`? + +- `android` with `syntaxHighlighterKey: "java"` is used in API reference pages via `` conditionals (81 occurrences across push-admin, push, types pages) +- These pages reference the Java-based Android Pub/Sub SDK, not the Kotlin Chat SDK +- The `android` language is listed in [`pubsub.ts`](src/data/nav/pubsub.ts:401) navigation config for push-related pages with explicit `languages` arrays +- Changing `android`'s `syntaxHighlighterKey` to `kotlin` would break Java syntax highlighting for all existing Pub/Sub Android content + +### Label and Icon: "Android" with android icon (NOT "Jetpack Compose") + +The user wants the UI to display **"Android"** as the label with the **`icon-tech-android-head`** icon, not "Jetpack Compose" with the jetpack icon. This makes sense because: + +- The Chat SDK for Android is the **Ably Chat Kotlin SDK** used on Android — "Jetpack Compose" is an implementation detail of the UI framework, not the SDK identity +- Users searching for "Android" support should see "Android" in the language selector +- The nav already shows "Kotlin (Android)" for the getting-started page in [`chat.ts`](src/data/nav/chat.ts:37) +- The existing `android` entry already has `label: "Android"` and `icon: "icon-tech-android-head"` — the `chat_android` entry should match + +## Implementation Steps + +### Phase 1: Update `ably-ui` (CodeSnippet/languages.ts) + +#### 1.1 Add `chat_android` to the languages map + +In [`../ably-ui/src/core/CodeSnippet/languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts:11): + +```typescript +chat_android: { + label: "Android", + icon: "icon-tech-android-head", + syntaxHighlighterKey: "kotlin", +}, +``` + +This entry uses: +- `label: "Android"` — consistent with the existing `android` entry, shows "Android" in code snippet tabs +- `icon: "icon-tech-android-head"` — the Android icon, same as the existing `android` entry +- `syntaxHighlighterKey: "kotlin"` — correct syntax highlighting for Kotlin/Jetpack Compose code + +#### 1.2 Update `stripSdkType()` to handle `chat_` prefix + +In [`../ably-ui/src/core/CodeSnippet/languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts:135): + +```typescript +export const stripSdkType = (lang: string) => { + if (lang.startsWith("realtime_") || lang.startsWith("rest_") || lang.startsWith("chat_")) { + return lang.split("_").slice(1).join("_"); + } + return lang; +}; +``` + +`stripSdkType("chat_android")` will return `"android"`, which is the base language key used for the language selector in the sidebar. + +#### 1.3 Update `getLanguageInfo()` to check full key first + +**Critical**: The current [`getLanguageInfo()`](../ably-ui/src/core/CodeSnippet/languages.ts:143) strips the prefix first, then looks up the stripped key. This means `getLanguageInfo("chat_android")` would return the `android` entry with `syntaxHighlighterKey: "java"` — **wrong**. + +Both [`LanguageSelector.tsx`](../ably-ui/src/core/CodeSnippet/LanguageSelector.tsx:22) and [`CodeSnippet.tsx`](../ably-ui/src/core/CodeSnippet.tsx:300) call `getLanguageInfo()` with the **full** language key (e.g., `chat_android`). So we need `getLanguageInfo()` to check the full key first: + +```typescript +export const getLanguageInfo = (langKey: string): LanguageInfo => { + // Check full key first (e.g., "chat_android" has its own entry) + if (languages[langKey.toLowerCase()]) { + return languages[langKey.toLowerCase()]; + } + + // Then try stripping the SDK type prefix + const key = stripSdkType(langKey).toLowerCase(); + if (languages[key]) { + return languages[key]; + } + + // Fallback for unknown languages + return { + label: langKey, + icon: "icon-tech-web", + syntaxHighlighterKey: langKey, + }; +}; +``` + +This way: +- `getLanguageInfo("chat_android")` → matches `chat_android` entry → `syntaxHighlighterKey: "kotlin"` ✅ +- `getLanguageInfo("realtime_javascript")` → no `realtime_javascript` entry → strips to `javascript` → matches ✅ +- `getLanguageInfo("android")` → matches `android` entry → `syntaxHighlighterKey: "java"` ✅ + +#### 1.4 Ensure `chat_` prefix doesn't trigger SDK type selector + +In [`CodeSnippet.tsx`](../ably-ui/src/core/CodeSnippet.tsx:202), the SDK type detection only checks for `realtime_` and `rest_`: + +```typescript +if (codeLanguage.startsWith("realtime_")) { + sdkTypes.add("realtime"); +} else if (codeLanguage.startsWith("rest_")) { + sdkTypes.add("rest"); +} +``` + +`chat_android` will **not** trigger the SDK selector, which is correct — Chat pages don't need a Realtime/REST toggle. **No change needed here.** + +#### 1.5 Fix `activeLanguage` resolution in `CodeSnippet.tsx` (CRITICAL) + +**This is the most critical change.** The `realtime_`/`rest_` prefixes work because the SDK type selector reconstructs the full key (e.g., `"realtime_" + "javascript"` → `"realtime_javascript"`). But `chat_` has no SDK type selector, so there's no reconstruction. + +The problem: [`MDXWrapper.tsx`](src/components/Layout/MDXWrapper.tsx:144) passes `activePage.language` (which is **stripped** to `"android"`) as the `lang` prop to `CodeSnippet`. Inside [`CodeSnippet.tsx`](../ably-ui/src/core/CodeSnippet.tsx:258), the `activeLanguage` computation does: + +```typescript +// Current code (line 258-268): +const activeLanguage = useMemo(() => { + if (resolvedSdk && sdkTypes.has(resolvedSdk)) { + return `${resolvedSdk}_${lang}`; // Only works for realtime_/rest_ + } + if (lang) return lang; // Returns "android" — but code blocks have "chat_android"! + ... +``` + +Then at line 292-294, the code filters: `codeData.filter(code => code.language === activeLanguage)`. Since `"android" !== "chat_android"`, **no code block matches and nothing renders**. + +**Fix**: Update the `activeLanguage` computation to find the matching prefixed language when the stripped `lang` doesn't directly match: + +```typescript +const activeLanguage = useMemo(() => { + if (resolvedSdk && sdkTypes.has(resolvedSdk)) { + return `${resolvedSdk}_${lang}`; + } + + if (lang) { + // Check if lang matches directly in the available languages + if (languages.includes(lang)) return lang; + // Check if lang matches a prefixed language when stripped + // (e.g., lang="android" matches "chat_android" after stripping) + const prefixedMatch = languages.find((l) => stripSdkType(l) === lang); + if (prefixedMatch) return prefixedMatch; + return lang; + } + + if (filteredLanguages.length > 0) return filteredLanguages[0]; + + return languages[0]; +}, [resolvedSdk, sdkTypes, lang, filteredLanguages, languages]); +``` + +This way: +- `lang = "android"`, `languages = ["javascript", "swift", "kotlin", "chat_android"]` +- `languages.includes("android")` → `false` +- `languages.find((l) => stripSdkType(l) === "android")` → finds `"chat_android"` ✅ +- `activeLanguage = "chat_android"` → matches code block data ✅ + +**This is backward-compatible** because: +- For `realtime_`/`rest_` prefixes: the `resolvedSdk` path handles them first (no change) +- For unprefixed languages like `"javascript"`: `languages.includes("javascript")` → `true` → returns directly (no change) +- For `chat_android`: the new `prefixedMatch` path kicks in only when needed + +**Verification of the full round-trip:** +1. User clicks "Android" tab → `handleLanguageChange("chat_android")` → `onChange(stripSdkType("chat_android"))` → `onChange("android")` → navigates to `?lang=android` +2. Page reloads → `activePage.language = "android"` → `lang = "android"` → `activeLanguage` finds `"chat_android"` via `prefixedMatch` → code block renders ✅ + +#### 1.6 Optionally remove or keep `jetpack` entry + +The `jetpack` entry in [`languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts:128) can be kept for backward compatibility or removed. Recommended: **remove it** since no code blocks will use it after migration. + +### Phase 2: Update `ably-docs` language configuration + +#### 2.1 Update [`src/data/languages/types.ts`](src/data/languages/types.ts:1) + +Replace `jetpack` with `chat_android` in the `languageKeys` array: + +```diff + 'laravel', + 'typescript', +- 'jetpack', ++ 'chat_android', +``` + +#### 2.2 Update [`src/data/languages/languageInfo.ts`](src/data/languages/languageInfo.ts:89) + +Replace `jetpack` entry with `chat_android`: + +```diff +- jetpack: { +- label: 'Jetpack Compose', +- syntaxHighlighterKey: 'kotlin', +- }, ++ chat_android: { ++ label: 'Android', ++ syntaxHighlighterKey: 'kotlin', ++ }, +``` + +Note: label is `"Android"` (not `"Jetpack Compose"`) to match the ably-ui entry and user expectations. + +#### 2.3 Update [`src/data/languages/languageData.ts`](src/data/languages/languageData.ts:38) + +Change the chat product's language list. **Use `android` as the key** (not `chat_android`), because [`determineActiveLanguage()`](src/contexts/layout-context.tsx:43) compares stripped language keys against `languageData[product]` keys: + +```diff + chat: { + javascript: '1.1', + react: '1.1', + swift: '1.0', + kotlin: '1.1', +- jetpack: '1.1', ++ android: '1.1', + }, +``` + +**Why `android` and not `chat_android`?** The flow is: +1. `pageContext.languages` contains `["javascript", "react", "swift", "kotlin", "chat_android"]` +2. [`layout-context.tsx:63`](src/contexts/layout-context.tsx:63) strips them: `["javascript", "react", "swift", "kotlin", "android"]` +3. [`determineActiveLanguage()`](src/contexts/layout-context.tsx:43) filters: `activeLanguages.filter((lang) => Object.keys(languageData[product]).includes(lang))` +4. So `"android"` must match a key in `languageData.chat` — hence `android: '1.1'` + +**Note**: `android` is NOT in `languageData.pubsub`, so there's no conflict. The pubsub nav pages that use `` get their language lists from the `languages` array in [`pubsub.ts`](src/data/nav/pubsub.ts:401) nav config, not from `languageData`. + +### Phase 3: Update MDX content files + +#### 3.1 Rename code block annotations + +In all chat MDX files, change the current `` ```android `` (which was already changed from `` ```jetpack `` in the branch) to `` ```chat_android ``: + +```diff +- ```android ++ ```chat_android +``` + +**Files to update** (13 files, all already using `` ```android `` from the branch commit): + +- [`src/pages/docs/chat/connect.mdx`](src/pages/docs/chat/connect.mdx) +- [`src/pages/docs/chat/setup.mdx`](src/pages/docs/chat/setup.mdx) +- [`src/pages/docs/chat/getting-started/android.mdx`](src/pages/docs/chat/getting-started/android.mdx) +- [`src/pages/docs/chat/rooms/history.mdx`](src/pages/docs/chat/rooms/history.mdx) +- [`src/pages/docs/chat/rooms/index.mdx`](src/pages/docs/chat/rooms/index.mdx) +- [`src/pages/docs/chat/rooms/media.mdx`](src/pages/docs/chat/rooms/media.mdx) +- [`src/pages/docs/chat/rooms/message-reactions.mdx`](src/pages/docs/chat/rooms/message-reactions.mdx) +- [`src/pages/docs/chat/rooms/messages.mdx`](src/pages/docs/chat/rooms/messages.mdx) +- [`src/pages/docs/chat/rooms/occupancy.mdx`](src/pages/docs/chat/rooms/occupancy.mdx) +- [`src/pages/docs/chat/rooms/presence.mdx`](src/pages/docs/chat/rooms/presence.mdx) +- [`src/pages/docs/chat/rooms/reactions.mdx`](src/pages/docs/chat/rooms/reactions.mdx) +- [`src/pages/docs/chat/rooms/replies.mdx`](src/pages/docs/chat/rooms/replies.mdx) +- [`src/pages/docs/chat/rooms/typing.mdx`](src/pages/docs/chat/rooms/typing.mdx) + +#### 3.2 Update `` conditional tags + +**Critical**: The branch commit did NOT update `` tags. There are **52 occurrences** across chat MDX files that need updating. + +The [`If.tsx`](src/components/Layout/mdx/If.tsx:22) component compares `lang` prop values against `activePage.language`, which comes from `stripSdkType`-processed languages. So `activePage.language` will be `"android"` (stripped from `chat_android`). + +**Therefore, use `` in MDX files** (not ``). This is consistent with how `` works for both `realtime_javascript` and `rest_javascript` code blocks. + +Two patterns exist: + +**Pattern A — Jetpack-only conditionals:** +```diff +- ++ +``` + +**Pattern B — Multi-language conditionals including jetpack:** +```diff +- ++ +``` + +**No conflict with existing `` in API reference pages**: Those pages are in the `pubsub` product context with different language sets. The `android` language appears in the language selector on pubsub push pages (via nav config `languages` arrays in [`pubsub.ts`](src/data/nav/pubsub.ts:401)) and on chat pages (via `languageData.chat`). The `` tags work correctly in both contexts because they're on different pages with different active language sets — a user can only have one active language per page. + +### Phase 4: No changes needed in `layout-context.tsx` + +The [`layout-context.tsx`](src/contexts/layout-context.tsx:63) imports `stripSdkType` from ably-ui: + +```typescript +languages = Array.from(new Set(pageContext.languages.map(stripSdkType))) as LanguageKey[]; +``` + +After the ably-ui update (Phase 1.2), `stripSdkType("chat_android")` will return `"android"`, so the language selector will correctly show "Android" as an option on chat pages. **No additional change needed here** beyond the ably-ui update. + +### Phase 5: Clean up `jetpack` references + +#### 5.1 Remove `jetpack` from [`types.ts`](src/data/languages/types.ts:29) (covered in 2.1) + +#### 5.2 Remove `jetpack` from [`languageInfo.ts`](src/data/languages/languageInfo.ts:89) (covered in 2.2) + +#### 5.3 Remove `jetpack` from ably-ui [`languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts:128) (covered in 1.6) + +## Summary of All Changes + +### ably-ui (separate PR/update) + +| File | Change | +|---|---| +| [`CodeSnippet/languages.ts`](../ably-ui/src/core/CodeSnippet/languages.ts) | Add `chat_android` entry with `label: "Android"`, `icon: "icon-tech-android-head"`, `syntaxHighlighterKey: "kotlin"`. Update `stripSdkType()` to handle `chat_` prefix. Update `getLanguageInfo()` to check full key first. Remove `jetpack` entry. | +| [`CodeSnippet.tsx`](../ably-ui/src/core/CodeSnippet.tsx) | **CRITICAL**: Update `activeLanguage` computation to resolve stripped `lang` prop back to the full prefixed key (e.g., `"android"` → `"chat_android"`) by searching the available `languages` array. Without this, code blocks using `chat_android` won't render when the active language is `"android"`. | + +### ably-docs + +| File | Change | +|---|---| +| [`src/data/languages/types.ts`](src/data/languages/types.ts) | Replace `jetpack` with `chat_android` in `languageKeys` | +| [`src/data/languages/languageInfo.ts`](src/data/languages/languageInfo.ts) | Replace `jetpack` entry with `chat_android` (label: `"Android"`) | +| [`src/data/languages/languageData.ts`](src/data/languages/languageData.ts) | Change `jetpack: '1.1'` to `android: '1.1'` in chat config | +| 13 chat MDX files | Change `` ```android `` → `` ```chat_android `` (code blocks) | +| 13 chat MDX files | Change `` → `` and `` → `` | + +## Data Flow Summary + +Here's the complete data flow for `chat_android` through the system: + +``` +MDX file: ```chat_android + ↓ +onCreatePage.ts: extracts "chat_android" into pageContext.languages + ↓ +layout-context.tsx: stripSdkType("chat_android") → "android" + ↓ (for language selector sidebar) + activePage.languages = ["javascript", "react", "swift", "kotlin", "android"] + activePage.language = "android" (matched against languageData.chat keys) + ↓ +If.tsx: matches activePage.language === "android" ✅ + ↓ +MDXWrapper.tsx: passes lang={activePage.language} = "android" to CodeSnippet + ↓ +CodeSnippet.tsx activeLanguage computation: + lang = "android", languages = ["javascript", "swift", "kotlin", "chat_android"] + → languages.includes("android") = false + → languages.find(l => stripSdkType(l) === "android") = "chat_android" + → activeLanguage = "chat_android" ✅ + ↓ +CodeSnippet.tsx: codeData.filter(code => code.language === "chat_android") → matches ✅ + ↓ +LanguageSelector.tsx: getLanguageInfo("chat_android") + → matches chat_android entry → label: "Android", icon: "icon-tech-android-head" ✅ + ↓ +CodeSnippet.tsx (line 300): getLanguageInfo("chat_android") + → matches chat_android entry → syntaxHighlighterKey: "kotlin" ✅ + ↓ +User clicks "Android" tab: + → handleLanguageChange("chat_android") + → onChange(stripSdkType("chat_android")) = onChange("android") + → navigate("?lang=android") + → activePage.language = "android" → cycle repeats ✅ +``` + +## Risk Assessment + +| Risk | Mitigation | +|---|---| +| ably-ui update needed first | Coordinate PR timing; ably-ui change is backward-compatible | +| `` overlap between chat and pub/sub | No actual conflict — different product contexts, different page language sets. `android` is NOT in `languageData.pubsub`; pubsub push pages get their `android` language from nav config `languages` arrays. | +| `stripSdkType` change affects existing behavior | Only adds `chat_` handling; `realtime_` and `rest_` unchanged | +| `languageData` key mismatch | Use `android` (not `chat_android`) as the key in `languageData.chat` | +| `getLanguageInfo()` change breaks existing lookups | Full-key-first lookup is additive; existing keys like `realtime_javascript` have no entry in the map, so they still fall through to stripped lookup | +| `activeLanguage` resolution fails for `chat_` prefix | Fixed by adding `prefixedMatch` fallback in `CodeSnippet.tsx` `activeLanguage` computation (Phase 1.5). Backward-compatible: unprefixed languages match directly, `realtime_`/`rest_` use the existing `resolvedSdk` path. | + +## Alternatives Considered + +### Alternative 1: Modify existing `android` entry to use `kotlin` + +**Rejected** because: +1. The existing `android` with Java highlighting is used in 81+ `` occurrences in API reference pages +2. If Pub/Sub Android pages ever add Java code blocks with `` ```android ``, they'd get Kotlin highlighting — incorrect +3. The `chat_` prefix approach is cleaner and follows established patterns + +### Alternative 2: Keep `` ```android `` as-is (current branch state) + +**Rejected** because: +1. `getLanguageInfo("android")` returns `syntaxHighlighterKey: "java"` — Kotlin code gets Java highlighting +2. Would require changing the existing `android` entry's `syntaxHighlighterKey`, breaking pub/sub pages diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts index 507ce00839..db68469c71 100644 --- a/src/data/languages/languageData.ts +++ b/src/data/languages/languageData.ts @@ -40,7 +40,7 @@ export default { react: '1.1', swift: '1.0', kotlin: '1.1', - jetpack: '1.1', + android: '1.1', }, aiTransport: { javascript: '2.11', diff --git a/src/data/languages/languageInfo.ts b/src/data/languages/languageInfo.ts index 69f589b8ea..794b95da74 100644 --- a/src/data/languages/languageInfo.ts +++ b/src/data/languages/languageInfo.ts @@ -77,6 +77,7 @@ export default { android: { label: 'Android', syntaxHighlighterKey: 'java', + alias: 'android-full', }, flutter: { label: 'Flutter', @@ -86,9 +87,10 @@ export default { label: 'Kotlin', syntaxHighlighterKey: 'kotlin', }, - jetpack: { - label: 'Jetpack Compose', + chat_android: { + label: 'Android', syntaxHighlighterKey: 'kotlin', + alias: 'android-full', }, realtime: { label: 'Realtime', diff --git a/src/data/languages/types.ts b/src/data/languages/types.ts index e975fe3265..37ec10b0af 100644 --- a/src/data/languages/types.ts +++ b/src/data/languages/types.ts @@ -26,7 +26,7 @@ export const languageKeys = [ 'css', 'laravel', 'typescript', - 'jetpack', + 'chat_android', ] as const; export type LanguageKey = (typeof languageKeys)[number]; diff --git a/src/pages/docs/chat/connect.mdx b/src/pages/docs/chat/connect.mdx index 24553bd74f..c1ede4bbb3 100644 --- a/src/pages/docs/chat/connect.mdx +++ b/src/pages/docs/chat/connect.mdx @@ -20,8 +20,8 @@ A connection can have any of the following statuses: | `closed` | The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically. No connection state is preserved by the service or the library. | | `failed` | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. | - -Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html) property to check which status a connection is currently in: + +Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html) property to check which status a connection is currently in: @@ -57,7 +57,7 @@ let status = chatClient.connection.status val connectionStatus = chatClient.connection.status ``` -```jetpack +```chat_android val connectionStatus = chatClient.connection.status ``` @@ -88,7 +88,7 @@ Listeners can also be registered to monitor the changes in connection status. An Use the [`connection.onStatusChange()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#onStatusChange)[`connection.onStatusChange()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connection/onstatuschange%28%29-76t7)[`connection.onStatusChange()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/on-status-change.html) method to register a listener for status change updates: - + Use the [`collectAsStatus()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/jetpack/chat-extensions-compose/com.ably.chat.extensions.compose/collect-as-status.html) composable function to observe the connection status: @@ -123,7 +123,7 @@ val (off) = chatClient.connection.onStatusChange { statusChange: ConnectionStatu } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.ChatClient @@ -174,7 +174,7 @@ The Chat SDK provides an `onDiscontinuity()` handler exposed via the Room object Any hooks that take an optional listener to monitor their events, such as typing indicator events in the `useTyping` hook, can also register a listener to be notified of, and handle, periods of discontinuity. - + Use the [`discontinuityAsFlow()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/discontinuity-as-flow.html) extension function to observe discontinuity events as a Flow in Jetpack Compose: @@ -215,7 +215,7 @@ val (off) = room.onDiscontinuity { reason: ErrorInfo -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.Room import com.ably.chat.discontinuityAsFlow diff --git a/src/pages/docs/chat/getting-started/android.mdx b/src/pages/docs/chat/getting-started/android.mdx index f830241c47..d9a85d50a9 100644 --- a/src/pages/docs/chat/getting-started/android.mdx +++ b/src/pages/docs/chat/getting-started/android.mdx @@ -30,7 +30,7 @@ Create a new Android project with Jetpack Compose. For detailed instructions, re 6. Add the Ably dependencies to your app-level `build.gradle.kts` file: -```kotlin +```chat_android implementation("com.ably.chat:chat:") // This package contains extension functions for better Jetpack Compose integration. // It's experimental for now (safe to use, but the API may change later). You can always use its code as a reference. @@ -71,7 +71,7 @@ Replace the contents of your `MainActivity.kt` file with the following code to s Note that this is for example purposes only. In production, you should use [token authentication](/docs/auth/token) to avoid exposing your API keys publicly, the [`clientId`](/docs/auth/identified-clients) is used to identify the client: -```kotlin +```chat_android package com.example.chatexample import android.os.Bundle @@ -147,7 +147,7 @@ Clients establish a connection with Ably when they instantiate an SDK. This enab In your `MainActivity.kt` file, add the following `ConnectionStatusUi` composable component: -```kotlin +```chat_android // This component will display the current connection status @Composable fun ConnectionStatusUi(connection: Connection) { @@ -164,7 +164,7 @@ fun ConnectionStatusUi(connection: Connection) { Update the `App` component to display the connection status using the new `ConnectionStatusUi` component: -```kotlin +```chat_android @Composable fun App(chatClient: ChatClient) { Scaffold { paddingValues -> @@ -190,7 +190,7 @@ Now that you have a connection to Ably, you can create a room. Use rooms to sepa In your project, open `MainActivity.kt`, and add a new component called `RoomStatusUi`: -```kotlin +```chat_android @Composable fun RoomStatusUi(roomName: String, room: Room?) { val roomStatus = room?.collectAsStatus()?.value @@ -206,7 +206,7 @@ fun RoomStatusUi(roomName: String, room: Room?) { Update your main app component to get and attach to the room and nest the `RoomStatusUi` component inside it: -```kotlin +```chat_android @Composable fun App(chatClient: ChatClient) { val roomName = "my-first-room" @@ -244,7 +244,7 @@ Messages are how your clients interact with one another. In your project, open `MainActivity.kt`, and add a new component called `ChatBox`: -```kotlin +```chat_android @Composable fun ChatBox(room: Room?) { val scope = rememberCoroutineScope() @@ -368,7 +368,7 @@ fun ChatBox(room: Room?) { Add the `ChatBox` component to your main app component: -```kotlin +```chat_android @Composable fun App(chatClient: ChatClient) { val roomName = "my-first-room" @@ -421,7 +421,7 @@ If your client makes a typo, or needs to update their original message then they 1. We will begin by adding this utility function to facilitate message data updates in the UI: - ```kotlin + ```chat_android inline fun MutableList.replaceFirstWith(replacement: T, predicate: (T) -> Boolean) { val index = indexOfFirst(predicate) if (index != -1) set(index, replacement) @@ -432,7 +432,7 @@ If your client makes a typo, or needs to update their original message then they 2. Add the edited state variable: -```kotlin +```chat_android var edited: Message? by remember { mutableStateOf(null) } ``` @@ -440,7 +440,7 @@ var edited: Message? by remember { mutableStateOf(null) } 3. Update the message subscription to handle edited messages: -```kotlin +```chat_android LaunchedEffect(room) { room?.messages?.asFlow()?.collect { event -> when (event.type) { @@ -461,7 +461,7 @@ the message content itself, along with the sender's username and the message tim Once we've identified this `Column`, we will integrate the new edit button alongside these existing elements. Replace the `Column` with the following: -```kotlin +```chat_android Row( modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically @@ -500,7 +500,7 @@ Row( 5. Update the send button to handle both new messages and edits: -```kotlin +```chat_android Button( onClick = { sending = true @@ -540,7 +540,7 @@ Ably Chat enables you to retrieve previously sent messages in a room. This is us Extend the `ChatBox` component to include a method to retrieve the last 10 messages when the component mounts. In your `MainActivity.kt` file, add the `DisposableEffect` in your `ChatBox` component: -```kotlin +```chat_android fun ChatBox(room: Room?) { /* variables declaration */ var subscription by remember { mutableStateOf(null) } @@ -579,7 +579,7 @@ You also can use `collectAsPagingMessagesState` to automatically subscribe to ne and lazily load previous messages as you scroll through the message list. -```kotlin +```chat_android @Composable fun ChatBox(room: Room?) { val scope = rememberCoroutineScope() @@ -715,7 +715,7 @@ Display the online status of clients using the presence feature. This enables cl In your `MainActivity.kt` file, create a new component called `PresenceStatusUi`: -```kotlin +```chat_android @Composable fun PresenceStatusUi(room: Room?) { val membersState = room?.collectAsPresenceMembers() @@ -737,7 +737,7 @@ fun PresenceStatusUi(room: Room?) { Add the `PresenceStatusUi` component to your main app component: -```kotlin +```chat_android @Composable fun App(chatClient: ChatClient) { val roomName = "my-first-room" @@ -787,7 +787,7 @@ Clients can send a reaction to a room to show their sentiment for what is happen In your `MainActivity.kt` file, add a new component called `ReactionBar`: -```kotlin +```chat_android @Composable fun ReactionBar(room: Room?) { val scope = rememberCoroutineScope() @@ -864,7 +864,7 @@ fun ReactionBar(room: Room?) { Add the `ReactionBar` component to your main app component: -```kotlin +```chat_android @Composable fun App(chatClient: ChatClient) { val roomName = "my-first-room" @@ -913,7 +913,7 @@ ably rooms reactions send my-first-room 👍 To gracefully close connection and clean up resources, you can subscribe to activity lifecycle events and close the connection when activity has paused or stopped, and then reconnect when activity resumes. To do this modify `MainActivity` class: -```kotlin +```chat_android class MainActivity : ComponentActivity() { private lateinit var realtimeClient: AblyRealtime private lateinit var chatClient: ChatClient diff --git a/src/pages/docs/chat/rooms/history.mdx b/src/pages/docs/chat/rooms/history.mdx index 6c1c616acb..316f986baf 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -7,8 +7,8 @@ The history feature enables users to retrieve messages that have been previously ## Retrieve previously sent messages - -Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. + +Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. @@ -72,7 +72,7 @@ while (historicalMessages.hasNext()) { println("End of messages") ``` -```jetpack +```chat_android var historicalMessages = room.messages.history(orderBy = OrderBy.NewestFirst) println(historicalMessages.items.toString()) @@ -103,7 +103,7 @@ Users can also retrieve historical messages that were sent to a room before the Use the [`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#historyBeforeSubscribe)[`historyBeforeSubscribe(withParams:)`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscriptionresponse/historybeforesubscribe%28withparams%3A%29))[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html) function returned as part of a [message subscription](/docs/chat/rooms/messages#subscribe) response to only retrieve messages that were received before the listener was subscribed to the room. This returns a paginated response, which can be queried further to retrieve the next set of messages. - + Use the [`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html) function returned as part of a [message subscription](/docs/chat/rooms/messages#subscribe) response to only retrieve messages that were received before the listener was subscribed to the room. This returns a paginated response, which can be queried further to retrieve the next set of messages. @@ -185,7 +185,7 @@ while (historicalMessages.hasNext()) { println("End of messages") ``` -```jetpack +```chat_android import androidx.compose.foundation.layout.* import androidx.compose.material.* import androidx.compose.runtime.* @@ -241,7 +241,7 @@ The following parameters can be passed when retrieving previously sent messages: | `end` | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | | `limit` | Maximum number of messages to be retrieved per page, up to 1,000. | - + ## Messages pagination @@ -269,7 +269,7 @@ The returned [`PagingMessagesState`](https://sdk.ably.com/builds/ably/ably-chat- - `refresh()`: A function to clear the error state and retry loading -```jetpack +```chat_android import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.material.Button diff --git a/src/pages/docs/chat/rooms/index.mdx b/src/pages/docs/chat/rooms/index.mdx index 321ca0a08d..7856be0eb7 100644 --- a/src/pages/docs/chat/rooms/index.mdx +++ b/src/pages/docs/chat/rooms/index.mdx @@ -21,8 +21,8 @@ The default 30-day retention period can be extended up to 365 days by [contactin Users send messages to a room and subscribe to the room in order to receive messages. - -To get an instance of a chat room, use the [`rooms.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#get)[`rooms.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/get%28named%3Aoptions%3A%29)[`rooms.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-rooms/get.html) method. It will create a new room instance if one doesn't already exist, or return the existing one if it does. + +To get an instance of a chat room, use the [`rooms.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#get)[`rooms.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/get%28named%3Aoptions%3A%29)[`rooms.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-rooms/get.html) method. It will create a new room instance if one doesn't already exist, or return the existing one if it does. @@ -71,7 +71,7 @@ let room = try await chatClient.rooms.get(named: "basketball-stream", options: . val room = chatClient.rooms.get(roomId = "basketball-stream") ``` -```jetpack +```chat_android val room = chatClient.rooms.get(roomId = "basketball-stream") ``` @@ -83,9 +83,9 @@ If the value changes between re-renders then the room will be discarded and recr - + -When you create or retrieve a room using `rooms.get()`, you can provide custom configuration for some features for that room by passing a [`RoomOptions`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html)[`RoomOptions`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions)[`RoomOptions`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room-options/index.html) object as the second argument. If you do not provide a `RoomOptions` object, the default settings will be used. +When you create or retrieve a room using `rooms.get()`, you can provide custom configuration for some features for that room by passing a [`RoomOptions`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html)[`RoomOptions`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions)[`RoomOptions`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room-options/index.html) object as the second argument. If you do not provide a `RoomOptions` object, the default settings will be used. ```javascript @@ -125,7 +125,7 @@ val room = chatClient.rooms.get(roomId = "basketball-stream") { } ``` -```jetpack +```chat_android val room = chatClient.rooms.get(roomId = "basketball-stream") { typing { heartbeatThrottle = 5.seconds @@ -156,8 +156,8 @@ Releasing a room allows the underlying resources to be garbage collected or rele Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it may be more beneficial. Also, proactively disconnecting rather than waiting for the standard two-minute timeout can help reduce costs and improve performance. - -Once [`rooms.release()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#release)[`rooms.release()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/release%28named%3A%29)[`rooms.release()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-rooms/release.html) has been called, the room will be unusable and a new instance will need to be created using [`rooms.get()`](#create) if you want to reuse it. + +Once [`rooms.release()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#release)[`rooms.release()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/release%28named%3A%29)[`rooms.release()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-rooms/release.html) has been called, the room will be unusable and a new instance will need to be created using [`rooms.get()`](#create) if you want to reuse it. ```javascript @@ -172,7 +172,7 @@ try await rooms.release(named: "basketball-stream") rooms.release("basketball-stream") ``` -```jetpack +```chat_android rooms.release("basketball-stream") ``` @@ -190,10 +190,10 @@ By default the `ChatRoomProvider` will automatically call [`release()`](https:// To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions. - + Once an instance of a room has been created using `rooms.get()`, clients attach to it to start receiving messages and events from the room. -Use the [`attach()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/attach%28%29)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/attach.html) method on a room to attach to it: +Use the [`attach()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/attach%28%29)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/attach.html) method on a room to attach to it: @@ -226,7 +226,7 @@ try await room.attach() room.attach() ``` -```jetpack +```chat_android room.attach() ``` @@ -241,8 +241,8 @@ As soon as a client is attached to a room, Ably will begin streaming messages an ### Detach from a room - -Use the [`detach()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#detach)[`detach()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/detach%28%29)[`detach()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/detach.html) method on a room to detach from it and stop receiving messages and events: + +Use the [`detach()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#detach)[`detach()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/detach%28%29)[`detach()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/detach.html) method on a room to detach from it and stop receiving messages and events: ```javascript @@ -257,7 +257,7 @@ try await room.detach() room.detach() ``` -```jetpack +```chat_android room.detach() ``` @@ -288,8 +288,8 @@ A room can have any of the following statuses: | `suspended` | The room, having previously been attached, has lost continuity. This is normally due to the client being disconnected from Ably for more than two minutes. The client will automatically attempt to reattach as soon as connectivity is restored. | | `failed` | An indefinite failure condition. This status is entered if an error has been received from Ably, such as an attempt to attach without the necessary access rights. | - -Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/status.html) property to check which status a room is currently in: + +Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/status.html) property to check which status a room is currently in: @@ -331,7 +331,7 @@ let status = room.status val status = room.status ``` -```jetpack +```chat_android val status = room.status ``` @@ -342,7 +342,7 @@ You can also subscribe to room status updates by registering a listener. An even Use the [`room.onStatusChange()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#onStatusChange)[`room.onStatusChange()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/onstatuschange%28%29-s9g)[`room.onStatusChange()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/on-status-change.html) method in a room to register a listener for status change updates: - + Use the [`collectAsStatus()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/jetpack/chat-extensions-compose/com.ably.chat.extensions.compose/collect-as-status.html) extension function to observe room status changes reactively in Jetpack Compose: @@ -365,7 +365,7 @@ val (off) = room.onStatusChange { statusChange: RoomStatusChange -> } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room diff --git a/src/pages/docs/chat/rooms/media.mdx b/src/pages/docs/chat/rooms/media.mdx index e96b225d22..a2acdbf744 100644 --- a/src/pages/docs/chat/rooms/media.mdx +++ b/src/pages/docs/chat/rooms/media.mdx @@ -94,7 +94,7 @@ suspend fun uploadMedia(): JsonObject { } ``` -```jetpack +```chat_android import com.ably.chat.json.* suspend fun uploadMedia(): JsonObject { @@ -174,7 +174,7 @@ suspend fun onMediaAttach() { } ``` -```jetpack +```chat_android import androidx.compose.foundation.layout.* import androidx.compose.material.* import androidx.compose.runtime.* @@ -307,7 +307,7 @@ suspend fun send(text: String, mediaToAttach: List) { } ``` -```jetpack +```chat_android import androidx.compose.foundation.layout.* import androidx.compose.material.* import androidx.compose.runtime.* @@ -448,7 +448,7 @@ fun getValidMedia(message: Message): List { } ``` -```jetpack +```chat_android import com.ably.chat.Message import com.ably.chat.json.* @@ -606,7 +606,7 @@ fun createMessageView(message: Message, context: android.content.Context): View } ``` -```jetpack +```chat_android import androidx.compose.foundation.layout.* import androidx.compose.material.* import androidx.compose.runtime.* @@ -727,7 +727,7 @@ suspend fun addMediaToMessage(message: Message, mediaData: JsonObject) { } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.* @@ -875,7 +875,7 @@ suspend fun removeMediaFromMessage(message: Message, mediaIdToRemove: String) { } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.* diff --git a/src/pages/docs/chat/rooms/message-reactions.mdx b/src/pages/docs/chat/rooms/message-reactions.mdx index 57d86dcd11..9dcda8ec9f 100644 --- a/src/pages/docs/chat/rooms/message-reactions.mdx +++ b/src/pages/docs/chat/rooms/message-reactions.mdx @@ -23,7 +23,7 @@ Note that if sending two identical reactions of type `Distinct`, the second one ### Configure the default reaction type - + The default reaction type can be configured at room-level by passing `RoomOptions` when calling `rooms.get`. If nothing is set, the default is `Distinct`. @@ -59,7 +59,7 @@ val room = ablyChatClient.rooms.get("room1") { } ``` -```jetpack +```chat_android val room = ablyChatClient.rooms.get("room1") { messages { defaultMessageReactionType = MessageReactionType.Unique @@ -89,7 +89,7 @@ const MyComponent = () => { ## Sending a message reaction - + To send a message reaction use `room.messages.reactions.send(message, params)`. This method takes the following parameters: * `message` - The message to send the reaction to. Can be either a Message object or a string containing the message serial. * `params` - Set the `name`, and optionally override the `type` or set a `count`. @@ -170,7 +170,7 @@ room.messages.reactions.send(message, ) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Message @@ -255,7 +255,7 @@ The `annotation-publish` capability is required for sending reactions. ## Removing a message reaction - + To remove a message reaction use `room.messages.reactions.delete(message, params)`. This method takes the following parameters: * `message` - The message to remove the reaction from. This can be a Message object, or just the string serial. * `params` - Set the `name`, and optionally override the `type` or set a `count`. @@ -357,7 +357,7 @@ room.messages.reactions.delete(message, ) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Message @@ -519,7 +519,7 @@ reactions = MessageReactionSummary( ) ``` -```jetpack +```chat_android interface Message { // ... (other fields omitted) val reactions: MessageReactionSummary @@ -559,11 +559,11 @@ Always call `Message.with(event)` when applying message events and reaction even ## Subscribing to message reactions - + Ably generates a summary (aggregate) of the reactions for each message and for each reaction type. For displaying accurate counts for message reactions, subscribe to changes in the message summary. - + Use the [`reactions.asFlow()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/as-flow.html) to receive new message reactions: @@ -590,7 +590,7 @@ room.messages.reactions.subscribe { event -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.Room @@ -677,7 +677,7 @@ room.messages.reactions.subscribe { event -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.Message import com.ably.chat.Room @@ -802,7 +802,7 @@ val room = ablyChatClient.rooms.get("room1") { } ``` -```jetpack +```chat_android val room = ablyChatClient.rooms.get("room1") { messages { rawMessageReactions = true @@ -829,7 +829,7 @@ const MyComponent = () => { ``` - + Then you can receive raw reactions using the `room.messages.reactions.subscribeRaw()` method: @@ -868,7 +868,7 @@ room.messages.reactions.subscribeRaw { event -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.MessageReactionEventType import com.ably.chat.Room diff --git a/src/pages/docs/chat/rooms/messages.mdx b/src/pages/docs/chat/rooms/messages.mdx index c511a13f78..626c1f8400 100644 --- a/src/pages/docs/chat/rooms/messages.mdx +++ b/src/pages/docs/chat/rooms/messages.mdx @@ -17,7 +17,7 @@ A user can also update or delete a message, all users that are subscribed to the Subscribe to receive messages in a room by registering a listener. Use the [`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/subscribe%28%29-360z1)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/subscribe.html) method in a room to receive all messages that are sent to it: - + You can use [`messages.asFlow()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/as-flow.html) to receive new messages: @@ -62,7 +62,7 @@ val subscription = room.messages.subscribe { messageEvent: ChatMessageEvent -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.Room import com.ably.chat.asFlow @@ -126,7 +126,7 @@ See [below](#global-ordering) for more information on how to apply deterministic Use the `unsubscribe()` function returned in the `subscribe()` response to remove a chat message listener: - + `messages.asFlow()` handles lifecycle and cleanup automatically. @@ -168,8 +168,8 @@ The [`detach()`](/docs/chat/rooms#detach) method detaches a user from the room. ## Send a message - -Use the [`messages.send()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#send)[`messages.send()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/send%28withparams%3A%29)[`messages.send()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/send.html) method to send a message in a chat room. All users that are [subscribed](#subscribe) to messages on that room will receive it: + +Use the [`messages.send()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#send)[`messages.send()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/send%28withparams%3A%29)[`messages.send()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/send.html) method to send a message in a chat room. All users that are [subscribed](#subscribe) to messages on that room will receive it: @@ -207,7 +207,7 @@ let message = try await room.messages.send(withParams: .init(text: "hello")) room.messages.send(text = "hello") ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -230,8 +230,8 @@ fun MyComponent(room: Room) { ## Get a single message - -Use the [`messages.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get)[`messages.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/get%28withserial:%29)[`messages.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/get.html) method to get a message in a chat room using message serial. + +Use the [`messages.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get)[`messages.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/get%28withserial:%29)[`messages.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/get.html) method to get a message in a chat room using message serial. @@ -269,7 +269,7 @@ let message = try await room.messages.get(withSerial: "01726232498871-001@abcdef val message = room.messages.get("01726232498871-001@abcdefghij:001") ``` -```jetpack +```chat_android val message = room.messages.get("01726232498871-001@abcdefghij:001") ``` @@ -278,8 +278,8 @@ val message = room.messages.get("01726232498871-001@abcdefghij:001") ## Update a message - -Use the [`messages.update()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#update)[`messages.update()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/update%28withserial:params:details:%29)[`messages.update()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/update.html) method to update a message in a chat room. All users that are [subscribed](#subscribe) to messages on that room will receive the update: + +Use the [`messages.update()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#update)[`messages.update()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/update%28withserial:params:details:%29)[`messages.update()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/update.html) method to update a message in a chat room. All users that are [subscribed](#subscribe) to messages on that room will receive the update: @@ -336,7 +336,7 @@ val updatedMessage = room.messages.update( ) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Message @@ -366,8 +366,8 @@ fun MyComponent(room: Room) { ### Filter for updates - -Use the [`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/subscribe%28%29-8jolq)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/subscribe.html) method to receive messages in a room. To filter for updated messages, provide a listener that checks the `type``action` property of the message event: + +Use the [`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/subscribe%28%29-8jolq)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/subscribe.html) method to receive messages in a room. To filter for updated messages, provide a listener that checks the `type``action` property of the message event: @@ -458,7 +458,7 @@ val messagesSubscription = room.messages.subscribe { event -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.ChatMessageEventType import com.ably.chat.Message @@ -534,8 +534,8 @@ The updated message response is identical to the structure of a message, with th ## Delete a message - -Use the [`messages.delete()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#delete)[`messages.delete()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/delete%28withserial:details:%29)[`messages.delete()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/delete.html) method to delete a message in a chat room. All users that are [subscribed](#subscribe) to messages on that room will receive the deletion: + +Use the [`messages.delete()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#delete)[`messages.delete()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/delete%28withserial:details:%29)[`messages.delete()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/delete.html) method to delete a message in a chat room. All users that are [subscribed](#subscribe) to messages on that room will receive the deletion: @@ -591,7 +591,7 @@ val deletedMessage = room.messages.delete( ) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Message @@ -620,8 +620,8 @@ fun MyComponent(room: Room) { ### Filter for deletes - -Use the [`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/subscribe%28%29-8jolq)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/subscribe.html) method to receive messages in a room. To filter for deleted messages, provide a listener that checks the `type``action` property of the message event: + +Use the [`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#subscribe)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/subscribe%28%29-8jolq)[`messages.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/subscribe.html) method to receive messages in a room. To filter for deleted messages, provide a listener that checks the `type``action` property of the message event: @@ -712,7 +712,7 @@ val messagesSubscription = room.messages.subscribe { event -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.ChatMessageEventType import com.ably.chat.Message diff --git a/src/pages/docs/chat/rooms/occupancy.mdx b/src/pages/docs/chat/rooms/occupancy.mdx index fcfec67a71..39011b4705 100644 --- a/src/pages/docs/chat/rooms/occupancy.mdx +++ b/src/pages/docs/chat/rooms/occupancy.mdx @@ -15,7 +15,7 @@ Occupancy generates messages on any client entering/leaving a room, and so incre Subscribe to a room's occupancy by registering a listener. Occupancy events are emitted whenever the number of online users within a room changes. Use the [`occupancy.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#subscribe)[`occupancy.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/subscribe%28%29-3loon)[`occupancy.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/subscribe.html) method in a room to receive updates: - + Use the [`collectAsOccupancy()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/jetpack/chat-extensions-compose/com.ably.chat.extensions.compose/collect-as-occupancy.html) extension function to observe occupancy changes reactively in Jetpack Compose: @@ -63,7 +63,7 @@ val subscription = room.occupancy.subscribe { event: OccupancyEvent -> } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -101,7 +101,7 @@ The following is the structure of an occupancy event: - + ```json { @@ -126,7 +126,7 @@ The following are the properties of an occupancy event: - + | Property | Description | Type | | -------- | ----------- | ---- | @@ -146,7 +146,7 @@ A user is counted for every device that they are in the room with. For example, Use the `unsubscribe()` function returned in the `subscribe()` response to remove a room occupancy listener: - + Jetpack Compose automatically handles lifecycle and cleanup when using `collectAsOccupancy()`. @@ -186,9 +186,9 @@ unsubscribe() The latest occupancy received in realtime (the same mechanism that powers occupancy subscriptions) can be retrieved in a one-off call. - + -Use the [`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#current)[`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/current)[`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/current.html) property to retrieve the most recently received room occupancy: +Use the [`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#current)[`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/current)[`occupancy.current`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/current.html) property to retrieve the most recently received room occupancy: ```javascript @@ -203,7 +203,7 @@ let occupancy = room.occupancy.current val occupancy = room.occupancy.current ``` -```jetpack +```chat_android val occupancy = room.occupancy.current ``` @@ -234,10 +234,10 @@ The following are the properties of the occupancy data: ## Retrieve room occupancy - + The occupancy of a room can be retrieved in one-off calls instead of subscribing to updates. -Use the [`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#get)[`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/get%28%29)[`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/get.html) method to retrieve the occupancy of a room: +Use the [`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#get)[`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy/get%28%29)[`occupancy.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-occupancy/get.html) method to retrieve the occupancy of a room: ```javascript @@ -252,7 +252,7 @@ let occupancy = try await room.occupancy.get() val occupancy = room.occupancy.get() ``` -```jetpack +```chat_android val occupancy = room.occupancy.get() ``` diff --git a/src/pages/docs/chat/rooms/presence.mdx b/src/pages/docs/chat/rooms/presence.mdx index 71530003fd..ccd5e93dbf 100644 --- a/src/pages/docs/chat/rooms/presence.mdx +++ b/src/pages/docs/chat/rooms/presence.mdx @@ -11,7 +11,7 @@ The presence feature of a chat room enables online users to advertise to others Subscribe to users' presence status by registering a listener. Presence events are emitted whenever a member enters or leaves the presence set, or updates their user data. Use the [`presence.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#subscribe)[`presence.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/subscribe%28_%3A%29)[`presence.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/subscribe.html) method in a room to receive updates: - + Use the [`collectAsPresenceMembers()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/jetpack/chat-extensions-compose/com.ably.chat.extensions.compose/collect-as-presence-members.html) extension function to observe user presence changes reactively in Jetpack Compose: @@ -77,7 +77,7 @@ val subscription = room.presence.subscribe { event: PresenceEvent -> } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -115,7 +115,7 @@ The following are the properties of a presence event: Use the `unsubscribe()` function returned in the `subscribe()` response to remove a presence listener: - + Jetpack Compose automatically handles lifecycle and cleanup when using `collectAsPresenceMembers()`. @@ -159,8 +159,8 @@ Users can enter and leave the presence set of a room to indicate when they are o Users must be identified to enter into the presence set. This means that they must set a `clientId` when [instantiating their client](/docs/chat/setup#instantiate). - -Use the [`presence.enter()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#enter)[`presence.enter()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/enter%28withdata%3A%29)[`presence.enter()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/enter.html) method to indicate when a user joins a room. This will send a presence event to all users subscribed to presence indicating that a new member has joined the chat. You can also set an optional data field with information such as the status of a user: + +Use the [`presence.enter()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#enter)[`presence.enter()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/enter%28withdata%3A%29)[`presence.enter()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/enter.html) method to indicate when a user joins a room. This will send a presence event to all users subscribed to presence indicating that a new member has joined the chat. You can also set an optional data field with information such as the status of a user: @@ -210,7 +210,7 @@ room.presence.enter( ) ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.Room import com.ably.chat.RoomStatus @@ -242,8 +242,8 @@ fun EnterPresenceComponent(room: Room) { ``` - -Use the [`presence.update()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#update)[`presence.update()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/update%28withdata%3A%29)[`presence.update()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/update.html) method when a user wants to update their data, such as an update to their status, or to indicate that they're raising their hand. Updates will send a presence event to all users subscribed to presence: + +Use the [`presence.update()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#update)[`presence.update()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/update%28withdata%3A%29)[`presence.update()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/update.html) method when a user wants to update their data, such as an update to their status, or to indicate that they're raising their hand. Updates will send a presence event to all users subscribed to presence: @@ -292,7 +292,7 @@ room.presence.update( ) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -318,8 +318,8 @@ fun UpdatePresenceComponent(room: Room) { ``` - -Use the [`presence.leave()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#leave)[`presence.leave()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/leave%28withdata%3A%29)[`presence.leave()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/leave.html) method to explicitly remove a user from the presence set. This will send a presence event to all users subscribed to presence. You can also set an optional data field such as setting a status of 'Back later'. + +Use the [`presence.leave()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#leave)[`presence.leave()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/leave%28withdata%3A%29)[`presence.leave()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/leave.html) method to explicitly remove a user from the presence set. This will send a presence event to all users subscribed to presence. You can also set an optional data field such as setting a status of 'Back later'. @@ -368,7 +368,7 @@ room.presence.leave( ) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -464,11 +464,11 @@ The following options can be set when [creating a room](/docs/chat/rooms#create) ## Retrieve the presence set - + The online presence of users can be retrieved in one-off calls. This can be used to check the status of an individual user, or return the entire presence set as an array. The `presence.get()` method may return multiple entries for the same `clientId` if the user has multiple active connections or has reconnected. When displaying presence members in UI, consider deduplicating by unique `clientId` to avoid showing duplicate users. -Use the [`presence.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#get)[`presence.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/get%28%29)[`presence.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/get.html) method to retrieve an array of all users currently entered into the presence set, or individual users: +Use the [`presence.get()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#get)[`presence.get()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/get%28%29)[`presence.get()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/get.html) method to retrieve an array of all users currently entered into the presence set, or individual users: ```javascript @@ -495,7 +495,7 @@ val presentMembers = room.presence.get() val presentMember = room.presence.get(clientId = "clemons123") ``` -```jetpack +```chat_android // Retrieve all users entered into presence as an array: val presentMembers = room.presence.get() @@ -504,7 +504,7 @@ val presentMember = room.presence.get(clientId = "clemons123") ``` -Alternatively, use the [`presence.isUserPresent()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#isUserPresent)[`presence.isUserPresent()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/isuserpresent%28withclientid%3A%29)[`presence.isUserPresent()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/is-user-present.html) method and pass in a user's `clientId` to check whether they are online or not. This will return a boolean: +Alternatively, use the [`presence.isUserPresent()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#isUserPresent)[`presence.isUserPresent()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence/isuserpresent%28withclientid%3A%29)[`presence.isUserPresent()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-presence/is-user-present.html) method and pass in a user's `clientId` to check whether they are online or not. This will return a boolean: ```javascript @@ -519,7 +519,7 @@ let isPresent = try await room.presence.isUserPresent(withClientID: "clemons123" val isPresent = room.presence.isUserPresent("client-id") ``` -```jetpack +```chat_android val isPresent = room.presence.isUserPresent("client-id") ``` diff --git a/src/pages/docs/chat/rooms/reactions.mdx b/src/pages/docs/chat/rooms/reactions.mdx index e81c2be503..e7a300f8c2 100644 --- a/src/pages/docs/chat/rooms/reactions.mdx +++ b/src/pages/docs/chat/rooms/reactions.mdx @@ -13,7 +13,7 @@ Room reactions are ephemeral and not stored or aggregated by Ably. The intention Subscribe to room reactions by registering a listener. Use the [`reactions.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#subscribe)[`reactions.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/subscribe%28%29-64gdf)[`reactions.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room-reactions/subscribe.html) method in a room to receive reactions: - + Use the [`reactions.asFlow()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/as-flow.html) to receive new room reactions: @@ -57,7 +57,7 @@ val subscription = room.reactions.subscribe { event: RoomReactionEvent -> } ``` -```jetpack +```chat_android import androidx.compose.runtime.* import com.ably.chat.Room import com.ably.chat.RoomReactionEvent @@ -94,7 +94,7 @@ The following are the properties of a room reaction event: Use the `unsubscribe()` function returned in the `subscribe()` response to remove a room reaction listener: - + Jetpack Compose automatically handles lifecycle and cleanup when using `LaunchedEffect` with `asFlow`. @@ -132,8 +132,8 @@ unsubscribe() ## Send a room reaction - -Use the [`reactions.send()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#send)[`reactions.send()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/send%28withparams%3A%29)[`reactions.send()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room-reactions/send.html) method to send a room-level reaction. The most common way of using this method is to trigger it whenever a user clicks an emoji button in a room: + +Use the [`reactions.send()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#send)[`reactions.send()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions/send%28withparams%3A%29)[`reactions.send()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room-reactions/send.html) method to send a room-level reaction. The most common way of using this method is to trigger it whenever a user clicks an emoji button in a room: @@ -180,7 +180,7 @@ room.reactions.send(name = "heart", metadata = jsonObject { }) ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room diff --git a/src/pages/docs/chat/rooms/replies.mdx b/src/pages/docs/chat/rooms/replies.mdx index 5f48a57a88..2b11479eb4 100644 --- a/src/pages/docs/chat/rooms/replies.mdx +++ b/src/pages/docs/chat/rooms/replies.mdx @@ -101,7 +101,7 @@ suspend fun sendReply(replyToMessage: Message, replyText: String) { } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Message @@ -191,7 +191,7 @@ fun prepareReply(parentMessage: Message) = jsonObject { } ``` -```jetpack +```chat_android import com.ably.chat.Message import com.ably.chat.json.jsonObject @@ -252,7 +252,7 @@ suspend fun fetchParentMessage(replyData: JsonObject): Message { } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.* @@ -400,7 +400,7 @@ room.messages.subscribe { event -> } ``` -```jetpack +```chat_android import androidx.compose.foundation.layout.* import androidx.compose.material.* import androidx.compose.runtime.* diff --git a/src/pages/docs/chat/rooms/typing.mdx b/src/pages/docs/chat/rooms/typing.mdx index 9df960864a..d4cc348bec 100644 --- a/src/pages/docs/chat/rooms/typing.mdx +++ b/src/pages/docs/chat/rooms/typing.mdx @@ -11,7 +11,7 @@ Typing indicators enable you to display which users are currently writing a mess Subscribe to typing events by registering a listener. Typing events can be emitted when a user starts typing, and when they stop typing. Use the [`typing.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#subscribe)[`typing.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/subscribe%28%29-7uox7)[`typing.subscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/subscribe.html) method in a room to receive these updates: - + Use the [`collectAsCurrentlyTyping()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/jetpack/chat-extensions-compose/com.ably.chat.extensions.compose/collect-as-currently-typing.html) extension function to observe typing changes reactively in Jetpack Compose: @@ -60,7 +60,7 @@ val subscription = room.typing.subscribe { event: TypingSetEvent -> } ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -113,7 +113,7 @@ You can use the size of the `currentlyTyping` set to decide whether to display i Use the `unsubscribe()` function returned in the `subscribe()` response to remove a typing listener: - + Jetpack Compose automatically handles lifecycle and cleanup when using `collectAsCurrentlyTyping()`. @@ -152,8 +152,8 @@ unsubscribe() ## Set typing status - -Use the [`typing.keystroke()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#keystroke)[`typing.keystroke()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/keystroke%28%29)[`typing.keystroke()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/keystroke.html) method to emit a typing event with `type` set to `typing.started`. + +Use the [`typing.keystroke()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#keystroke)[`typing.keystroke()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/keystroke%28%29)[`typing.keystroke()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/keystroke.html) method to emit a typing event with `type` set to `typing.started`. @@ -192,7 +192,7 @@ try await room.typing.keystroke() room.typing.keystroke() ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -217,8 +217,8 @@ fun TypingKeystrokeComponent(room: Room) { ``` - -Use the [`stop()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#stop)[`stop()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/stop%28%29)[`stop()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/stop.html) method to emit a typing event with `type` set to `typing.stopped`. + +Use the [`stop()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#stop)[`stop()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/stop%28%29)[`stop()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/stop.html) method to emit a typing event with `type` set to `typing.stopped`. @@ -256,7 +256,7 @@ try await room.typing.stop() room.typing.stop() ``` -```jetpack +```chat_android import androidx.compose.material.* import androidx.compose.runtime.* import com.ably.chat.Room @@ -315,8 +315,8 @@ All clients in a room must have the same timeout value configured. If not, typin ## Retrieve a list of users that are currently typing - -Use the [`typing.current`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#current)[`typing.current`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/current)[`typing.current`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/current.html) property to retrieve a set of `clientId`s for all users that are currently typing in the room: + +Use the [`typing.current`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#current)[`typing.current`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/current)[`typing.current`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-typing/current.html) property to retrieve a set of `clientId`s for all users that are currently typing in the room: @@ -332,7 +332,7 @@ let currentlyTypingClientIds = room.typing.current val currentlyTypingClientIds = room.typing.current ``` -```jetpack +```chat_android val currentlyTypingClientIds = room.typing.current ``` diff --git a/src/pages/docs/chat/setup.mdx b/src/pages/docs/chat/setup.mdx index 2b71f96e2a..d60d768b5e 100644 --- a/src/pages/docs/chat/setup.mdx +++ b/src/pages/docs/chat/setup.mdx @@ -115,7 +115,7 @@ import AblyChat - + ### Gradle The Ably Chat SDK is available on the Maven Central Repository. To include the dependency in your project, add the following to your `build.gradle.kts` file: @@ -125,7 +125,7 @@ The Ably Chat SDK is available on the Maven Central Repository. To include the d implementation("com.ably.chat:chat:1.1.0") ``` -```jetpack +```chat_android implementation("com.ably.chat:chat:1.1.0") implementation("com.ably.chat:chat-extensions-compose:1.1.0") ``` @@ -138,7 +138,7 @@ For groovy: implementation 'com.ably.chat:chat:1.1.0' ``` -```jetpack +```chat_android implementation 'com.ably.chat:chat:1.1.0' implementation 'com.ably.chat:chat-extensions-compose:1.1.0' ``` @@ -199,7 +199,7 @@ val realtimeClient = AblyRealtime( val chatClient = ChatClient(realtimeClient) ``` -```jetpack +```chat_android import com.ably.chat.ChatClient import io.ably.lib.realtime.AblyRealtime import io.ably.lib.types.ClientOptions @@ -239,7 +239,7 @@ Additional options can also be passed to the Chat client to customize the follow - + | Property | Description | | -------- | ----------- | @@ -297,7 +297,7 @@ val chatClient = ChatClient(realtimeClient) { } ``` -```jetpack +```chat_android val realtimeClient = AblyRealtime( ClientOptions().apply { key = "{{API_KEY}}" @@ -315,7 +315,7 @@ val chatClient = ChatClient(realtimeClient) { The `logHandler` property is your own function that will be called for each line of log output generated by the Chat SDK. - + The `logHandler` property is your custom `LogHandler` implementation that will be called for each line of log output generated by the Chat SDK. diff --git a/src/styles/global.css b/src/styles/global.css index 368539e341..3a407f6c3b 100644 --- a/src/styles/global.css +++ b/src/styles/global.css @@ -4,7 +4,6 @@ @import '@ably/ui/reset/styles.css'; @import '@ably/ui/core/styles.css'; -@import '@ably/ui/core/CookieMessage/component.css'; @import '@ably/ui/core/Slider/component.css'; @import '@ably/ui/core/Code/component.css'; @import '@ably/ui/core/Flash/component.css';