Discover Ditto by building and exploring through a task app:

This guide is based on Android Studio 4.1 and Kotlin 1.4

The first step is to create a project. Go to File → New → New Project and select Basic Activity:

Next, fill out the options with the product name: "Tasks", choose Kotlin, and set the minimum API level to 26:

In the newer version of Android Studio the Basic Activity template includes additional files that are not needed for this tutorial. To continue, remove the following if they exist:

To install Ditto, we need to add it as a dependency in the build.gradle script for the app, as well as ensuring that we have the relevant Java -compatibility set.

Android requires requesting permission to use Bluetooth Low Energy and Wifi Aware. For instructions, see Jetpack Compose: Defining UI.

For the UI in this example, we are still using Kotlin synthetics, which are no longer bundled automatically. We need to add kotlin-android-extensions in the the plugins section of build.gradle to enable.

Be sure to Sync Project with Gradle Files after you add Ditto as a dependency. Click the elephant icon with the blue arrow in the top right to manually trigger if it doesn't prompt.

At this point, you have the basic project in place! Now we need to start to build the UI elements.

Set up the interface for your task app:

Navigate to the content_main.xml layout file and replace the XML in the text representation view. This will remove the existing text view and a recycler view that we will use to display the list of tasks:

Now navigate to activity_main.xml layout file and replace the XML in the text representation view. This will adjust the floating action button to use a white add icon:

The layout should look like this:

Now navigate to activity_main.xml layout file and replace the XML in the text representation view. This will adjust the floating action button to use a white add icon:

Now navigate to activity_main.xml layout file and replace the XML in the text representation view. This will adjust the floating action button to use a white add icon:

The layout should look like this now:

We now need to create a new layout resource file to define our alert dialog. Right-click on the layouts folder in the project and Go to File → New → XML → Layout XML.

Name the resource file dialog_new_task.

Open the new dialog_new_task.xml layout file and replace the XML in the text representation view. This will add an editable text input to allow the user to enter the task:

The layout should look like this now:

We need to create a few string constants. Open strings.xml in the /res/values folder and replace it with this XML:

To use the AlertDialog we will create a DialogFragment. Create a new Kotlin class by right-clicking the app folder within Java in the project view:

Name the new file NewTaskDialogFragment:

Replace the contents of NewTaskDialogFragment.kt with this:

We need to import Ditto and create a few variables. Open the MainActivity file and replace the existing code with this:

If it does not run automatically, execute Sync Project with Gradle Files. 

We will add a function and override two now that MainActivity is an abstract class. Insert this code after onCreate() function in the class:

Right-click on the layouts folder in the project and Go to File → New → XML → Layout XML. Name the file task_view:

Open the task_view.xml layout file and replace the XML in the text representation view. This will add a text view and checkbox to display the task in each row of the RecyclerView:

The layout should look like this now:

We now need to continue to configure the MainActivity to customize the RecyclerView, display the tasks, and add the logic for the user actions. Replace the onCreate() function with this code that will configure the recycler view:

We need to declare a RecyclerView.Adapter to provide a data source to the RecyclerView. Add this code to the bottom of MainActivity, as a new class within the file:

To match the iOS getting started app, we also want to add swipe to delete functionality. Insert this code at the bottom of MainActivity as a new class:

Almost there! At this point, we have most of the app created, but we now need to integrate Ditto!

In order to integrate Ditto into our app we first need to create a new app on the portal. Apps created on the portal will automatically sync data between them and also to the Ditto Big Peer. For instructions, see Onboarding.

To finish the app, we now need to integrate Ditto. We will initialize it in the onCreate() function within MainActivity. Furthermore, we will add handlers for the swipe to delete and listening for row clicks to mark a task as completed (or in-completed). Replace the existing onCreate() code with this:

The important things to note is that you need an access license to use Ditto. If you do not have one yet, reach out and we can supply one. To enable background synchronization, we need to call startSync() which allows you to control when synchronization occurs. For this application we want it to run the entire time the app is in use.

Finally, we then use Ditto's key API to observe changes to the database by creating a live-query in the setupTaskList() function. This allows us to set the initial state of the RecyclerView after the query is immediately run and then subsequently get callbacks for any new data changes that occur locally or that were synced from other devices:

Note, that we are using the observeLocal API in Ditto. This sets up a local observer for data changes in the database that match the query. You also need to create a subscription for the same query that will be used to request this data from other devices.

This is a best-practice when using Ditto, since it allows your UI to simply react to data changes which can come at any time given the ad-hoc nature of how Ditto synchronizes with nearby devices.

Android requires you to request location permissions to fully enable Bluetooth Low Energy (since Bluetooth can be involved with location tracking). Insert this function in MainActivity:

Just in case your project did not auto import as you went along, you can replace the import statements in MainActivity with these:

🎉 You now have a fully functioning Tasks app. Build and run it on a device. The simulator will not show any data sync because neither Bluetooth or the necessary network system is available to allow simulators to find each other or another device.