Public Preview - This version is in public preview and subject to changes. For production use, please use SDK v4.

​
Kotlin Install Guide

​
Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto for each of the KMP target platforms are currently supported.
  • Kotlin 2.1.0
  • Java Development Kit (JDK) version 17.0
  • Android target
    • Android version 7.0 (Nougat) or AAOS 13.0
    • minSdk version 24.0
    • compileSdk version 34.0
  • iOS target
    • iOS 14
  • JVM target
    • Windows 10 on x86_64
    • Linux x86_64
    • macOS 11 on arm64 (Apple Silicon) or x86_64
For more infomration about other supported platforms, see the Kotlin Compatibility page.

​
Setting Up Your Environment

Include the Maven Central repository in your Gradle file, and then synchronize it with your project.
1

From your project-level build.gradle file located in the app’s root directory, ensure the mavenCentral() repository is included in the repositories section:
allprojects {
    repositories {
        mavenCentral()
    }
}
2

Synchronize your project with the Gradle file by clicking File > Sync Project with Gradle Files.

​
Adding the Ditto SDK Dependency

Add the Ditto SDK to your app’s build.gradle file in the dependencies block with the appropriate version: 
implementation "com.ditto:ditto-kotlin:5.0.0-preview.2"

​
Configuring Permissions

The Android operating system limits access to some device functionality for end-user control and privacy. In order to use this functionality, configure your app to declare and request permissions from end users at runtime:
1

Review permissions used by Ditto. (Declaring Permissions)
2

Proactively check permission status to avoid unnecessary delay between granting access and Ditto being able to use the feature. (Requesting Permissions)

​
Declaring Permissions in the Android Manifest

Android requires certain permissions to be explicitly requested by the app to access features like Bluetooth Low Energy and Wi-Fi Aware. These permissions must be declared in the app’s manifest file and requested from the end user at runtime. The Ditto SDK’s AndroidManifest.xml includes all of the necessary permissions for enabling its mesh network capabilities. These permissions will automatically be merged with your app’s permissions, so you should be aware of them. 
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" tools:targetApi="s" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" tools:targetApi="s" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" android:usesPermissionFlags="neverForLocation" tools:targetApi="tiramisu" />
Some of these permissions have an android:maxSdkVersion attribute which means they are not used on devices running newer versions of Android. This is a best practice to respect users’ privacy when those permissions are not necessary. However, some apps may still need to use one or more of the above permissions across more versions of Android. This can be accomplished by overriding the permission configuration in your app’s AndroidManifest.xml To override any of these permission limitations in your app, do the following:
1

Open the AndroidManifest.xml located in the app/src/main directory of your project.
2

Within the same <manifest> tag, just before the <application> tag, add the relevant permissions you want to configure (location example):
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:remove="android:maxSdkVersion" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:remove="android:maxSdkVersion" />
Note the additional tools:remove attribute. This tells the manifest merger to selectively remove the android:maxSdkVersion behavior from the associated permissions, changing them to apply to all Android versions.
For more information, see the official Permissions on Android and Merge manifest files documentation.

​
Requesting Permissions at Runtime

In addition to being declared in the manifest, some permissions need to be requested from the user at runtime. To ensure your app has the required permissions for sync, use the DittoSyncPermissions helper class from the Ditto SDK. This helper class:
  • Simplifies the process of requesting end-user permissions at runtime with a single method call (ensurePermissions) for all necessary permissions.
  • Handles any errors encountered during the permissions request process.

​
Using the Helper

To use the DittoSyncPermissions helper class:
1

Import the DittoSyncPermissions helper class in the main activity of your app:
import com.ditto.kotlin.transports.DittoSyncPermissions
2

Call the following in your Activity or Fragment’s onCreate method:
fun requestPermissions() {
    val missing = DittoSyncPermissions(this).missingPermissions()
    if (missing.isNotEmpty()) {
        this.requestPermissions(missing, 0)
    }
}
3

Refresh permissions after permissions are granted.On Android, after granting permissions, Ditto may not immediately recognize the change, causing a delay in syncing. To address this, whenever a relevant permission changes, call refreshPermissions() to quickly check and start syncing with the new permissions. This can be done in the onRequestPermissionsResult() activity lifecycle method:
private val requestPermissionLauncher = registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { this.ditto.refreshPermissions() }
override fun onCreate(savedInstanceState: Bundle?) { }

​
Integrating and Initializing

Using the Application-level Context, integrate Ditto into your app’s onCreate method. Most apps require that Ditto run as a singleton. A singleton is an implementation ensuring your Ditto instance accesses and shares a single object instance throughout your app. To store the Ditto instance as a singleton object, create a custom Application subclass for your Android app. Include the necessary setup configuration below in the onCreate method.
By doing so, you ensure that there is only one instance of Ditto throughout the app’s lifecycle, and it remains available for use by any activity or component that needs it. This approach helps in efficient resource management and avoids unnecessary object instantiation and destruction.
1

