|
| 1 | +--- |
| 2 | +ms.author: chengyuanlai |
| 3 | +title: Quickstart - Add data channel to your Android calling app |
| 4 | +titleSuffix: An Azure Communication Services document |
| 5 | +description: In this quickstart, you learn how to add data channel messaging to your existing Android calling app using Azure Communication Services. |
| 6 | +author: sloanster |
| 7 | +services: azure-communication-services |
| 8 | +ms.date: 05/04/2023 |
| 9 | +ms.topic: include |
| 10 | +ms.service: azure-communication-services |
| 11 | +ms.subservice: calling |
| 12 | +--- |
| 13 | + |
| 14 | +[!INCLUDE [Public Preview](../../../../includes/public-preview-include-document.md)] |
| 15 | +>[!IMPORTANT] |
| 16 | +> Please be aware that the current Data Channel feature API doesn't support direct messaging between a web browser and a native app in a peer-to-peer call scenario. |
| 17 | +
|
| 18 | +## Overview |
| 19 | +The Data Channel feature API enables real-time data messaging during audio and video calls. In this quickstart guide, we illustrate how to integrate Data Channel feature to your call and use the Data Channel APIs to send and receive data messages through a data channel. |
| 20 | +### Prerequisites |
| 21 | +Refer to the [Voice Calling Quickstart](../../getting-started-with-calling.md?pivots=platform-android) to set up a sample app with voice calling. |
| 22 | +### Classes |
| 23 | +| Name | Description | |
| 24 | +| - | - | |
| 25 | +| DataChannelCallFeature | Used to start and manage data channel feature. | |
| 26 | +| DataChannelSender | Used to manage a data channel as a sender and send data. | |
| 27 | +| DataChannelReceiver | Used to manage a data channel as a receiver and receive data. | |
| 28 | +| DataChannelSenderCreateOptions | Used for representing options to create a data channel sender. | |
| 29 | +### Events |
| 30 | +| Name | Description | |
| 31 | +| - | - | |
| 32 | +| DataChannelReceiverCreatedEvent | Describes the event when a receiver is created. A new receiver is created when receiving a data message from another endpoint through a new data channel for the first time. | |
| 33 | +| DataChannelReceiverMessageReceivedEvent | Describes the event when a data message is received and ready to be fetched. | |
| 34 | +| DataChannelReceiverClosedEvent | Describes the event when a data channel receiver is to be closed. | |
| 35 | +### Listeners |
| 36 | +| Name | Description | |
| 37 | +| - | - | |
| 38 | +| DataChannelReceiverCreatedListener | Used to handle `DataChannelReceiverCreatedEvent`. | |
| 39 | +| DataChannelReceiverMessageReceivedListener | Used to handle `DataChannelReceiverMessageReceivedEvent`. | |
| 40 | +| DataChannelReceiverClosedListener | Used to handle `DataChannelReceiverClosedEvent`. | |
| 41 | +### Enums |
| 42 | +| Name | Description | |
| 43 | +| - | - | |
| 44 | +| DataChannelPriority | Describes the priority options of data channel. Values: { `NORMAL`, `HIGH` }. | |
| 45 | +| DataChannelReliability | Describes the reliability options of data channel. Values: { `LOSSY`, `DURABLE` }. | |
| 46 | +### Methods |
| 47 | +#### Enable Data Channel feature |
| 48 | + |
| 49 | +1. Get the ongoing call object established during the prerequisite steps. |
| 50 | +2. Get the Data Channel Feature object. |
| 51 | +```java |
| 52 | +DataChannelCallFeature dataChannelCallFeature = call.feature(Features.DATA_CHANNEL); |
| 53 | +``` |
| 54 | +#### Receiving data message |
| 55 | +1. Define the DataChannelReceiverCreatedListener. |
| 56 | +```java |
| 57 | +DataChannelReceiverCreatedListener receiverCreatedListener = new DataChannelReceiverCreatedListener() { |
| 58 | + @Override |
| 59 | + public void onDataChannelReceiverCreated(DataChannelReceiverCreatedEvent e) { |
| 60 | + DataChannelReceiver receiver = e.getReceiver(); // get the new data channel receiver |
| 61 | + int channelId = receiver.getChannelId(); // get the channel id |
| 62 | + CommunicationIdentifier senderId = receiver.getSenderIdentifier(); // get the message sender id |
| 63 | + // listen to the message received event and closed event from this receiver |
| 64 | + // receiver.addOnMessageReceivedListener(messageReceivedlistener); |
| 65 | + // receiver.addOnClosedListener(receiverClosedListener); |
| 66 | + } |
| 67 | +}; |
| 68 | +``` |
| 69 | +2. Register the `receiverCreatedListener`. |
| 70 | +```java |
| 71 | +dataChannelCallFeature.addOnDataChannelReceiverCreatedListener(receiverCreatedListener); |
| 72 | + ``` |
| 73 | +3. Define the DataChannelReceiverMessageReceivedListener. |
| 74 | +```java |
| 75 | +DataChannelReceiverMessageReceivedListener messageReceivedListener = new DataChannelReceiverMessageReceivedListener() { |
| 76 | + @Override |
| 77 | + public void onMessageReceived(DataChannelReceiverMessageReceivedEvent e) { |
| 78 | + DataChannelMessage message = e.getReceiver().readMessage(); // read the data message from the receiver |
| 79 | + int sequence = message.getSequenceNumber(); // get the message sequence number |
| 80 | + byte[] data = message.getData(); // get the data content |
| 81 | + } |
| 82 | +}; |
| 83 | +``` |
| 84 | +4. Define the DataChannelReceiverClosedListener. |
| 85 | +```java |
| 86 | +DataChannelReceiverClosedListener receiverClosedListener = new DataChannelReceiverClosedListener() { |
| 87 | + @Override |
| 88 | + public void onReceiverClosed(DataChannelReceiverClosedEvent e) { |
| 89 | + DataChannelReceiver receiver = e.getReceiver(); // get the data channel receiver to be closed |
| 90 | + // clean up resources related to the receiver |
| 91 | + } |
| 92 | +}; |
| 93 | +``` |
| 94 | +5. Register the `messageReceivedListener` and `receiverClosedListener`. |
| 95 | +```java |
| 96 | +receiver.addOnMessageReceivedListener(messageReceivedlistener); |
| 97 | +receiver.addOnClosedListener(receiverClosedListener); |
| 98 | +``` |
| 99 | +#### Sending data message |
| 100 | +1. Configure the DataChannelSenderCreateOptions. |
| 101 | +```java |
| 102 | +DataChannelSenderCreateOptions options = new DataChannelSenderCreateOptions(); |
| 103 | +options.setChannelId(1000); |
| 104 | +options.setBitrateInKbps(32); |
| 105 | +options.setPriority(DataChannelPriority.NORMAL); |
| 106 | +options.setReliability(DataChannelReliability.LOSSY); |
| 107 | + |
| 108 | +List<CommunicationIdentifier> participants = Arrays.asList( /* identifier1, identifier2, ... */ ); |
| 109 | +options.setParticipants(participants); |
| 110 | +``` |
| 111 | +2. Define the DataChannelSender and send data message |
| 112 | +```java |
| 113 | +DataChannelSender dataChannelSender = dataChannelCallFeature.createDataChannelSender(options); |
| 114 | +dataChannelSender.setParticipants(new ArrayList<CommunicationIdentifier>()); // change participants in the channel if needed |
| 115 | +dataChannelSender.sendMessage(msgData); // msgData contains the byte[] data to be sent |
| 116 | +``` |
0 commit comments