Files
simplex-chat/apps/multiplatform
Evgeny @ SimpleX Chat 4eeddce11d core, ui: chatItemUpdated event has the previous item (#8219)
* core, ui: chatItemUpdated event has the previous item

Apps change counters by the difference between the previous and the new item, and insert an updated item only when the update created it.

* core, ui: a recreated item is sent as newChatItems

An update of a locally deleted message creates it again and sends it as a new item, so chatItemUpdated always has the previous item and the apps never insert on an update.

* core, ui: previous item is optional and has no chat info

Events from older remote hosts decode without it; the apps then insert the item if it is not loaded and change no counters.

* core: catch-up subscriber gets an edited history post as a new item

* ui: updates in another profile do not notify, as on iOS

* core, ui: one type for the updated item and its previous version

AChatItemUpdate has the chat info, the new item and the previous item with the same chat type and direction. Its JSON is the JSON of AChatItem with an optional prevChatItem; the event keeps the key chatItem.

* core: tested event key, previous item reactions, cleared mentions

One function renames the event field to chatItem for JSON and docs, and the test checks the wire key and compatibility with AChatItem. The previous item of a direct edit has its reactions. An edit that removes all mentions sends the item without them.

* core: test that an edit removing mentions sends the item without them

* core: event JSON field mapping inline in the TH options, for the Windows build

* core: file chat item update checked in one store transaction

* core: test that a file reset by unknown relays sends its previous item

* core, ui: chatItemUpdated event key chatItemUpdate

* core, ui: chatItemUpdated always has the previous item

* ci: mcp scope tests the plugin with its published dependencies

* core: mention of the user follows edits of a group message

* core: previous item of a prohibited file is read before the prohibition

* android, desktop: missed call check inline, counter test with core pairs

* ios: spec link of the chatItemUpdated event

* core: mention edits in support chats update members requiring attention

* core: one rule for the mention of the user in received and edited items

* core: record item events of updates for app tests

* android, desktop: remove the missed call notification of updates, never shown

* android, desktop: test item updates on events recorded by the core

* ios: test item updates on events recorded by the core

* docs: plan of app tests of item updates, recording tests in the CI guide

* core: record the response to an update after its item status is final

* ios: notification manager replaceable in tests

* ios: test notifications of updates and the update response

* android, desktop: test the recorded update response

* docs: plan with iOS notifications and the update response

* core: recorded response to an update of a sent message
2026-11-17 20:47:18 +00:00
..
2026-11-04 08:53:18 +00:00
2023-06-29 12:53:11 +01:00

Android App Development

This is a guide to contributing to the develop of the SimpleX android and desktop apps.

Project Overview

This is the Kotlin Multiplatform (KMP) mobile and desktop client for SimpleX Chat, sharing code between Android and Desktop (JVM) platforms using Compose Multiplatform for UI.

Setup

The desktop app builds nanohttpd from a submodule, Android does not use it. Before building the desktop app on a fresh checkout:

git submodule update --init --recursive

Build Commands

# Android debug APK, assembleGoogleDebug builds the flavor with the Play Billing dependency
./gradlew assembleFossDebug

# Android release APK, distributed via F-Droid and GitHub
./gradlew assembleFossRelease

# Android app bundle, distributed via Google Play, includes Play Billing
./gradlew bundleGoogleRelease

# Always name the flavor for releases. The aggregate tasks (build, assemble, assembleRelease,
# bundle, bundleRelease) fail on purpose: they would package a release APK with Play Billing,
# or an app bundle without it.
# The fdroiddata recipe defaults to assembleRelease and must be changed to assembleFossRelease.

# Desktop distribution (current OS)
./gradlew :desktop:packageDistributionForCurrentOS

# Run desktop/JVM tests
./gradlew desktopTest

# Run Android instrumented tests (requires connected device/emulator)
./gradlew connectedFossDebugAndroidTest

# Build native libraries for all platforms
./gradlew common:cmakeBuild -PcrossCompile

# Clean build
./gradlew clean

Architecture

Module Structure

  • common/ - Shared code (Compose UI, models, business logic)
    • src/commonMain/ - Cross-platform code
    • src/androidMain/ - Android-specific implementations
    • src/desktopMain/ - Desktop-specific implementations
  • android/ - Android app container
  • desktop/ - Desktop JVM app container

Key Components (common/src/commonMain/kotlin/chat/simplex/common/)

  • model/ChatModel.kt - Main state container with reactive properties (MutableState, MutableStateFlow)
  • model/SimpleXAPI.kt - API bindings to Haskell core library via FFI
  • platform/Core.kt - FFI interface to native libapp library
  • platform/ - Platform abstraction layer (expect/actual pattern for Android/Desktop specifics)
  • views/ - Compose UI screens organized by feature (chat, chatlist, call, usersettings, etc.)
  • ui/theme/ - Design system (colors, typography, shapes)

Native Integration

The app calls into a Haskell core library via JNI/FFI:

  • CMake builds in common/src/commonMain/cpp/android/ and cpp/desktop/
  • Cross-compilation toolchains in cpp/toolchains/
  • Built libraries go to cpp/desktop/libs/ (organized by platform)

Configuration

local.properties (create from local.properties.example)

compression.level=0          # APK compression (0-9)
enable_debuggable=true       # Debug mode
application_id.suffix=.debug # Multiple app instances on same device
app.name=SimpleX Debug       # App name for debug builds

gradle.properties

Contains versions (Kotlin, Compose, AGP) and app version info. Key settings:

  • kotlin.jvm.target=11
  • database.backend=sqlite (or postgres)

Testing

Tests are in:

  • common/src/commonTest/kotlin/ - Cross-platform tests
  • common/src/desktopTest/kotlin/ - Desktop-specific tests (run with ./gradlew desktopTest)
  • android/src/androidTest/ - Android instrumented tests

Resources & Localization

  • String resources: common/src/commonMain/moko-resources/base/strings.xml + 21 language variants
  • Uses Moko Resources (dev.icerock.moko:resources) for cross-platform resource management
  • The adjustFormatting gradle task validates string resources during build

Platform-Specific Notes

Android

  • Min SDK 26, Target SDK 35
  • NDK 23.1.7779620
  • Supports ABI splits: arm64-v8a, armeabi-v7a
  • Deep linking requires SHA certificate fingerprint in assetlinks.json (see README.md)

Desktop

  • Distributions: DMG (macOS), MSI/EXE (Windows), DEB (Linux)
  • Mac signing/notarization configured via local.properties
  • Video playback uses VLCJ

Gotchas

In order for the SimpleX app to be automatically adopted for opening links from https://simplex.chat the SHA certificate fingerprint for the App installed on the phone must be in the hosted assetlinks.json file on simplex.chat.

The accepted fingerprints are in the sha256_cert_fingerprints list.

To find your SHA certificate fingerprint perform the following steps.

  1. Build and install your development version of the app as usual
  2. From the terminal in Android studio run adb shell pm get-app-links chat.simplex.app
  3. Copy the signature listed in signatures in the result
  4. Add your signature to assetlinks.json in the website repo and make a PR. On approval, wait a few minutes for the changes to propagate to the public website and then you should be able to verify SimpleX.

More information is available here. If there is no response when running the pm get-app-links command, the intents in AndroidManifest.xml are likely misspecified. A verification attempt can be triggered using adb shell pm verify-app-links --re-verify chat.simplex.app.

Note that this is not an issue for the app store build of the app as this is signed with our app store credentials and thus there is a stable signature over users. Developers do not have general access to these credentials for development and testing.

Adding icons

  1. Find a Material symbol in Rounded category.

  2. Set weight to 400, grade to -25 and size to 48px.

  3. Click on the icon, choose Android and download XML file.

  4. Update the color to black (#FF000000) and the size to "24.dp", as in other icons.

For example, this is add reaction icon.