Using the DataTrack API

In this guide, we will show you how to use the DataTrack API to send messages between Participants connected to a Room. With the DataTrack API you will be able to build powerful collaboration features such as whiteboarding, screen annotations, shared augmented reality apps and more. Read below to learn more.

Overview

The DataTrack API lets you create a DataTrack channel which can be used to send low latency messages to zero or more receivers subscribed to the data. DataTracks have the following properties.

  • DataTracks are unidirectional.
  • DataTracks have built-in mechanisms to support reliable transmission. Check out the section on Configuring DataTrack reliablity.
  • Recommended maximum payload size of data sent over the DataTrack is 16KiB.
  • string or byte data can be sent over the DataTrack.
  • The DataTrack API supports both Peer-to-peer Rooms and Group Rooms.

In the next section we will show you how to use the DataTrack API with the iOS SDK.

Using the DataTrack API

Create a LocalDataTrack

The TVILocalDataTrack is a Track that represents data that can be published to a Room by the TVILocalParticipant.

var localDataTrack = TVILocalDataTrack()

Connect to a Room with a LocalDataTrack

Next, we want to connect to a Room with the TVILocalDataTrack we created earlier.

let connectOptions = TVIConnectOptions.init(token: accessToken){ (builder) in
    builder.roomName = "my-room"
    if let localDataTrack = self.localDataTrack {
        builder.dataTracks = [localDataTrack]
    }
}
var room = TwilioVideo.connect(with: connectOptions, delegate: self)

Publish the LocalDataTrack

After connecting to the Room, we now want to publish our TVILocalDataTrack to it.

if let localParticipant = room?.localParticipant,
   let localDataTrack = self.localDataTrack {
    localParticipant.publishDataTrack(localDataTrack)
}

Send messages over the LocalDataTrack

The DataTrack API supports sending string as well as byte data.

let message = "Hello DataTrack!"
localDataTrack.send(message)

var messageBuffer = Data(bytes: bytes, length: length)
localDataTrack.send(messageBuffer)

Listening for RemoteDataTrack events

The TVIRemoteParticipant class provides a delegate protocol named TVIRemoteParticipantDelegate. You can implement this protocol to learn about published and unpublished DataTrack events.

// MARK: TVIRemoteParticipantDelegate
extension MyClass : TVIRemoteParticipantDelegate {

    // Participant has published a data track.
    func remoteParticipant(_ participant: TVIRemoteParticipant,
                           publishedDataTrack publication: TVIRemoteDataTrackPublication) {
    }

    // Participant has unpublished a data track.
    func remoteParticipant(_ participant: TVIRemoteParticipant,
                           unpublishedDataTrack publication: TVIRemoteDataTrackPublication) {
    }

    // Data track has been subscribed to and messages can be observed.
    func subscribed(to dataTrack: TVIRemoteDataTrack,
                    publication: TVIRemoteDataTrackPublication,
                    for participant: TVIRemoteParticipant) {
        // Respond to incoming messages.
        dataTrack.delegate = self
    }

    // Data track has been unsubsubscribed from and messages cannot be observed.
    func unsubscribed(from dataTrack: TVIRemoteDataTrack,
                      publication: TVIRemoteDataTrackPublication,
                      for participant: TVIRemoteParticipant) {
    }
}

Receiving Messages

You can implement TVIRemoteDataTrackDelegate to receive incoming messages on a DataTrack.

// MARK: TVIRemoteDataTrackDelegate
extension ViewController : TVIRemoteDataTrackDelegate {
    func remoteDataTrack(_ remoteDataTrack: TVIRemoteDataTrack, didReceive message: String) {
    }

    func remoteDataTrack(_ remoteDataTrack: TVIRemoteDataTrack, didReceive message: Data) {
    }
}

Take a look at the iOS DataTrack Example to learn more.

Configuring DataTrack reliability

DataTracks are intended for low-latency communication between Participants. Importantly, to optimize for lowest latency possible, delivery of DataTrack messages is not guaranteed. You can think of them more like UDP messages, rather than TCP.

You can configure the retry parameters for your DataTrack with the following options:

  • maxPacketLifeTime sets the time in milliseconds during which the DataTrack will transmit or retransmit a message until that message is acknowledged.
  • maxRetransmits sets the maximum number of retransmit attempts that will be made.

In Group Rooms, DataTrack connections are established between Participants via the media server. Under the hood, there is one connection between a local Participant to the Media server and a second connection from the Media server to the remote Participant. Twilio’s media server configures the same maxPacketLifeTime value on each remote Participant's connection. Therefore you should set the maxPacketLifetime to half the acceptable max lifetime for each message you send.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.