Public Preview - This version is in public preview and subject to changes. For production use, please use SDK v4.
Prerequisites
Before you begin, ensure you have the following installed:- Code editor (preferably Visual Studio Code or Android Studio)
- Flutter SDK (>3.19.0)
- An existing Flutter application to integrate Ditto into
- Ditto Portal account with a Ditto App (see Getting SDK Connection Details)
Android
- Android Studio installed on your machine
- A physical Android device or Android emulator
- Upgrade your Kotlin Gradle version to
1.9.20
or later- Navigate to the root folder
- Open
./android/settings.gradle
- Update the
org.jetbrains.kotlin.android
plugin to1.9.20
iOS
- macOS with the latest version of Xcode installed
- A physical iOS device or an iOS simulator
Web
- Web support requires at least Flutter 3.22.0
- Follow the guide for Web Browser Support
Step 1: Add the Ditto Dependency
1
Run the following command in your terminal from the root of your application:
2
For iOS development, add the following permissions to
ios/Runner/Info.plist
:3
For Android development, add the following permissions to Additionally, if you would like Ditto to continue syncing data while the Android app is running in the background add the following permissions and service declaration to Make sure you customize the service metadata—it will be displayed to the user in the foreground service notification. Note that your
android/app/src/main/AndroidManifest.xml
.android/app/src/main/AndroidManifest.xml
. Then edit the service metadata appropriately.small_app_icon
drawable must be monochrome white.The foreground service will be automatically started and stopped on startSync()
and stopSync()
, respectively.Step 2: Obtain Ditto Credentials
1
Log in to your Ditto Portal account.
2
Navigate to your application and obtain the App ID, Playground Token, AuthURL, and WebSocket URL. (See Getting SDK Connection Details for details)
3
Locate the
appID
, playground token
, authURL
, and websocketURL
for your application. These are required to initialize the Ditto SDK.Step 3: Import & Initialize Ditto
1
Import the SDK in your Dart file where you plan to use it.
Dart
2
Request device permissions.
If you are writing code that targets both web and native platforms, you must
not import platform-specific libraries, such as
dart:io
. However, this
prevents using Platform.is...
to detect the current platform. Note that this
is a compile-time error, so it is not possible to work around this with
kIsWeb
.To streamline this, the Ditto Flutter SDK provides Ditto.currentPlatform
,
which is usable on all platforms.3
Initialize the SDK to obtain an instance of
Ditto
. This is the main entry point into all Ditto-related functionality.Flutter
Step 4: Creating and Reading Data
Insert Data
To insert data into the Ditto store, use the following example. This demonstrates inserting a document into a collection nameditems
:
Dart
insertData
function wherever appropriate in your application, such as in a button press handler.
Dart
Obseve Data Store Changes
To observe changes in the data store, register an observer. This example sets up an observer to listen for changes in theitems
collection:
Dart
observeData
function, typically in the initState
method of a stateful widget to start observing when the widget is initialized.
Dart
dispose()
method to prevent resource leaks
Dart
Step 5: Syncing Data
To keep your data in sync across devices and with Ditto Server, you need to register sync subscriptions. Sync subscriptions define the specific data that should be automatically synchronized to the device.Starting Sync
To start sync on the device you need to callstartSync
. This enables this device to sync data with other peers including the Ditto Cloud.
Dart
Registering a Subscription
Register a subscription to a collection to keep the data in sync. Below is an example of how to register a subscription to theitems
collection:
Dart
syncData
function, typically when initializing your Ditto instance.
Syncing Data Offline
Once your application is syncing data using Ditto, you can deploy it to multiple local devices, Android emulators, or iOS simulators. You can then disable the internet to observe the devices syncing offline.Step 6: Web Browser Support
Web Assets
When Ditto is used on the web, it needs to download and initialize assets for its WebAssembly binary. This happens automatically when callingawait Ditto.init()
. By default, assets are bundled with the application and loaded
from the same web server that serves the application. After running flutter build web
, you can find those in the
build/web/assets/packages/ditto_live/lib/assets
directory.
Alternatively, you can host the contents of that directory on a CDN or other web
server and configure Ditto to load assets from there. All contents of the
directory, excluding the ditto.wasm
file itself, must be reachable at the URL
given by the wasmShimUrl
parameter. The ditto.wasm
file can be served from a
separate URL given by the wasmUrl
parameter.
Configuration for loading all assets from a CDN:
Disable Peer to Peer
On the web, Ditto only supports syncing with the Ditto cloud and does not directly connect to other devices. Make sure that your app only enables peer-to-peer transports on mobile platforms.Considerations for Web
- Flutter for Web is designed to work seamlessly with the Ditto cloud. Due to browser restrictions, direct peer-to-peer synchronization with other devices is not supported.
- The web platform utilizes an in-memory Ditto store, meaning data is not retained across page reloads.
- Ditto’s Flutter SDK currently supports the default build mode for the web.
- When developing with Flutter’s development server, it is required to quit and restart the server after making changes to the source code of your app (support for hot restart is in development).
Step 7: Working with Hot Restart
Flutter’s hot reload is fully compatible with Ditto and works as expected for UI changes. However, hot restart can cause issues because Ditto maintains persistent state that conflicts with Flutter’s restart mechanism.Understanding the Issue
When you perform a hot restart in Flutter:- The Dart VM resets and reinitializes your app
- Ditto’s native resources and lockfiles remain in memory/disk
- Attempting to reinitialize Ditto with the same persistence directory causes conflicts
Recommended Workarounds
Option 1: Use Randomized Directory in Debug Mode
The simplest solution is to use a different persistence directory for each debug session. This prevents conflicts by ensuring each restart uses a fresh directory:This approach means data won’t persist between hot restarts during development. This is typically acceptable for development workflows since you’re focusing on UI/logic changes rather than data persistence.
Option 2: Full App Restart for Development
If you need to maintain data persistence during development, perform a full app restart instead of hot restart:- Stop the Flutter app (
q
in terminal or stop button in IDE) - Run
flutter run
again - This ensures all native resources are properly cleaned up
Best Practices
- Use hot reload for UI changes - it’s fully compatible with Ditto
- Use randomized directories in debug mode for the smoothest development experience
- Implement error handling to gracefully recover from initialization failures
- Document your approach in your project README so team members understand the development workflow
Platform-Specific Notes
- Hot reload: Works without issues on all platforms (web, iOS, Android)
- Hot restart: Requires workarounds on all platforms including web, as Ditto instances cannot be re-initialized in the same process
Step 8: Troubleshooting
- Ensure that all dependencies are up-to-date by updating to the latest version.
- Contact the Ditto team through Contact Us