​

Installing the C++ SDK

​

Linux

To install the C++ SDK:

​

Downloading and Unpacking Ditto

Download Ditto.tar.gz and unpack an archive containing the libditto.a static library and Ditto header:

curl -O https://software.ditto.live/cpp-linux-x86_64/Ditto/4.9.3/dist/Ditto.tar.gz && tar xvfz Ditto.tar.gz

​

Linking to Ditto

Add -lditto as a compilation step in the main.cpp source file:

# This command assumes:
# You have unzipped the Ditto.tar.gz in a relative directory ./sdk/
# Your main code entry point is in ./src/main.cpp

g++ -std=c++17 ./src/main.cpp -I ./sdk -lditto -ldl -lrt -pthread -L ./sdk -o dist/main;

 # Once executed, your output will be available at: ./dist/main

​

Android

The Ditto C++ SDK for Android is available in the Maven Central repository: https://central.sonatype.com/artifact/live.ditto/ditto-cpp

Integrating the C++ SDK into an Android app requires use of the Android Native Development Kit (NDK) and the Java Native Interface (JNI) mechanism. To learn more about the NDK and JNI, see https://developer.android.com/ndk/guides.

​

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-cpp:4.9.3"

To ensure that your app links properly with the shared objects in the SDK, and that your app has debugging symbols for the SDK, add these rules to your android packagingOptions block:

        jniLibs {
            useLegacyPackaging = true
            keepDebugSymbols.add("**/*.so")
            pickFirsts.add("lib/**/libditto.so")
            pickFirsts.add("lib/**/libc++_shared.so")
        }

​

Setting Android Context

The C++ SDK for Android requires that the app call Ditto::set_android_context(JNIEnv* env, jobject context) with an application context object after creating an instance of the C++ Ditto class. This context is required by the SDK on Android to access system resources such as network interfaces and files.

​

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.

<!-- Required for Bluetooth -->
<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="31" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" tools:targetApi="31" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" tools:targetApi="31" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />

<!-- Required for WiFi Aware -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_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.NEARBY_WIFI_DEVICES" android:usesPermissionFlags="neverForLocation" tools:targetApi="33" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="32" />

<!-- Required for WiFi Aware, TCP, UDP, and WebSockets -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required for mDNS discovery -->
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

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

At runtime, your app can call the C++ Ditto::missing_permissions() function to get a list of permissions required by Ditto that are missing, and your app can request them.

​

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

​

Importing and Initializing Ditto

From the source code of your app, using #include <Ditto.h>, use the ditto namespace, and provide your access credentials:

const auto identity = ditto::Identity::OnlinePlayground(
    std::move(app_id),
    std::move(online_playground_token),
    enable_cloud_sync,                  // This is required to be set to false to use the correct URLs
    std::move(custom_url)
);

ditto->update_transport_config([&](ditto::TransportConfig &config) {
    config.enable_all_peer_to_peer();
    config.connect.websocket_urls.insert(websocket_url);
});
// Required for compatibility with DQL.
ditto->disable_sync_with_v3();

// Disable DQL strict mode so that collection definitions are not required in DQL queries
ditto->get_store().execute("ALTER SYSTEM SET DQL_STRICT_MODE = false");

ditto->start_sync();