快速入門：將資料通道傳訊功能新增至您的通話應用程式

資料通道功能 API 可在語音和視訊通話期間支援即時傳訊。 在本快速入門指南中，我們將說明如何整合資料通道功能，以便在群組通話時讓參與者可以交換文字簡訊。 請注意，除了資料通道功能以外，還有許多不同的訊息解決方案，您應該選擇適合的解決方案來滿足特定使用案例的需求。

建立 DataChannelSender 物件

首先，您必須先建立一個 DataChannelSender 物件來傳送訊息。 在此自訂傳訊應用程式中，我們建議指派一個數字給 channelId，用來區分不同的應用程式使用案例。 例如，若是自訂訊息，您可以 1000 給 channelId。

const dataChannel = call.feature(Features.DataChannel);
const messageSender = dataChannel.createDataChannelSender({
    channelId: 1000
});

還有幾個其他選項，例如可靠性、頻寬和優先順序。 您現在可以忽略這些選項，並使用預設值。 建立傳送者物件時，您仍然需要接收者物件來接收訊息。

註冊接聽程式以取得 DataChannelReceiver 物件

若要取得接收者物件，您必須註冊接聽程式以擷取 dataChannelReceiverCreated 事件。 建立接收者物件時，SDK 會連同接收者物件一起發出事件。

dataChannel.on('dataChannelReceiverCreated', receiver => {
    // receiver.channelId
    // reciever.senderParticipantIdentifier, which shows the sender id
});

在接聽程式回撥函式中，您可以存取接收者物件，並擷取 channelId 和傳送者參與者的參與者識別碼 senderParticipantIdentifier 等資訊。 您必須負責維護接收者物件參考，因為 SDK 會針對每個建立的接收者物件發出一次事件。

處理 DataChannelReceiver 的 messageReady 和 close 事件

當訊息送達時，DataChannelReceiver 物件會收到訊息、將其儲存在內部緩衝區中並發出 messageReady 事件。 不需要註冊 messageReady 事件接聽程式來接收訊息，因為您一直都可以隨時呼叫 readMessage API。 不過，為了獲得最佳做法，建議您在 messageReady 接聽程式回撥中讀取訊息，如果訊息處理需要很長的時間，您可以將工作卸載給 Web 背景工作角色，以防止封鎖訊息接收。

dataChannel.on('dataChannelReceiverCreated', receiver => {
    if (receiver.channelId === 1000) {
        receiver.on('close', () => {
            console.log(`data channel id = ${receiver.channelId} from ${JSON.stringify(receiver.senderParticipantIdentifier)} is closed`);
        });
        receiver.on('messageReady', () => {
            const message = receiver.readMessage();
            // process the message
        });
    }
});

設定參與者

若要指定訊息的收件者，您可以使用 DataChannelSender.setParticipants API。 傳送者物件會維護您所提供的最新參與者清單。 參與者類型是 CommunicationIdentifier，您可以從 remoteParticipant.identifier 中取得。 如需詳細資訊，請參閱存取遠端參與者屬性。

const user = call.remoteParticipants[0]; // assume the user wants to send a message to the first participant in the remoteParticipants list
messageSender.setParticipants([user.identifier]);

請注意，參與者清單的參與者數目上限為 64 名。 如果參與者清單是空陣列，SDK 會將訊息廣播給通話中的所有參與者。

傳送和接收訊息

資料通道功能 API 會要求您以 Uint8Array 類型傳遞資料。 您無法使用 sendMessage API 直接傳送 JavaScript 字串。 例如，如果您要傳送字串 abc，則無法使用 sender.sendMessage('abc')。 而必須改為先在位元組緩衝區中序列化資料。

const data = (new TextEncoder()).encode('abc');
sender.sendMessage(data);

以下是另一個傳送 JSON 物件的範例。

const obj = {...}; // some object
const data = (new TextEncoder()).encode(JSON.stringify(obj));
sender.sendMessage(data);

接收和解碼訊息

dataChannel.on('dataChannelReceiverCreated', receiver => {
    if (receiver.channelId === 1000) {
        const textDecoder = new TextDecoder();
        receiver.on('close', () => {
            console.log(`data channel id = ${receiver.channelId} from ${JSON.stringify(receiver.senderParticipantIdentifier)} is closed`);
        });
        receiver.on('messageReady', () => {
            const message = receiver.readMessage();
            const text = textDecoder.decode(message.data);
            console.log(`from ${JSON.stringify(receiver.senderParticipantIdentifier)}:${text}`);
        });
    }
});

您可以使用下列連結取得完整的範例：https://github.com/Azure-Samples/communication-services-web-calling-tutorial

概觀

資料通道功能 API 可在語音和視訊通話期間支援即時資料傳訊。 在本快速入門指南中，我們將說明如何將資料通道功能整合到您的通話，並使用資料通道 API 透過資料通道傳送和接收資料訊息。

必要條件

請參閱語音通話快速入門，設定具有語音通話功能的範例應用程式。

類別

列舉

錯誤碼

方法

啟用資料通道功能

1. 取得在執行必要條件步驟期間建立的持續呼叫物件。
2. 取得資料通道功能物件。

DataChannelCallFeature dataChannelCallFeature = call.feature(Features.DATA_CHANNEL);

接收資料訊息

1. 定義 DataChannelReceiverCreatedListener。

DataChannelReceiverCreatedListener receiverCreatedListener = new DataChannelReceiverCreatedListener() {
    @Override
    public void onReceiverCreated(DataChannelReceiverCreatedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the new data channel receiver
        int channelId = receiver.getChannelId(); // get the channel id
        CommunicationIdentifier senderId = receiver.getSenderIdentifier(); // get the message sender id
        // listen to the message received event and closed event from this receiver
        // receiver.addOnMessageReceivedListener(messageReceivedlistener);
        // receiver.addOnClosedListener(receiverClosedListener);
    }
};

2. 註冊 receiverCreatedListener。

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

3. 定義 MessageReceivedListener。

MessageReceivedListener messageReceivedListener = new MessageReceivedListener() {
    @Override
    public void onMessageReceived(PropertyChangedEvent e) {
        DataChannelMessage message = e.getReceiver().receiveMessage(); // read the data message from the receiver
        int sequence = message.getSequenceNumber(); // get the message sequence number
        byte[] data = message.getData(); // get the data content
    }
};

4. 定義 ReceiverClosedListener。

ReceiverClosedListener receiverClosedListener = new ReceiverClosedListener() {
    @Override
    public void onReceiverClosed(PropertyChangedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the data channel receiver to be closed
    }
};

5. 註冊 messageReceivedListener 和 receiverClosedListener。

receiver.addOnMessageReceivedListener(messageReceivedlistener);
receiver.addOnClosedListener(receiverClosedListener);

傳送資料訊息

1. 設定 DataChannelSenderOptions。

DataChannelSenderOptions options = new DataChannelSenderOptions();
options.setChannelId(1000);
options.setBitrateInKbps(32);
options.setPriority(DataChannelPriority.NORMAL);
options.setReliability(DataChannelReliability.LOSSY);

List<CommunicationIdentifier> participants = Arrays.asList( /* identifier1, identifier2, ... */ );
options.setParticipants(participants);

2. 取得 DataChannelSender 並傳送資料訊息

DataChannelSender dataChannelSender = dataChannelCallFeature.getDataChannelSender(options);

// msgData contains the byte[] data to be sent
dataChannelSender.sendMessage(msgData);

// change participants in the channel if needed
dataChannelSender.setParticipants(new ArrayList<CommunicationIdentifier>()); 

概觀

資料通道功能 API 可在語音和視訊通話期間支援即時資料傳訊。 在本快速入門指南中，我們將說明如何將資料通道功能整合到您的通話，並使用資料通道 API 透過資料通道傳送和接收資料訊息。

必要條件

請參閱語音通話快速入門，設定具有語音通話功能的範例應用程式。

類別

列舉

錯誤碼

方法

啟用資料通道功能

1. 取得在執行必要條件步驟期間建立的持續呼叫物件。
2. 取得資料通道功能物件。

var dataChannelCallFeature = self.call!.feature(Features.dataChannel)

接收資料訊息

let featureDelegate = new FeatureDelegate()
let receiverDelegate = new ReceiverDelegate()
dataChannelCallFeature!.delegate = featureDelegate

class FeatureDelegate: NSObject, DataChannelCallFeatureDelegate {
    public func dataChannelCallFeature(_ dataChannelCallFeature: DataChannelCallFeature, didCreateReceiver args: DataChannelReceiverCreatedEventArgs) {
        let receiver = args.receiver // get the new data channel receiver
        let channelId = receiver.channelId // get the channel id
        let senderId = receiver.senderIdentifier // get the message sender id

        receiver.delegate = receiverDelegate
    }
}

class ReceiverDelegate: NSObject, DataChannelReceiverDelegate {
    public func dataChannelReceiver(_ dataChannelReceiver: DataChannelReceiver, didReceiveMessage args: PropertyChangedEventArgs) {
        let message = dataChannelReceiver.receiveMessage() // read the data message from the receiver
        let sequence = message?.sequenceNumber // get the message sequence number
        let data = message?.data // get the data content
    }
    
    public func dataChannelReceiver(_ dataChannelReceiver: DataChannelReceiver, didClose args: PropertyChangedEventArgs) {
       let channelId = dataChannelReceiver.channelId // get the data channel id to be closed
    }
}

傳送資料訊息

1. 設定 DataChannelSenderOptions。

let options = new DataChannelSenderOptions()
options.channelId = 1000
options.bitrateInKbps = 32
options.priority = DataChannelPriority.normal
options.reliability = DataChannelReliability.lossy

let communicationIdentifiers: [CommunicationIdentifier] = [ /* identifier1, identifier2, ... */ ]
options.participants = communicationIdentifiers

2. 定義 DataChannelSender 和傳送資料訊息

DataChannelSender sender = dataChannelCallFeature.getDataChannelSender(options)

// msgData contains the data to be sent
sender.sendMessage(msgData)

// change participants in the channel if needed
let participants: [CommunicationIdentifier] = []
dataChannelSender.setParticipants(participants: participants)

概觀

資料通道功能 API 可在語音和視訊通話期間支援即時資料傳訊。 在本快速入門指南中，我們將說明如何將資料通道功能整合到您的通話，並使用資料通道 API 透過資料通道傳送和接收資料訊息。

必要條件

請參閱語音通話快速入門，設定具有語音通話功能的範例應用程式。

類別

列舉

錯誤碼

方法

啟用資料通道功能

1. 取得在執行必要條件步驟期間建立的持續呼叫物件。
2. 取得資料通道功能物件。

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

接收資料訊息

1. 定義 DataChannelReceiverCreated 事件處理常式。

void DataChannelReceiverCreatedHandler(object sender, DataChannelReceiverCreatedEventArgs args) 
{
    DataChannelReceiver receiver = args.Receiver; // get the new data channel receiver
    int channelId = receiver.ChannelId; // get the channel id
    CallIdentifier senderId = receiver.SenderIdentifier; // get the message sender id
    
    // add event handlers for the message received event and closed event from this receiver
    // receiver.MessageReceived += MessageReceivedHandler;
    // receiver.Closed += ReceiverClosedHandler;
}

2. 附加 DataChannelReceiverCreatedHandler。

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

3. 定義 MessageReceived 事件處理常式。

void MessageReceivedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelMessage message = (sender as DataChannelReceiver).ReceiveMessage(); // read the data message from the receiver
    long sequence = message.SequenceNumber; // get the message sequence number
    byte[] data = message.Data; // get the data content
}

4. 定義 Closed 事件處理常式。

void ReceiverClosedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelReceiver receiver = sender as DataChannelReceiver; // get the data channel receiver to be closed
};

5. 附加 MessageReceivedHandler 和 ReceiverClosedHandler。

receiver.MessageReceived += MessageReceivedHandler;
receiver.Closed += ReceiverClosedHandler;

傳送資料訊息

1. 設定 DataChannelSenderOptions。

DataChannelSenderOptions options = new DataChannelSenderOptions();
options.ChannelId = 1000;
options.BitrateInKbps = 32;
options.Priority = DataChannelPriority.Normal;
options.Reliability = DataChannelReliability.Lossy;
var participants = new List<CallIdentifier> { /* identifier1, identifier2, ... */ };
options.Participants = participants.AsReadOnly();

2. 定義 DataChannelSender 和傳送資料訊息

DataChannelSender sender = dataChannelCallFeature.GetDataChannelSender(options);
// msgData contains the byte[] data to be sent
sender.SendMessage(msgData);
// change participants in the channel if needed
sender.SetParticipants(new List<CallIdentifier>().AsReadOnly());