SDK Installation

  1. Ensure you have CocoaPods 1.1.0 or later
  2. Ensure you have use_frameworks! in your Podfile
  3. Add DittoSwift to your Podfile like so:
pod 'DittoSwift'
# Note: ensure it is `DittoSwift` and NOT `DittoObjc`. `DittoObjc` is for Objective-C projects
  1. Add these keys in your Info.plist

Since iOS 13 and Xcode 11 an app must ask the user's permission to use Bluetooth. Ditto will activate Bluetooth by default, which means the user will receive a permission prompt automatically.

You must include several keys in the Info.plist file your app.

  • Privacy - Local Network Usage Description
  • Privacy - Bluetooth Peripheral Usage Description
  • Privacy - Bluetooth Always Usage Description
  • A Bonjour service _http-alt._tcp.
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Uses Bluetooth to connect and sync with nearby devices</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Uses Bluetooth to connect and sync with nearby devices</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Uses WiFi to connect and sync with nearby devices</string>
<key>NSBonjourServices</key>
<array>
  <string>_http-alt._tcp.</string>
</array>
  1. Set your license token as below. We recommend putting it inside your AppDelegate.swift's didFinishLaunchingWithOptions
let ditto = Ditto()
self.ditto.setLicenseToken("<ditto_license_token>")
  1. Ensure you have CocoaPods 1.1.0 or later
  2. Ensure you have use_frameworks! in your Podfile
  3. Add DittoObjC to your Podfile like so:
pod 'DittoObjC'
# Note: ensure it is `DittoObjC` and NOT `DittoSwift`. `DittoSwift` is for Swift projects
  1. Add these keys in your Info.plist

Since iOS 13 and Xcode 11 an app must ask the user's permission to use Bluetooth. Ditto will activate Bluetooth by default, which means the user will receive a permission prompt automatically.

You must include several keys in the Info.plist file your app.

  • Privacy - Local Network Usage Description
  • Privacy - Bluetooth Peripheral Usage Description
  • Privacy - Bluetooth Always Usage Description
  • A Bonjour service _http-alt._tcp.
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Uses Bluetooth to connect and sync with nearby devices</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Uses Bluetooth to connect and sync with nearby devices</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Uses WiFi to connect and sync with nearby devices</string>
<key>NSBonjourServices</key>
<array>
  <string>_http-alt._tcp.</string>
</array>
  1. Set your license token as below. We recommend putting it inside your AppDelegate.m's didFinishLaunchingWithOptions
DITDitto *ditto = [[DITDitto alloc] init];
[ditto setLicenseToken: @"<ditto_license_token>"];
  1. Ensure your device has Android 7.1 or higher
  2. Ensure that jcenter is in the project level build.gradle file like so:
buildscript {
    repositories {
        jcenter()
    }
}
  1. In the individual module build.gradle file add:
dependencies {
    // ...
    implementation "live.ditto:ditto:latest.release"
}

