Install Guides

React Native

This article provides instructions on adding the Ditto package to your project by importing, initializing, and preparing Ditto to be integrated successfully with your React Native apps.

React Native CLI Support

The Ditto SDK is designed for apps built with bare React Native CLI.

Expo Go is not supported, and other Expo workflows (such as Development Builds) have yet to be added to the SDK.

Once you've confirmed that you have the necessary prerequisites, integrate Ditto within your React Native app:

1

Set up a React Native CLI project. (Creating Your Project)

2

Install the Ditto package into your project. (Installing the Ditto SDK)

3

Install the project dependencies. (Installing Dependencies)

4

Enable your app to sync with nearby devices. (Setting Up Transport Configurations)

5

Import the previously installed Ditto SDK package in your app. (Initializing Ditto)

6

Set up permissions handling. (Handling Permissions)

7

Set up authentication. (Setting Up Authentication)

8

Specify how Ditto should handle sync. (Creating a New Instance of Ditto)

9

Set up transport configurations. (Setting Transport Configurations)

10

Initiate sync at global scope. (Starting the Sync Process)

11

If desired, enable the Small Peer Information feature. (Enabling smallPeerInfo)

12

If desired, monitor the activity of remote peers in the mesh by logging relevant information in logs or using Ditto’s Presence Viewer app. (Setting Up Presence)

13

If desired, set the log level to debug. (Setting the Logs to Debug Level)

14

Create your subscription logic. (Constructing Subscription Logic)

Creating Your Project

First, set up your environment and initialize your React Native project, seeing it build successfully. For instructions, see React Native's official documentation on Setting up the development environment. Then, proceed by creating a project without a framework.

To verify that you’ve set up your environment correctly, install and run the React Native CLI doctor. For more information, see the official Meet Doctor, a new React Native command React Native blog post.

Installing the Ditto SDK

From a terminal, navigate to the folder containing your React Native project, and then, using your preferred package manager, install the Ditto package:

Yarn
npm


Installing Dependencies

From the root of your project, install project dependencies based on the package.json file:

Yarn
npm


Configuring Permissions

Once you've added dependencies, set up the prerequisites to enable Ditto Transports for iOS and Android.

iOS

From Xcode, enable Bluetooth Low Energy (BLE) and local network services in your app:

1

Install pods and make sure you use a compatible minimum iOS version.

From the ios/Podfile file in your project, set the minimum deployment target for iOS:



Tip: No version changes are needed for RN 0.76+ projects that already havemin_ios_version_supported set to 14.

Be sure to reinstall Pods afterward:


2

From your project's Info.plist file, add the following key-value pairs:

XML


Tip: To view Info.plist as source code, right-click the file from the left sidebar in Xcode > click Open As > and then select Source Code from the menu.

If desired, customize the default values for the permission prompts by replacing them with your preferred text.

For example, if your end users prefer a language other than English, you can replace the default English strings with their language equivalents.

Once implemented, these string values display to your end users as dismissable prompts explaining why the app requires certain permissions.

3

Ensure your app continues to sync while it runs in the background by enabling Bluetooth LE background modes. Once enabled, your app continuously syncs in the background, even while the device is locked.

For official instructions, see Configuring background execution modes from Apple.

  1. From the left sidebar, click to select your project.
  2. Click Signing & Capabilities.
  3. Click + Capability, and then from the modal that appears, search and select Background Modes.
  4. From TARGETS, select your app from the list.
  5. From Background Modes, toggle the following:
    • Uses Bluetooth LE accessories
    • Acts as a Bluetooth LE accessory
Document image


Android

From Android Studio, set up transport configurations for the Android target:

1

Use a compatible Android minimum SDK version:

  1. Open the project-level build.gradle located in the android root directory.
  2. Set the minSDKVersion to 24.

Other projects might require setting the SDK version in android/gradle.properties.

2

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 the app to explicitly request certain permissions 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 the necessary permissions to enable its mesh network capabilities. These permissions will automatically be merged with your app's permissions, so you should be aware of them.

AndroidManifest.xml


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 for respecting users' privacy when those permissions are unnecessary.

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:

  1. Open the AndroidManifest.xml located in your project's app/src/maindirectory.
  2. Within the same <manifest> tag, just before the <application> tag, add the relevant permissions you want to configure (location example):
AndroidManifest.xml


Note the additional tools:remove the attribute. This tells the manifest merger to selectively remove the android:maxSdkVersion behavior from the associated permissions, changing them to apply to all Android versions.

3

If using React Native's Legacy Architecture, you must add the following code snippet to the module-level build.gradle located in the android/app directory:


4

Start the app in Metro:





Initializing Ditto

Within the top-most scope of your app, import the Ditto package with the necessary modules and components from the Ditto's SDK library:



Handling Permissions

Within your default React component (App), use this helper function to request permissions if developing for the Android target:



Configuring Sync

Using an asynchronous function, let's say, startSync(), do the following:

1

Define an identity configuration with authentication settings. (Setting Up Authentication)

2

Instantiate a ditto object with the specified identity. (Creating a New Ditto Instance)

3

Configure peer-to-peer transport settings and enable transports. (Setting Transport Configurations)

4

Initiate sync. (Starting the Sync Process)

Setting Up Authentication

Create an identity object, define your authentication type, and provide access credentials. To sync, each instance of Ditto running in your app must prove its identity to other peers.

There are two types of identities you can use to authenticate:

  • onlinePlayground — Explore platform features and functionality without setting up your authentication mechanism.
  • onlineWithAuthentication — If developing a production-level app, integrate your own identity provider, such as Auth0, identify users, give users read or write control, and integrate with your existing authentication systems.

For more information, see Cloud Authentication .

onlinePlayground

Use an online playground identity for development. You can find authentication details for your app on the Ditto Portal. Use these to set up your identity:



onlineWithAuthentication

Use the onlineWithAuthentication identity when developing a production app for deployment.



Creating a New Instance of Ditto

Within a try statement, instantiate a new Ditto object with the identity you’ve specified:



Setting Transport Configurations

Using a TransportConfig instance, do the following to set up transport configurations in your app:

1

Configure peer-to-peer transport settings so that all desired transport types available on the end-user device are available to Ditto.

2

Specify how you want Ditto to handle which transports to sync data across the mesh.



Constructing Sync Subscription Logic

Create the logic that performs sync and data operations in your app, including registering subscriptions, executing store operations, and observing changes in the given collection. For more information, see Data-Handling Essentials and Managing Sync Subscriptions.

For example, the following snippet defines a document object (document), creates a subscription for the Cars collection, executes database operations and logs the results, registers an observer for watching changes in the Cars collection:



Starting the Sync Process

To start syncing with other peers in the mesh:



Enabling Small Peer Info

Enabling the smallPeerInfo feature allows you to gather and store peer-to-peer sync and network details automatically rather than continuously query Ditto for this data.

Once enabled, collected details are available within the Ditto portal. For more information, see Using the Device Dashboard.

You can configure smallPeerInfo directly on the Ditto instance.



Setting Up Presence

Monitor remote peers in the logs or using Ditto’s Presence Viewer app. For more information, see the blog post “An explanation of the Ditto Presence Viewer.

To set up presence observations:



Setting Logs to Debug Level

Capture database debug logs by setting the Ditto log level to Debug mode. That way, any potential issues are tracked.

To set the minimum log level to Debug:



Known issues

  1. React Native's Fast Refresh will throw an error with the current Ditto architecture, insisting you provide a different persistence directory name. We are working on



Updated 26 Nov 2024
Did this page help you?