Add Ditto to your application by placing it in your Application.onCreate method.
To ensure your app maintains a single Ditto instance throughout its lifetime and prevents it from going out of scope or getting garbage collected, place Ditto in the Application-level Context instead of the Context from any activity where you initially instantiated the Ditto instance.
Kotlin
try {
    val androidDependencies = DefaultAndroidDittoDependencies(applicationContext)
    val identity =
        DittoIdentity.OnlinePlayground(
            dependencies = androidDependencies,
            appId = "REPLACE_ME_WITH_YOUR_APP_ID",
            token = "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
            customAuthUrl = "REPLACE_ME_WITH_YOUR_AUTH_URL",
            enableDittoCloudSync = false  // This is required to be set to false to use the correct URLs
        )

    ditto = Ditto(androidDependencies, identity)

    ditto?.updateTransportConfig { config ->
        config.connect.websocketUrls.add("REPLACE_ME_WITH_YOUR_WEBSOCKET_URL")
    }

    // Disable DQL strict mode so that collection definitions are not required in DQL queries
    ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")
    
    ditto.startSync()
} catch (e: DittoError) {
    Log.e("Ditto error", e.message!!)
}
2

Replace YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available from the portal. (See Getting SDK Connection Details )

​
Proguard

When building a release version of an Android app with minification enabled, the app may crash at runtime due to ProGuard or R8 shrinking or obfuscating necessary code. To ensure the app runs smoothly in release builds, it’s important to explicitly retain critical classes and methods. This can be achieved by adjusting your ProGuard rules to prevent essential code from being removed or altered during the minification process. To help identify issues caused by missing or obfuscated classes, here’s a typical crash log that you might encounter when the necessary ProGuard rules are not applied: 
java.lang.NoSuchMethodError: no static method "..."
To ensure optimal app performance when using the Ditto SDK, update your ProGuard rules to retain critical classes. Depending on the features you’re using, you’ll need to add specific rules to prevent ProGuard from stripping essential code: Ditto Native Bindings - Required for All Ditto SDK Use: This rule ensures that all native bindings related to Ditto are preserved and available at runtime. Ditto Blanket Exclusion - Required for Presence This rule retains all Ditto classes, which is essential for features like Presence Viewer, and ensures Jackson classes are preserved for proper JSON deserialization. 
-keep class com.ditto.kotlin.** { *; }
  • keep class com.ditto.kotlin.internal.swig.ffi.** ensures that all classes and interfaces under the com.ditto.internal.swig.ffi package (including sub-packages) are retained.
  • { *; } specifies that all members (fields, methods, constructors, etc.) of these classes should be preserved as well.
  • This rule prevents ProGuard from shrinking, obfuscating, or modifying these classes, ensuring that your app functions correctly in a minified release build.

​
Declaring a Foreground Service (Optional)

A foreground service allows your app to continue syncing data with Ditto while running in the background. A foreground service is not required to use Ditto, but without it your app will stop syncing whenever it is in the background. To declare the foreground service, add the following to your AndroidManifest.xml: 
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" tools:targetApi="upside_down_cake" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:targetApi="tiramisu" />

<application ...>
    <service
        android:name="com.ditto.kotlin.transports.foregroundservice.DefaultDittoForegroundService"
        android:exported="false"
        android:foregroundServiceType="connectedDevice"
        android:stopWithTask="true">
        <meta-data android:name="notificationChannelName" android:value="Background Data Sync" />
        <meta-data android:name="notificationChannelId" android:value="BackgroundDataSyncId" />
        <meta-data android:name="smallIcon" android:resource="@drawable/small_app_icon" />
        <meta-data android:name="notificationTitle" android:value="Syncing Data" />
        <meta-data android:name="notificationText" android:value="Syncing data across connected devices" />
        <meta-data android:name="notificationId" android:value="1001" />
    </service>
</application>
Make sure you customize the service metadata—it will be displayed to the user in the foreground service notification. Note that your small_app_icon drawable must be monochrome white. The foreground service will be automatically started and stopped on startSync() and stopSync(), respectively. For more information about the Ditto foreground service consult the API Reference.

​
Using crash reporters in Android apps

1

Setup

Integrate the crash reporter SDK into your app, following their documentation.
2

Check crash collection

Trigger a panic and check that it was registered in your crash reporter. You can use the DittoExperimental.triggerTestPanic() function to do so. At this point, without native symbols, the crash will be unreadable. If you are not seeing any crashes in the reporter, check that you have integrated its components correctly.
3

Upload symbols

Upload the native library .so file provided by the Ditto SDK for the platform you are targeting. This file contains a symbol map allowing crashes to be symbolicated.The native library .so can be found at the following path:
$buildDir/intermediates/merged_native_libs/$variant/out/lib/$arch/libdittoffi.so
Check your crash reporter’s documentation for how to do this. For example, Crashlytics has a Gradle plugin which uploads symbols automatically while Sentry and BugSnag provide a CLI tools.
4

Final test

Trigger a new panic and notice that the crash is now symbolicated by the reporting framework.