Skip to content

README.md

Latest commit

 

History

History
59 lines (36 loc) · 4.09 KB

README.md

File metadata and controls

59 lines (36 loc) · 4.09 KB
Raw

Ditto Android Java Quickstart App 🚀

Prerequisites

After you have completed the common prerequisites you will need the following:

Permissions (already configured)

Documentation

Building and Running the Android Application

Assuming you have Android Studio and other prerequisites installed, you can build and run the app by following these steps:

  1. Create an application at https://portal.ditto.live/. Make note of the database ID and development token.
  2. Copy the .env.sample file at the top level of the quickstart repo to .env and add your Database ID, Development Token, and Server URL.
  3. Launch Android Studio and open the quickstart/android-java directory.
  4. In Android Studio, select a connected Android device, or create and launch an Android emulator and select it as the destination, then choose the Run > Run 'app' menu item.

The app will build and run on the selected device or emulator. You can add, edit, and delete tasks in the app.

If you run the app on additional devices or emulators, the data will be synced between them.

Compatible with Android Automotive OS (AAOS)

A Guided Tour of the Android App Source Code

The Android app is a simple to-do list app that demonstrates how to use the Ditto Android SDK to sync data with other devices. It is implemented using Java and Android Views using an Activity and a programmatically implemented RecyclerView.

The Ditto integration is split by concern, following the natural lifecycle of each piece:

  • DittoManager.kt — Ditto instance management: configuration, identity/auth, and starting/stopping sync. The ditto instance is a process-global singleton — created exactly once at app startup and never tied to an Activity, so a configuration change like rotation recreates the Activity without recreating Ditto (two instances on the same persistence directory would contend on its lock). It knows nothing about tasks.
  • TasksApplication.java — the Application subclass that creates the Ditto singleton once at process start (via DittoManager.initialize) and starts sync. Registered as the app's android:name in the manifest.
  • TasksRepository.kt — the tasks data concern: it registers the app-lifetime sync subscription (once), performs CRUD by calling the real Ditto API directly through DittoManager.ditto, and exposes observeTasks(...), which creates a store observer and returns its handle to the caller.
  • MainActivity.java — the UI. It owns the store observer for the screen: it starts observing in onCreate and closes the observer in onDestroy, so the observer is scoped to the view while the Ditto instance and the subscription live for the whole app.

The Ditto v5 SDK ships as a Kotlin module (com.ditto:ditto-kotlin-android) and exposes some APIs (such as store.execute) as suspend functions. Because Java cannot call suspend functions directly, DittoManager and TasksRepository are written in Kotlin, which lets them invoke the real Ditto API directly (bridging the suspending calls with runBlocking) instead of introducing a wrapper layer over the SDK. The remaining application logic — TasksApplication, MainActivity, Task, and TaskAdapter — is in Java.

It is assumed that the reader is familiar with Android development and with Java/Activity/RecyclerView, but needs some guidance on how to use Ditto. The following is a summary of the key parts of integration with Ditto.

Adding the Ditto SDK

In app/build.gradle.kts, you will see this line that causes Android Studio to download the Ditto SDK from Maven Central and add it to the project:

    implementation(libs.ditto)