Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ditto.live/llms.txt

Use this file to discover all available pages before exploring further.

Public Preview - This version is in public preview and subject to changes. For production use, please use SDK v4.
To install the C# SDK:
1
Confirm that you meet the minimum requirements. (Prerequisites)
2
Install the Ditto SDK. (Installing Dependencies)
3
Set up your app permissions. (Configuring Permissions)
4
Add Ditto to your app. (Initializing Ditto)
5
(Optional) Declare a foreground service (Android only). (Declaring a Foreground Service)

​
Prerequisites

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

​
Installing Dependencies

To use the Ditto SDK in your project, you’ll need to install the appropriate NuGet package.
If using a package manager other than NuGet, the official package manager for .NET, the command syntax to install Ditto may differ from the following snippet. For more information, see the official Nuget documentation > Ditto .NET
Install-Package Ditto -Version 4.7.2

​
Configuring Permissions

To set up your environment for your target platform:
For apps targeting iOS; for example, MAUI, once you’ve added the Ditto package dependency, configure permissions and ensure your app continues syncing while running in the background, including when the end-user device is locked, by enabling background modes.
1
Open the Info.Plist file for your project.
2
Add the following key-value pairs, and then, if desired, modify each string value:
XML
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Uses Bluetooth to connect and sync with nearby devices</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Uses WiFi to connect and sync with nearby devices</string>
<key>NSBonjourServices</key>
<array>
<string>_http-alt._tcp.</string>
</array>
3
Enable Bluetooth Background Modes:
XML
<key>UIBackgroundModes</key>
<array>
<string>bluetooth-central</string>
<string>bluetooth-peripheral</string>
</array>

​
Requesting Permissions at Runtime

In addition to being declared, 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 for all necessary permissions. Ensure StartSync() is invoked after permissions have been requested.
C#
public async Task CheckPermissions()
{
    await DittoSyncPermissions.RequestPermissionsAsync();
    ditto.StartSync();;
}

​
Initializing Ditto

Once you’ve installed the Ditto SDK, set the debug level you want Ditto to log messages for, create a new Ditto identity, and set up Ditto exception handling for data sync operations:
C#
// Your HTTP Cloud URL Endpoint
var endpoint = "REPLACE_ME_WITH_YOUR_URL";
var id = "REPLACE_ME_WITH_YOUR_DATABASE_ID";

var config = new DittoConfig(
    databaseId: id, // This was "appID" in v4
    connect: new DittoConfigConnect.Server(new Uri(endpoint))
);

var ditto = await Ditto.OpenAsync(config);

// Set up authentication expiration handler (required for server connections)
ditto.Auth.ExpirationHandler = async (ditto, secondsRemaining) =>
{
    // Authenticate when token is expiring
    try
    {
        await ditto.Auth.LoginAsync(
            // Your development token, replace with your actual token
            "REPLACE_ME_WITH_YOUR_DEVELOPMENT_TOKEN",
            // Use DittoAuthenticationProvider.Development for playground, or your actual provider
            DittoAuthenticationProvider.Development
        );
        Console.WriteLine("Authentication successful");
    }
    catch (Exception error)
    {
        Console.WriteLine($"Authentication failed: {error}");
    }
};

ditto.StartSync();

​
Declaring a Foreground Service (Android Only)

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.

​
Next Steps

Learn how to build a task list app built on .NET and integrated with Ditto by going to the .NET MAUI or .NET TUI quickstart apps.