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

​
Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto.
  • Java Development Kit (JDK) version 17
  • One of the following platforms and architectures:
    • Windows x86_64
    • Linux x86_64
    • MacOS arm64 (Apple Silicon) or x86_64

​
Additional Resources

​
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 project’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 Build > Sync Project with Gradle Files

​
Adding the Ditto SDK Dependency

To reduce the size of your final application archive, we provide binaries for each supported platform and architecture separately. You can include all supported binaries or only the ones you need.
1

Add the Ditto SDK to your module’s build.gradle file in the dependencies block with the appropriate version. This is the Java API that you will use to interact with Ditto.
implementation 'com.ditto:ditto-java:5.0.0-preview.2'
2

Add binaries to the same dependencies block based on what platforms you are targeting.
// This will include binaries for all supported platforms and architectures
implementation 'com.ditto:ditto-java:5.0.0-preview.2'

// Or you can use one or more of the following declarations to include binaries for specific platforms
implementation('com.ditto:ditto-binaries:5.0.0-preview.2') {
    capabilities {
        requireCapability('com.ditto:ditto-binaries-windows-x64')
    }
}

implementation('com.ditto:ditto-binaries:5.0.0-preview.2') {
    capabilities {
        requireCapability('com.ditto:ditto-binaries-linux-x64')
    }
}

implementation('com.ditto:ditto-binaries:5.0.0-preview.2') {
    capabilities {
        requireCapability('com.ditto:ditto-binaries-macos-arm64')
    }
}

​
Integrating and Initializing

1

Add the following code to import Ditto, at the top of your project file.
Java
import com.ditto.java.*;
2

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 Ditto subclass that can be used throughout the application.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.
Java
// Your HTTP Cloud URL Endpoint
String endpoint = "REPLACE_ME_WITH_YOUR_URL";
String id = "REPLACE_ME_WITH_YOUR_DATABASE_ID";

DittoAndroidConfig config = new DittoAndroidConfig(
    context,
    id, // This was "appID" in v4
    new DittoConfigConnect.Server(new URL(endpoint))
);

Ditto ditto = Ditto.open(config);

// Set up authentication expiration handler (required for server connections)
ditto.getAuth().setExpirationHandler((dit, secondsRemaining) -> {
    // Authenticate when token is expiring
    dit.getAuth().login(
        // Your development token, replace with your actual token
        "REPLACE_ME_WITH_YOUR_DEVELOPMENT_TOKEN",
        // Use DittoAuthenticationProvider.development() for playground
        DittoAuthenticationProvider.development(),
        (clientInfo, error) -> {
            if (error != null) {
                System.out.println("Authentication failed: " + error);
            } else {
                System.out.println("Authentication successful");
            }
        }
    );
});

ditto.startSync();
3

Replace the database ID and development token with your access credentials available in the portal.
For instructions on how to obtain your access credentials, see Getting SDK Connection Details.