Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Using the DataTrack API with iOS v3.x


(warning)

Warning

This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.

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(link takes you to an external page) to learn about the DataTrack API.


Overview

overview page anchor

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 reliability .
  • 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.


Create a LocalDataTrack

create-a-localdatatrack page anchor

The TVILocalDataTrack(link takes you to an external page) is a Track that represents data that can be published to a Room by the TVILocalParticipant(link takes you to an external page).


_10
var localDataTrack = LocalDataTrack()

Connect to a Room with a LocalDataTrack

connect-to-a-room-with-a-localdatatrack page anchor

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


_10
let connectOptions = ConnectOptions(token: accessToken){ (builder) in
_10
builder.roomName = "my-room"
_10
if let localDataTrack = self.localDataTrack {
_10
builder.dataTracks = [localDataTrack]
_10
}
_10
}
_10
var room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)

Publish the LocalDataTrack

publish-the-localdatatrack page anchor

In the previous example, TVILocalDataTrack was published when connecting to the Room. You can also publish TVILocalDataTrack after connecting to a Room:


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

Send messages over the LocalDataTrack

send-messages-over-the-localdatatrack page anchor

The DataTrack API supports sending string as well as byte data. You can use sendString(link takes you to an external page) or sendData(link takes you to an external page) 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:

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.


_17
// MARK: LocalParticipantDelegate
_17
extension MyClass : LocalParticipantDelegate {
_17
func localParticipantDidPublishDataTrack(participant: LocalParticipant, dataTrackPublication: LocalDataTrackPublication) {
_17
// The data track has been published and is ready for use
_17
_17
guard let localDataTrack = dataTrackPublication.localTrack else {
_17
return
_17
}
_17
_17
let message = "Hello DataTrack!"
_17
localDataTrack.send(message)
_17
_17
// Assume bytes and length are defined elsewhere
_17
var messageBuffer = Data(bytes: bytes, length: length)
_17
localDataTrack.send(messageBuffer)
_17
}
_17
}

Listening for RemoteDataTrack events

listening-for-remotedatatrack-events page anchor

The TVIRemoteParticipant(link takes you to an external page) class provides a delegate protocol named TVIRemoteParticipantDelegate(link takes you to an external page). You can implement this protocol to learn about published and unpublished DataTrack events.


_27
// MARK: RemoteParticipantDelegate
_27
extension MyClass : RemoteParticipantDelegate {
_27
_27
// Participant has published a data track.
_27
func remoteParticipantDidPublishDataTrack(participant: RemoteParticipant,
_27
publication: RemoteDataTrackPublication) {
_27
}
_27
_27
// Participant has unpublished a data track.
_27
func remoteParticipantDidUnpublishDataTrack(participant: RemoteParticipant,
_27
publication: RemoteDataTrackPublication) {
_27
}
_27
_27
// Data track has been subscribed to and messages can be observed.
_27
func didSubscribeToDataTrack(dataTrack: RemoteDataTrack,
_27
publication: RemoteDataTrackPublication,
_27
participant: RemoteParticipant) {
_27
// Respond to incoming messages.
_27
dataTrack.delegate = self
_27
}
_27
_27
// Data track has been unsubsubscribed from and messages cannot be observed.
_27
func didUnsubscribeFromDataTrack(dataTrack: RemoteDataTrack,
_27
publication: RemoteDataTrackPublication,
_27
participant: RemoteParticipant) {
_27
}
_27
}

You can implement TVIRemoteDataTrackDelegate(link takes you to an external page) to receive incoming messages on a DataTrack.


_10
// MARK: RemoteDataTrackDelegate
_10
extension ViewController : RemoteDataTrackDelegate {
_10
func remoteDataTrackDidReceiveString(remoteDataTrack: RemoteDataTrack, message: String) {
_10
}
_10
_10
func remoteDataTrackDidReceiveData(remoteDataTrack: RemoteDataTrack, message: Data) {
_10
}
_10
}

For a fully working example and to learn more about Data Tracks, take a look at the iOS DataTrack Example(link takes you to an external page).


Configuring DataTrack reliability

configuring-datatrack-reliability page anchor

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.


Rate this page: