Freigeben über

Schnellstart: Hinzufügen von Datenkanalmessaging zu Ihrer Anruf-App

  • Artikel

Die DataChannel-Feature-API ermöglicht Echtzeitmessaging während Audio- und Videoanrufen. In dieser Schnellstartanleitung wird veranschaulicht, wie Sie das Datenkanalfeature integrieren, um den Austausch von Textnachrichten zwischen Teilnehmern innerhalb eines Gruppenaufrufs zu ermöglichen. Beachten Sie, dass es viele verschiedene Messaginglösungen außer dem Datenkanalfeature gibt, und Sie sollten die geeignete Lösung für Ihr spezifisches Verwendungsszenario auswählen.

Wichtig

Beachten Sie, dass unsere aktuelle Implementierung der DataChannel-Feature-API in einem Peer-to-Peer-Anrufszenario kein direktes Messaging zwischen einem Webbrowser und einer nativen App unterstützt.

Erstellen eines DataChannelSender-Objekts

Sie müssen zunächst ein DataChannelSender-Objekt erstellen, um Nachrichten senden zu können. In dieser benutzerdefinierten Messaginganwendung wird empfohlen, channelIdeine Zahl zuzuweisen, die dazu dient, verschiedene Anwendungsfälle der Anwendung zu unterscheiden. Beispielsweise können Sie channelId die Zahl 1000 für benutzerdefinierte Nachrichten zuweisen.

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

Es gibt einige andere Optionen, z. B. Zuverlässigkeit, Bandbreite und Priorität. Sie können diese vorerst ignorieren und die Standardwerte verwenden. Das Absenderobjekt ist zwar erstellt, doch benötigen Sie noch ein Empfängerobjekt, um Nachrichten zu empfangen.

Registrieren eines Listeners zum Abrufen des DataChannelReceiver-Objekts

Zum Abrufen eines Empfängerobjekts müssen Sie einen Listener registrieren, der das dataChannelReceiverCreated-Ereignis erfasst. Beim Erstellen eines Empfängerobjekts gibt das SDK das Ereignis zusammen mit dem Empfängerobjekt aus.

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

Innerhalb der Listener-Rückruffunktion können Sie auf das Empfängerobjekt zugreifen und Informationen wie channelId und die Teilnehmer-ID des Absenders senderParticipantIdentifier abrufen. Es liegt in Ihrer Verantwortung, den Empfängerobjektverweis zu verwalten, da das SDK das Ereignis einmal für jedes erstellte Empfängerobjekt ausgibt.

Behandeln des MessageReady- und Close-Ereignisses des DataChannelReceiver-Objekts

Wenn eine Nachricht eingeht, empfängt das DataChannelReceiver-Objekt die Nachricht, speichert sie in seinem internen Puffer und gibt ein messageReady-Ereignis aus. Es ist nicht erforderlich, den messageReady-Ereignislistener zu registrieren, um Nachrichten zu empfangen, da Sie die readMessage-API jederzeit aufrufen können. Als bewährte Methode wird jedoch empfohlen, Nachrichten innerhalb des messageReady-Listenerrückrufs zu lesen. Wenn die Nachrichtenverarbeitung lange dauert, können Sie diese an einen Web Worker auslagern, um zu verhindern, dass der Nachrichtenempfang blockiert wird.

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
        });
    }
});

Festlegen von Teilnehmern

Sie können Sie die DataChannelSender.setParticipants-API verwenden, um die Empfänger für Ihre Nachrichten anzugeben. Das Absenderobjekt verwaltet die letzte von Ihnen bereitgestellte Teilnehmerliste. Der Teilnehmertyp ist CommunicationIdentifier, den Sie von remoteParticipant.identifierabrufen können. Weitere Informationen finden Sie unter Zugriff auf Remoteteilnehmer-Eigenschaften.

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]);

Beachten Sie, dass die Teilnehmerliste auf 64 Teilnehmer begrenzt ist. Wenn die Teilnehmerliste ein leeres Array ist, sendet das SDK die Nachricht an alle Teilnehmer des Anrufs.

