Customizing Transport 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().

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.

// Create a new DittoTransportConfig()
var config = DittoTransportConfig()

//Enable all peer to peer transports
config.enableAllPeerToPeer()

//Or enable/disable each transport separately
//BluetoothLe
config.peerToPeer.bluetoothLE.isEnabled = true
//Local Area Network
config.peerToPeer.lan.isEnabled = true
//Awdl
config.peerToPeer.awdl.isEnabled = true

ditto.transportConfig = config

do {
  try ditto.startSync()
} catch (let err) {
  print(err.localizedDescription)
}

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.

let ditto = Ditto(identity: .onlinePlayground(
    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
))
do {
  try ditto.startSync()
} catch (let err) {
  print(err.localizedDescription)
}

Observing Peers

Ditto always monitors the mesh network and can report the device names of peers it is connected to. You can manually set the device name of those peers and observe those peers in the network.

The device name must be set before startSync() is called.

ditto.deviceName = "Susan B.";
try {
    ditto.startSync();
} catch(DittoError e) {
    // handle error
}
ditto.getPresence().observe(peers -> {
    // render peers
});

If you want to observe changes made by a particular device, include the device name as a field in the document and query for that field in your ditto live query.

"status == 'open' && edited_by == 'deviceC'"

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

auto config = ditto::TransportConfig();
// Connect explicitly to remote devices
config.connect.tcp_servers.insert("135.1.5.5:12345");
config.connect.tcp_servers.insert("185.1.5.5:12345");

// set the transport config
ditto.set_transport_config(config);
// now you can start ditto's sync
ditto.start_sync();

Initializing WebSocket Connections

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

val config = DittoTransportConfig()

config.connect.websocketUrls.add("ws://127.0.0.1")

ditto.transportConfig = config

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.

import { TransportConfig } from '@dittolive/ditto'

const config = new TransportConfig()
config.listen.tcp.isEnabled = true
config.listen.tcp.interfaceIP = '0.0.0.0'
config.listen.tcp.port = 4000
ditto.setTransportConfig(config)
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.

import { TransportConfig } from '@dittolive/ditto'

const config = new TransportConfig()
if (isNode() && OS === 'darwin') {
// 1. Enable All Peer to Peer Connections (not in a browser environment)
config.setAllPeerToPeerEnabled(true)
// 2. Listen for incoming connections on port 4000
config.listen.tcp.isEnabled = true
config.listen.tcp.interfaceIP = '0.0.0.0'
config.listen.tcp.port = 4000

// 3. Connect explicitly to remote devices
ditto.setTransportConfig(config)
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")
       }
   }