​

Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto.

• Android version 6.0 (Marshmallow)

• minSdk version 23

• compileSdk version 34

• Java Development Kit (JDK) version 11

​

Setting Up Your Environment

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

allprojects {
    repositories {
        mavenCentral()
    }
}

​

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 "live.ditto:ditto:4.8.1"

​

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:

​

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:

<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" />

​

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:

import live.ditto.transports.DittoSyncPermissions;

void requestPermissions() {
   DittoSyncPermissions permissions = new DittoSyncPermissions(this);
   String[] missing = permissions.missingPermissions(permissions.requiredPermissions());
   if (missing.length > 0) {
      this.requestPermissions(missing, 0);
   }
}

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
   super.onRequestPermissionsResult(requestCode, permissions, grantResults);
   this.ditto.refreshPermissions();
}

For more information about requesting permissions in a user-friendly way, refer to the official Requesting Runtime Permissions documentation

​

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. 

DittoLogger.setMinimumLogLevel(DittoLogLevel.DEBUG);
DittoDependencies androidDependencies = new DefaultAndroidDittoDependencies(this.context);
DittoIdentity identity = new DittoIdentity.OnlinePlayground(
    androidDependencies,
    "YOUR_APP_ID",
    "YOUR_PLAYGROUND_TOKEN"
);
Ditto ditto = new Ditto(androidDependencies, identity);

try {
    ditto.startSync();
} catch(DittoError e) {
    //handle error
}