Senden und Empfangen von Nachrichten

Die DataChannel-Feature-API erfordert, dass Sie Daten vom Typ Uint8Array übergeben. Sie können eine JavaScript-Zeichenfolge nicht direkt mit der sendMessage-API senden. Wenn Sie beispielsweise die Zeichenfolge abcsenden möchten, können Sie sender.sendMessage('abc') nicht verwenden. Stattdessen müssen Sie die Daten zuerst in einen Bytepuffer serialisieren.

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

Es folgt ein weiteres Beispiel für das Senden eines JSON-Objekts.

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

Empfangen und Decodieren der Nachricht

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}`);
        });
    }
});

Ein vollständiges Beispiel finden Sie unter dem folgenden Link: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Wichtig

Beachten Sie, dass die aktuelle Datenkanal-Feature-API in einem Peer-to-Peer-Anrufszenario kein direktes Messaging zwischen einem Webbrowser und einer nativen App unterstützt.

Überblick

Die Datenkanal-Feature-API ermöglicht Echtzeit-Datenmessaging während Audio- und Videoanrufen. In dieser Schnellstartanleitung wird veranschaulicht, wie Sie das Datenkanal-Feature in Ihren Anruf integrieren und die Datenkanal-APIs verwenden, um Datennachrichten über einen Datenkanal zu senden und zu empfangen.

Voraussetzungen

Informationen zum Einrichten einer Beispiel-App mit Sprachanrufen finden Sie unter dem Schnellstart: Sprachanruf.

Klassen

name Beschreibung
DataChannelCallFeature Wird zum Starten und Verwalten des Datenkanal-Features verwendet.
DataChannelSender Wird verwendet, um einen Datenkanal als Sender zu verwalten und Daten zu senden.
DataChannelReceiver Wird verwendet, um einen Datenkanal als Empfänger zu verwalten und Daten zu empfangen.
DataChannelSenderOptions Wird zum Darstellen von Optionen zum Erstellen eines Datenkanalsenders verwendet.

Enumerationen

Name Beschreibung
DataChannelPriority Beschreibt die Prioritätsoptionen des Datenkanals. Werte: { NORMAL, HIGH }.
DataChannelReliability Beschreibt die Zuverlässigkeitsoptionen des Datenkanals. Werte: { LOSSY, DURABLE }.

Fehlercode

Name Beschreibung
DATA_CHANNEL_FAILED_TO_START getDataChannelSender() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass der zugrunde liegende Datenkanal noch nicht verwendet werden kann.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE getDataChannelSender() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass alle verfügbaren zufälligen Kanal-IDs bereits verwendet wurden.
DATA_CHANNEL_SENDER_CLOSED sendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass der Sender bereits zuvor geschlossen wurde.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT sendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass die Größe der Nachrichtendaten den Grenzwert überschreitet. Sie können den Grenzwert für die Nachrichtengröße mithilfe von getMaxMessageSizeInBytes() in DataChannelSender abrufen.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH sendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an auf einen Fehler beim Senden der Nachricht hin, weil nicht genügend Bandbreite vorhanden ist.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT sendMessage() kann mit diesem Fehlercode fehlschlagen. Er weist darauf hin, dass der Versand der Nachricht fehlgeschlagen ist, weil die Gesamtnutzung des Datenkanals nicht den Regeln für die Verkehrsbegrenzung entspricht. Details zum Datenverkehrslimit finden Sie in der Dokumentation zum Konzept des Datenkanals.

Methoden

Aktivieren des Datenkanal-Features

  1. Rufen Sie das laufende Aufrufobjekt ab, das während der Vorbereitungsschritte eingerichtet wurde.
  2. Rufen Sie das Objekt für Datenkanal-Feature ab.
DataChannelCallFeature dataChannelCallFeature = call.feature(Features.DATA_CHANNEL);

Empfangen einer Datennachricht

  1. Definieren Sie 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);
    }
};
  1. Registrieren des receiverCreatedListener.
dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);
  1. Definieren des 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
    }
};
  1. Definieren des ReceiverClosedListener
ReceiverClosedListener receiverClosedListener = new ReceiverClosedListener() {
    @Override
    public void onReceiverClosed(PropertyChangedEvent e) {
        DataChannelReceiver receiver = e.getReceiver(); // get the data channel receiver to be closed
    }
};
  1. Registrieren Sie messageReceivedListener und receiverClosedListener.
receiver.addOnMessageReceivedListener(messageReceivedlistener);
receiver.addOnClosedListener(receiverClosedListener);

Senden einer Datennachricht

  1. Konfigurieren des 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);
  1. Abrufen des DataChannelSender und Senden einer Datennachricht
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>());

Wichtig

Beachten Sie, dass die aktuelle Datenkanal-Feature-API in einem Peer-to-Peer-Anrufszenario kein direktes Messaging zwischen einem Webbrowser und einer nativen App unterstützt.

Überblick

Die Datenkanal-Feature-API ermöglicht Echtzeit-Datenmessaging während Audio- und Videoanrufen. In dieser Schnellstartanleitung wird veranschaulicht, wie Sie das Datenkanal-Feature in Ihren Anruf integrieren und die Datenkanal-APIs verwenden, um Datennachrichten über einen Datenkanal zu senden und zu empfangen.

Voraussetzungen

Informationen zum Einrichten einer Beispiel-App mit Sprachanrufen finden Sie unter dem Schnellstart: Sprachanruf.

Klassen

name Beschreibung
DataChannelCallFeature Wird zum Starten und Verwalten des Datenkanal-Features verwendet.
DataChannelSender Wird verwendet, um einen Datenkanal als Sender zu verwalten und Daten zu senden.
DataChannelReceiver Wird verwendet, um einen Datenkanal als Empfänger zu verwalten und Daten zu empfangen.
DataChannelSenderOptions Wird zum Darstellen von Optionen zum Erstellen eines Datenkanalsenders verwendet.

Enumerationen

Name Beschreibung
DataChannelPriority Beschreibt die Prioritätsoptionen des Datenkanals. Werte: { normal, high }.
DataChannelReliability Beschreibt die Zuverlässigkeitsoptionen des Datenkanals. Werte: { lossy, durable }.

Fehlercode

Name Beschreibung
dataChannelFailedToStart getDataChannelSender() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass der zugrunde liegende Datenkanal noch nicht verwendet werden kann.
dataChannelRandomIdNotAvailable getDataChannelSender() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass alle verfügbaren zufälligen Kanal-IDs bereits verwendet wurden.
dataChannelSenderClosed sendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass der Sender bereits zuvor geschlossen wurde.
dataChannelMessageSizeOverLimit sendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass die Größe der Nachrichtendaten den Grenzwert überschreitet. Sie können den Grenzwert für die Nachrichtengröße mithilfe von maxMessageSizeInBytes in DataChannelSender abrufen.
dataChannelMessageFailureForBandwidth sendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an auf einen Fehler beim Senden der Nachricht hin, weil nicht genügend Bandbreite vorhanden ist.
dataChannelMessageFailureForTrafficLimit sendMessage() kann mit diesem Fehlercode fehlschlagen. Er weist darauf hin, dass der Versand der Nachricht fehlgeschlagen ist, weil die Gesamtnutzung des Datenkanals nicht den Regeln für die Verkehrsbegrenzung entspricht. Details zum Datenverkehrslimit finden Sie in der Dokumentation zum Konzept des Datenkanals.

Methoden

Aktivieren des Datenkanal-Features

  1. Rufen Sie das laufende Aufrufobjekt ab, das während der Vorbereitungsschritte eingerichtet wurde.
  2. Rufen Sie das Objekt für Datenkanal-Feature ab.
var dataChannelCallFeature = self.call!.feature(Features.dataChannel)

Empfangen einer Datennachricht

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
    }
}

Senden einer Datennachricht

  1. Konfigurieren des 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
  1. Definieren von DataChannelSender und Senden einer Datennachricht
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)

Wichtig

Beachten Sie, dass die aktuelle Datenkanal-Feature-API in einem Peer-to-Peer-Anrufszenario kein direktes Messaging zwischen einem Webbrowser und einer nativen App unterstützt.

Überblick

Die Datenkanal-Feature-API ermöglicht Echtzeit-Datenmessaging während Audio- und Videoanrufen. In dieser Schnellstartanleitung wird veranschaulicht, wie Sie das Datenkanal-Feature in Ihren Anruf integrieren und die Datenkanal-APIs verwenden, um Datennachrichten über einen Datenkanal zu senden und zu empfangen.

Voraussetzungen

Informationen zum Einrichten einer Beispiel-App mit Sprachanrufen finden Sie unter dem Schnellstart: Sprachanruf.

Klassen

name Beschreibung
DataChannelCallFeature Wird zum Starten und Verwalten des Datenkanal-Features verwendet.
DataChannelSender Wird verwendet, um einen Datenkanal als Sender zu verwalten und Daten zu senden.
DataChannelReceiver Wird verwendet, um einen Datenkanal als Empfänger zu verwalten und Daten zu empfangen.
DataChannelSenderOptions Wird zum Darstellen von Optionen zum Erstellen eines Datenkanalsenders verwendet.

Enumerationen

Name Beschreibung
DataChannelPriority Beschreibt die Prioritätsoptionen des Datenkanals. Werte: { Normal, High }.
DataChannelReliability Beschreibt die Zuverlässigkeitsoptionen des Datenkanals. Werte: { Lossy, Durable }.

Fehlercode

Name Beschreibung
DataChannelFailedToStart GetDataChannelSender() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass der zugrunde liegende Datenkanal noch nicht verwendet werden kann.
DataChannelRandomIdNotAvailable GetDataChannelSender() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass alle verfügbaren zufälligen Kanal-IDs bereits verwendet wurden.
DataChannelSenderClosed SendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass der Sender bereits zuvor geschlossen wurde.
DataChannelMessageSizeOverLimit SendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an, dass die Größe der Nachrichtendaten den Grenzwert überschreitet. Sie können den Grenzwert für die Nachrichtengröße mithilfe von MaxMessageSizeInBytes in DataChannelSender abrufen.
DataChannelMessageFailureForBandwidth SendMessage() kann mit diesem Fehlercode fehlschlagen. Er gibt an auf einen Fehler beim Senden der Nachricht hin, weil nicht genügend Bandbreite vorhanden ist.
DataChannelMessageFailureForTrafficLimit SendMessage() kann mit diesem Fehlercode fehlschlagen. Er weist darauf hin, dass der Versand der Nachricht fehlgeschlagen ist, weil die Gesamtnutzung des Datenkanals nicht den Regeln für die Verkehrsbegrenzung entspricht. Details zum Datenverkehrslimit finden Sie in der Dokumentation zum Konzept des Datenkanals.

Methoden

Aktivieren des Datenkanal-Features

  1. Rufen Sie das laufende Aufrufobjekt ab, das während der Vorbereitungsschritte eingerichtet wurde.
  2. Rufen Sie das Objekt für Datenkanal-Feature ab.
DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Empfangen einer Datennachricht

  1. Definieren Sie den DataChannelReceiverCreated-Ereignishandler:
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;
}
  1. Fügen Sie DataChannelReceiverCreatedHandler an.
dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;
  1. Definieren des MessageReceived-Ereignishandlers
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
}
  1. Definieren des Closed-Ereignishandlers
void ReceiverClosedHandler(object sender, PropertyChangedEventArgs args) 
{
    DataChannelReceiver receiver = sender as DataChannelReceiver; // get the data channel receiver to be closed
};
  1. Fügen Sie MessageReceivedHandler und ReceiverClosedHandler an.
receiver.MessageReceived += MessageReceivedHandler;
receiver.Closed += ReceiverClosedHandler;

Senden einer Datennachricht

  1. Konfigurieren des 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();
  1. Definieren von DataChannelSender und Senden einer Datennachricht
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());

Nächste Schritte

Weitere Informationen finden Sie in den folgenden Artikeln: