Using the DataTrack API - iOS 4.x
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. Use this guide along with our example app iOS DataTrack Example to learn about the DataTrack API.
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
. - TVILocalDataTrack is used to send messages to a room.
- Implement TVIRemoteDataTrackDelegate to receive messages.
- DataTracks have built-in mechanisms to
support reliable transmission
. Check out the section on Configuring DataTrack reliability. - Recommended maximum payload size of data sent over the DataTrack is
16KiB
. string
orbyte
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 = LocalDataTrack()
Connect to a Room with a LocalDataTrack
Next, we want to connect to a Room with the TVILocalDataTrack
we created earlier.
let connectOptions = ConnectOptions(token: accessToken){ (builder) in
builder.roomName = "my-room"
if let localDataTrack = self.localDataTrack {
builder.dataTracks = [localDataTrack]
}
}
var room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)
Publish the LocalDataTrack
In the previous example, TVILocalDataTrack
was published when connecting to the Room. You can also publish TVILocalDataTrack
after connecting to a Room:
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. You can use sendString or sendData to send data to the Room. DataTracks behave similarly to audio and video Tracks in the sense that, Participants will only receive data that was sent after:
- The TVILocalDataTrack was successfully published to the Room, and
- The Participant subscribed to the DataTrack.
For example, if Alice starts sending a stream of consecutive natural numbers (one number per second), and Bob joins the Room and subscribes to Alice's DataTrack after 5 seconds while Charlie joins the Room and subscribes to Alice's DataTrack after 10 seconds, then Bob will receive all the numbers starting from 6, and Charlie will receive all the numbers starting from 11.
// MARK: LocalParticipantDelegate
extension MyClass : LocalParticipantDelegate {
func localParticipantDidPublishDataTrack(participant: LocalParticipant, dataTrackPublication: LocalDataTrackPublication) {
// The data track has been published and is ready for use
guard let localDataTrack = dataTrackPublication.localTrack else {
return
}
let message = "Hello DataTrack!"
localDataTrack.send(message)
// Assume bytes and length are defined elsewhere
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: RemoteParticipantDelegate
extension MyClass : RemoteParticipantDelegate {
// Participant has published a data track.
func remoteParticipantDidPublishDataTrack(participant: RemoteParticipant,
publication: RemoteDataTrackPublication) {
}
// Participant has unpublished a data track.
func remoteParticipantDidUnpublishDataTrack(participant: RemoteParticipant,
publication: RemoteDataTrackPublication) {
}
// Data track has been subscribed to and messages can be observed.
func didSubscribeToDataTrack(dataTrack: RemoteDataTrack,
publication: RemoteDataTrackPublication,
participant: RemoteParticipant) {
// Respond to incoming messages.
dataTrack.delegate = self
}
// Data track has been unsubsubscribed from and messages cannot be observed.
func didUnsubscribeFromDataTrack(dataTrack: RemoteDataTrack,
publication: RemoteDataTrackPublication,
participant: RemoteParticipant) {
}
}
Receiving Messages
You can implement TVIRemoteDataTrackDelegate to receive incoming messages on a DataTrack.
// MARK: RemoteDataTrackDelegate
extension ViewController : RemoteDataTrackDelegate {
func remoteDataTrackDidReceiveString(remoteDataTrack: RemoteDataTrack, message: String) {
}
func remoteDataTrackDidReceiveData(remoteDataTrack: RemoteDataTrack, message: Data) {
}
}
For a fully working example and to learn more about Data Tracks, take a look at the iOS DataTrack Example.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.