Customizing Transports Configurations

This article provides instructions on explicitly configuring your Ditto instance to listen for connections on a specific port and to connect to remote instances using a host (IP) and port.

Although Ditto automatically attempts to connect to other instances on the Local Area Network (LAN), Bluetooth Low Energy (LE), and Apple Wireless Direct Link (AWDL), supplying a DittoTransportConfig does not enable this feature by default.

Rather, you manually enable peer-to-peer connections using EnableAllPeerToPeer(). (See Enabling and Disabling Transports)

Enabling and Disabling Transports

You can enable and disable transport protocols for all connected Small Peers by doing either of the following.

To enable all transport protocols at once, configure EnableAllPeertoPeer( ).
To enable transport protocols separately, configure a transport protocol one at a time, as shown in the following example.

final config = TransportConfig()
  ..setAllPeerToPeerEnabled(true)
  ..peerToPeer.bluetoothLE.isEnabled = true
  ..peerToPeer.lan.isEnabled = true
  ..peerToPeer.awdl.isEnabled = true;
  
await ditto.setTransportConfig(config);
await ditto.startSync();

Configuring Additional Settings

If you need additional connection configurations for the current Ditto instance, configure it to listen for connections on a specific port and to connect to remote instances using a host (IP) and port:

Before calling startSync(), create a DittoTransportConfig object with the desired settings.

Using the ditto.SetTransportConfig API method, set the created object on your Ditto instance.

Call the startSync method on your Ditto instance to initiate sync with the configured settings.

Syncing with Big Peer

The Big Peer generates certificates automatically for each Small Peer. A certificate involves an expiration date and AppID, among other credentials. Read more here about how it works.

In order to sync with other devices, a peer must connect to the Big Peer at least once. To do this, you must use either OnlinePlayground or OnlineWithAuthentication digital identities.

We recommend using OnlinePlayground for development and OnlineWithAuthentication for production apps. If you only want to use the Big Peer for authentication without syncing to the cloud, you can use enableDittoCloudSync=false.

By default, enableDittoCloudSync is set to true.

final identity = await OnlinePlaygroundIdentity.create(
  appID: 'REPLACE_ME_WITH_YOUR_APP_ID',
  token: 'REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN',
  // Set to false to disable syncing with the cloud
  enableDittoCloudSync: true,
);

final ditto = await Ditto.open(
  identity: identity,
  persistenceDirectory: persistenceDirectory,
);
await ditto.startSync();

Connecting to Remote Small Peers

If you know the host and port of another remote Ditto peer and would like to connect to it, construct a DittoTransportConfig object and, using string format: host:port separated by a colon, add the host and port to the DittoTransportConfig.Connect.TcpServers property.

For example, the following indicates there are two other Small Peers known to Ditto and provides details of their network locations, including the IP addresses and port numbers associated with each peer:

Host IP 135.1.5.5 at port 12345
Host IP 185.1.5.5 at port 4567

final config = TransportConfig()
  ..connect.websocketURLs.push('wss://135.1.5.5:12345')
  ..connect.websocketURLs.push('wss://185.1.5.5:12345');

await ditto.setTransportConfig(config);
await ditto.startSync();

Initializing WebSocket Connections

Ensure WebSocket connections are discoverable across peers within your local network:

final config = TransportConfig()
 ..connect.websocketURLs.push('ws://127.0.0.1');
await ditto.setTransportConfig(config);
await ditto.startSync();

Listening for Connections

You can enable the Ditto instance to listen for incoming connections from other remotes Ditto peers on a specific port. You can think of this as setting up your Ditto as a "server" that can listen to connections from other peers.

In this example, we would like our Ditto instance to listen to incoming connections on port 4000 on 0.0.0.0.

To be safe, please do not use localhost when setting the IP interface. Use "0.0.0.0" instead.

final config = TransportConfig()
  ..listen.tcp.isEnabled = true
  ..listen.tcp.interfaceIP = '0.0.0.0'
  ..listen.tcp.port = 4000;
  
await ditto.setTransportConfig(config);
await ditto.startSync();

Incoming connections from other Ditto peers will be able to connect only if the port is accessible. Depending on your deployment be sure to check that external connections can reach the port that you have specified in your configuration. You may need to set up port forwarding if external ports map differently to your host.

Combining Multiple Transports

You can specify several modes of transport configuration within DittoTransportConfig. The following snippet shows you a ditto instance that can:

Connect to local area network devices
Listen for incoming remote connections
Connect to remote devices with a known host and port.

final config = TransportConfig()
  ..setAllPeerToPeerEnabled(true)
  ..listen.tcp.isEnabled = true
  ..listen.tcp.interfaceIP = '0.0.0.0'
  ..listen.tcp.port = 4000;

// 3. Connect explicitly to remote devices
await ditto.setTransportConfig(config);
await ditto.startSync();

Monitoring Conditions

If syncing over Bluetooth LE is a critical part of your application you may want to warn the user if they are missing the permission or if the hardware is disabled. Ditto will help you by reporting conditions via a delegate or callback object.

First, while configuring Ditto, assign a delegate or a callback to receive notifications.

// Setting up inside a ViewController
let ditto = Ditto(identity: DittoIdentity.onlinePlayground(appID: "REPLACE_ME_WITH_YOUR_APP_ID", token: "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN"))
ditto.delegate = self
try! ditto.startSync()

// Now you can observe real time changes to the transport conditions:
extension ViewController: DittoDelegate {
   func transportConditionDidChange(transportID: Int64, condition: TransportCondition) {
       if condition == .BleDisabled {
           print("BLE disabled")
       } else if condition == .NoBleCentralPermission {
           print("Permission missing for BLE")
       } else if condition == .NoBlePeripheralPermission {
           print("Permission missing for BLE")
       }
   }