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.
概要
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
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 Android SDK.
Using the DataTrack API
Create a local DataTrack
The LocalDataTrack is a Track that represents data that can be published to a Room by the LocalParticipant
LocalDataTrack localDataTrack = LocalDataTrack.create(context);
Connect to a Room with a LocalDataTrack
Next, we want to connect to a Room with the LocalDataTrack
we created earlier
ConnectOptions connectOptions = new ConnectOptions.Builder(token) .dataTracks(Collections.singletonList(localDataTrack)) .build(); Video.connect(context, connectOptions, roomListener);
Publish the LocalDataTrack
After connecting to the Room, we now want to publish our LocalDataTrack
to it.
LocalParticipant localParticipant = room.getLocalParticipant(); localParticipant.publish(localDataTrack);
Sending messages over the DataTrack
The DataTrack API supports sending string
as well as byte
data.
String message = "Hello DataTrack!"; localDataTrack.send(message); ByteBuffer messageBuffer = ByteByffer.wrap(new byte[]{ 0xf, 0xe }); localDataTrack.send(messageBuffer);
Listening for DataTrack events
The RemoteParticipant class provides a listener interface. You can implement this interface to listen to published and unpublished DataTrack events.
RemoteParticipant.Listener participantListener = new RemoteParticipant.Listener() { // Participant has published data track @Override public void onDataTrackPublished(RemoteParticipant remoteParticipant, RemoteDataTrackPublication remoteDataTrackPublication) {} // Participant has unpublished data track @Override public void onDataTrackUnpublished(RemoteParticipant remoteParticipant, RemoteDataTrackPublication remoteDataTrackPublication) {} // Data track has been subscribed to and messages can be observed. @Override public void onDataTrackSubscribed(RemoteParticipant remoteParticipant, RemoteDataTrackPublication remoteDataTrackPublication,RemoteDataTrack remoteDataTrack) {} // Data track has been unsubsubscribed from and messages cannot be // observed. @Override public void onDataTrackUnsubscribed(RemoteParticipant remoteParticipant, RemoteDataTrackPublication remoteDataTrackPublication, RemoteDataTrack remoteDataTrack) {} };
Receiving messages from the DataTrack
RemoteDataTrack.Listener dataTrackListener = new RemoteDataTrack.Listener() { @Override public void onMessage(String message) { // Should print "Hello DataTrack!" Log.d(TAG, String.format("Received data track message: %s", message)); } } @Override public void onMessage(ByteBuffer message) { Log.d(TAG, "Received message buffer on data track!"); } }; remoteDataTrack.setListener(dataTrackListener);
Take a look at the Android Quickstart Application 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.
ヘルプが必要ですか?
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.