android {
    // ...

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
  1. Configure your manifest like so:
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
  1. Register your license token as below. We recommend placing this in your Application.onCreate method
val androidDependencies = DefaultAndroidDittoDependencies(applicationContext)
val ditto = Ditto(androidDependencies)
ditto.setLicenseToken("<ditto_license_token>")
  1. Ensure your device has Android 7.1 or higher
  2. Ensure that jcenter is in the project level build.gradle file like so:
buildscript {
    repositories {
        jcenter()
    }
}
  1. In the individual module build.gradle file add:
dependencies {
    // ...
    implementation "live.ditto:ditto:latest.release"
}

android {
    // ...

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
  1. Configure your manifest like so:
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
  1. Register your license token as below. We recommend placing this in your Application.onCreate method
DefaultAndroidDittoDependencies androidDependencies = new DefaultAndroidDittoDependencies(applicationContext);
Ditto ditto = new Ditto(androidDependencies);
ditto.setLicenseToken("<ditto_license_token>");
  1. To start integrating Ditto into your app you need to download a copy of the libditto.a static library and the Ditto.h header. The following command will download and then unpack an archive containing the library and header. The URL in the following command will download a copy of the static library built to work on iOS:

    curl -O https://software.ditto.live/cpp-ios/Ditto/1.0.6/dist/Ditto.tar.gz && tar xvfz Ditto.tar.gz
    

    If you want to download the C++ SDK for usage on Linux x86_64 then use the following command, which uses a different URL:

    curl -O https://software.ditto.live/cpp-linux-x86_64/Ditto/1.0.6/dist/Ditto.tar.gz && tar xvfz Ditto.tar.gz
    
  2. Configure your app to link to the Ditto static library. Usually this will mean adding an -lditto to a compilation step for your app.

  3. Somewhere in your app, register your license token as below:

    Ditto ditto = Ditto();
    ditto.set_license_token("<ditto_license_token>");
    
  1. Add the Ditto NPM package to your project:
npm install --save @dittolive/ditto

GOTCHA: Ditto is powered by a WebAssembly core when running in the browser. Because WebAssembly (.wasm) files bigger than 4 KB can only be loaded from a proper URL, Ditto won't work when imported from an HTML page opened locally. At least the Ditto JS files together with the ditto.wasm file need to be served via a web server. The ditto.wasm file needs to be located in the exact same location as the ditto.es6.js (or ditto.umd.js if you are using the UMD module). Note that bundlers combine everything into one main.js file (or similar). In that case you'll have to make sure the ditto.wasm file is copied to the same location. If you are using Webpack, take a look at our minimal Webpack example: getditto/ditto-js-example-webpack. You can also pass the location or the actual WebAssembly module explicitly to the init() function.


  1. Once you make sure the ditto.wasm file is served properly, you can import it like any other NPM package in your source and start using it:
import { init, Ditto } from '@dittolive/ditto'

(async () => {
  await init()
  const identity = { type: 'development', appName: 'com.example.ditto', siteID: BigInt('123') }
  const ditto = new Ditto(identity, 'playground')
})()

Linux Bluetooth Setup

If you would like to run Ditto on a Linux device and leverage Bluetooth Low Energy please follow the instructions prior to getting started.

There are two major things to do in order to setup/install ditto for Linux, primary for BLE support.

  1. Install/Update BlueZ 5.51> (or above)
  2. Configure BlueZ to support iOS

Install/Update BlueZ

BlueZ needs to be equal or higher than version 5.51 in order to support GATT Write without Response. By-default Raspbian (RPi) ships with BlueZ 5.50. To check and update, use the following steps.

1. Check current BlueZ version

To check, run

bluetoothctl -v

It should output bluetoothctl: x.xx. If the x.xx version is 5.51 or greater, you do not need to update. If it is 5.50 or lower (or command not found), continue following the steps to update.

2. Install BlueZ dependencies

   apt-get update   
   agt-get upgrade
   apt-get install libdbus-1-dev libglib2.0-dev libudev-dev libical-dev libreadline-dev -y

3. Get BlueZ source from http://www.bluez.org/download/

Looking at the User Space BlueZ Package section, download the bluez-5.xx.tar.xz tarball.

4. Build and install BlueZ

Unpackage and cd into the new BlueZ directory. To build and install BlueZ next, run the following commands.

./configure
make
sudo make install

BlueZ should now be updated and installed!

As an example, these commands download and install BlueZ 5.60 but should work with any BlueZ version.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install libdbus-1-dev libglib2.0-dev libudev-dev libical-dev libreadline-dev -y
wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.60.tar.xz
tar -xf bluez-5.60.tar.xz
cd bluez-5.60
./configure
make
sudo make install

iOS Support

BlueZ 5.51 and above try to automatically read the battery status/service of devices when they connect.

With iOS, BlueZ does not have permissions to read the battery service, so a pairing prompt will appear. To disable the battery service in BlueZ, use the following steps.

  1. Open the bluetooth service file /usr/lib/systemd/system/bluetooth.service, or /etc/systemd/system/bluetooth.target.wants/bluetooth.service in a text editor. You may need sudo permission to write to this file.
  2. Find the line beginning with ExecStart= and add -P battery to the end. The line should look like
ExecStart=/usr/lib/bluetooth/bluetoothd -P battery
  1. Save the file.
  2. Run systemctl daemon-reload and systemctl restart bluetooth to apply the changes to the Bluetooth service

After that, BlueZ should be able to connect to iOS devices without prompting and Ditto Apps should be able to connect over BLE between iOS and Linux.

Top