​
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
    • MacOS arm64 (Apple Silicon)

​
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 'live.ditto:ditto-java:4.11.0-preview.1'
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 'live.ditto:ditto-java:4.11.0-preview.1'

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

implementation('live.ditto:ditto-binaries:4.11.0-preview.1') {
    capabilities {
        requireCapability('live.ditto:ditto-binaries-linux-x64')
    }
}

implementation('live.ditto:ditto-binaries:4.11.0-preview.1') {
    capabilities {
        requireCapability('live.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.

try {
    File dittoDir = new File("path/to/ditto/dir");
    DittoDependencies dependencies = new DefaultDittoDependencies(dittoDir);

    DittoIdentity identity = new DittoIdentity.OnlinePlayground(
        "REPLACE_ME_WITH_YOUR_APP_ID",
        "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
        false, // This is required to be set to false to use the correct URLs
        "REPLACE_ME_WITH_YOUR_AUTH_URL"
    );

    Ditto ditto = new Ditto.Builder(dependencies)
        .setIdentity(identity)
        .build();

    DittoTransportConfig config = new DittoTransportConfig.Builder()
        .connect(connect -> {
            connect.addWebsocketUrls("wss://REPLACE_ME_WITH_YOUR_WEBSOCKET_URL");
        })
        .build();

    
    // Disable DQL strict mode so that collection definitions are not required in DQL queries
    ditto.getStore().execute("ALTER SYSTEM SET DQL_STRICT_MODE = false");
    
    ditto.setTransportConfig(config);
    ditto.startSync();
} catch (DittoError e) {
    // Handle error in Ditto initialization
}
3

Replace the variables with your access credentials available in the portal.

For instructions on how to obtain your access credentials, see Getting SDK Connection Details.