Kotlin
You can integrate the Ditto SDK into Kotlin projects to develop native apps for the Android platform.
For a complete overview of the platforms, transports, and devices the Kotlin SDK supports, see the compatibility map for Kotlin.
To install the Kotlin SDK and start syncing offline:
Confirm that you meet the minimum requirements. (Prerequisites)
Prepare your environment for Ditto. (Setting Up Your Environment)
Configure your app permissions. (Setting Up Permissions)
Authenticate with the Big Peer and then start syncing offline. (Integrating and Initializing)
Following are the minimum requirements that must be met before attempting to install Ditto.
- Android version 6.0 (Marshmallow)
- minSdk version 23.0
- compileSdk version 34.0
- Java Development Kit (JDK) version 11.0
Confirm that mavenCentral() is in the project-level build.gradle:
In the individual module build.gradle file:
The following bash script uses the placeholder 4.x.x within the dependencies block. Make sure to replace the placeholder with the latest Ditto SDK version number; for example, 4.7.1.
For the latest Ditto SDK version number, see the Directory of Release Notes and select the release notes for your language.
The Android operating system limits access to some device functionality for end-user control and privacy.
To fully unlock Ditto's capabilities, configure your app to automatically request all necessary permissions from end users at runtime:
Include the necessary permissions required by Android. (Including Required Permissions)
Proactively check for permission availability to avoid unnecessary delay between granting location access and Ditto recognizing the permission. (Ensuring Permissions Setup)
Android requires certain permissions to be explicitly requested by the app in order to access features like Bluetooth Low Energy (LE) and Wi-Fi Aware. These permissions must be included in the app's manifest file and requested from the end user at runtime.
For more information about required permissions, see the official Permissions on Android documentation.
To include the necessary permissions required by Android:
Within the <manifest> tag, confirm that following namespace declarations and, if needed, add them to the beginning of the file:
Within the same <manifest> tag, just before the <application> tag, add the following permissions:
If you want to exclude specific permissions from the maxSDKVersion behavior, use the tools:remove attribute as desired.
The android:maxSdkVersion attribute results in the permission being requested only on devices running the specified SDK level or lower. While this attribute prevents the requesting of additional permissions beyond what Ditto requires, it prevents your app from requresting permission on devices running a newer OS version.
For example, the following configuration allows the permission to be requested on any SDK version:
Save the AndroidManifest.xml file.
Ensure that your app’s build.gradle file includes the Ditto SDK dependency with the correct version. For example:
Make sure to replace the placeholder with the latest Ditto SDK version number; for example, 4.7.1.
For the latest Ditto SDK version number, see the Directory of Release Notes and select the release notes for your language.
To ensure your app has the required permissions for sync, use the DittoSyncPermissions helper from the Ditto SDK.
This helper simplifies the process of requesting end-user permissions at runtime with a single method call (ensurePermissions) for all permissions, as well as handles any potential errors encountered during the permissions request process.
To use the helper:
Call the following in your Activity or Fragment's onCreate method:
On Android, after granting location access, Ditto may not immediately recognize the permission, 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:
Using the Application-level Context, integrate Ditto into your app's onCreate method.
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.
Replace YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available from the portal. (See Sync Credentials)