Quickstart: Data Channel Messaging toevoegen aan uw aanroepende app

Artikel
08/06/2024

Met de functie-API voor gegevenskanalen kunt u realtime berichten verzenden tijdens audio- en videogesprekken. In deze snelstartgids laten we zien hoe u de functie Gegevenskanaal integreert, waardoor tekstberichten kunnen worden uitgewisseld tussen deelnemers in een groepsgesprek. Houd er rekening mee dat er veel andere berichtenoplossingen zijn dan de functie Data Channel en u moet de geschikte oplossing kiezen voor uw specifieke gebruiksscenario.

Belangrijk

Houd er rekening mee dat onze huidige implementatie van de DataChannel-functie-API geen directe berichten ondersteunt tussen een webbrowser en een systeemeigen app in een peer-to-peer-oproepscenario.

Een DataChannelSender-object maken

Eerst moet u een DataChannelSender-object maken om berichten te verzenden. In deze aangepaste berichtentoepassing raden we u aan een nummer toe te channelIdwijzen, dat dient om verschillende toepassingsgebruiksscenario's te onderscheiden. U kunt bijvoorbeeld 1000 toewijzen channelId voor aangepaste berichten.

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

Er zijn verschillende andere opties, zoals betrouwbaarheid, bandbreedte en prioriteit. U kunt deze voorlopig negeren en de standaardwaarden gebruiken. Terwijl het afzenderobject is gemaakt, hebt u nog steeds een ontvangerobject nodig om berichten te ontvangen.

Een listener registreren om het DataChannelReceiver-object te verkrijgen

Als u een ontvangerobject wilt verkrijgen, moet u een listener registreren waarmee de dataChannelReceiverCreated gebeurtenis wordt vastgelegd. Wanneer een ontvangerobject wordt gemaakt, verzendt de SDK de gebeurtenis samen met het ontvangerobject.

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

Binnen de callback-functie van de listener hebt u toegang tot het ontvangerobject en kunt u informatie ophalen, zoals channelId en de deelnemer-id senderParticipantIdentifiervan de afzender. Het is uw verantwoordelijkheid om de verwijzing naar het ontvangerobject te behouden, omdat de SDK de gebeurtenis eenmaal verzendt voor elk gemaakt ontvangerobject.

MessageReady verwerken en gebeurtenis van DataChannelReceiver-object sluiten

Wanneer een bericht binnenkomt, ontvangt het DataChannelReceiver-object het bericht, slaat het op in de interne buffer en verzendt het een messageReady gebeurtenis. Het is niet nodig om de gebeurtenislistener te registreren messageReady om berichten te ontvangen, omdat u de readMessage API altijd op elk gewenst moment kunt aanroepen. Voor aanbevolen procedures raden we u echter aan om het bericht te lezen in de callback van de messageReady listener, als het verwerken van berichten lang duurt, kunt u het werk offloaden naar een webmedewerker om te voorkomen dat de ontvangst van berichten wordt geblokkeerd.

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

Deelnemers instellen

Als u de geadresseerden voor uw berichten wilt opgeven, kunt u API gebruiken DataChannelSender.setParticipants . Het afzenderobject onderhoudt de meest recente lijst met deelnemers die u opgeeft. Het type deelnemer is CommunicationIdentifier, dat u kunt verkrijgen van remoteParticipant.identifier. Raadpleeg de eigenschappen van externe deelnemers in Access voor meer informatie.

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

Houd er rekening mee dat de lijst met deelnemers beperkt is tot 64 deelnemers. Als de lijst met deelnemers een lege matrix is, verzendt de SDK het bericht naar alle deelnemers in de oproep.

Berichten verzenden en ontvangen

DataChannel feature-API vereist dat u gegevens doorgeeft als Uint8Array type. U kunt een JavaScript-tekenreeks niet rechtstreeks verzenden met behulp van sendMessage API. Als u bijvoorbeeld een tekenreeks abcwilt verzenden, kunt u deze niet gebruiken sender.sendMessage('abc'). In plaats daarvan moet u de gegevens eerst serialiseren naar een bytebuffer.

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

Hier volgt een ander voorbeeld voor het verzenden van een JSON-object.

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

Het bericht ontvangen en decoderen

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

U vindt een volledig voorbeeld via de volgende koppeling: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Belangrijk

Houd er rekening mee dat de huidige API voor gegevenskanaalfuncties geen ondersteuning biedt voor directe berichten tussen een webbrowser en een systeemeigen app in een peer-to-peer-oproepscenario.

Overzicht

Met de functie-API voor gegevenskanalen kunt u realtime gegevensberichten verzenden tijdens audio- en videogesprekken. In deze snelstartgids laten we zien hoe u de functie Data Channel kunt integreren in uw aanroep en hoe u de Data Channel-API's gebruikt om gegevensberichten via een gegevenskanaal te verzenden en te ontvangen.

Vereisten

Raadpleeg de quickstart voor spraakoproepen om een voorbeeld-app in te stellen met spraakoproepen.

Klassen

Name	Beschrijving
DataChannelCallFeature	Wordt gebruikt om de functie voor het gegevenskanaal te starten en te beheren.
DataChannelSender	Wordt gebruikt voor het beheren van een gegevenskanaal als afzender en het verzenden van gegevens.
DataChannelReceiver	Wordt gebruikt voor het beheren van een gegevenskanaal als ontvanger en het ontvangen van gegevens.
DataChannelSenderOptions	Wordt gebruikt voor het weergeven van opties voor het maken van een afzender van een gegevenskanaal.

Enums

Name	Beschrijving
DataChannelPriority	Beschrijft de prioriteitsopties van het gegevenskanaal. Waarden: { `NORMAL`, `HIGH` }.
Betrouwbaarheid van DataChannel	Beschrijft de betrouwbaarheidsopties van het gegevenskanaal. Waarden: { `LOSSY`, `DURABLE` }.

Foutcode

Name	Beschrijving
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` kan mislukken met deze foutcode, wat aangeeft dat het onderliggende gegevenskanaal niet gereed is om te worden gebruikt.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` kan mislukken met deze foutcode, waarmee wordt aangegeven dat alle beschikbare willekeurige kanaal-id's al zijn gebruikt.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` kan mislukken met deze foutcode, waarmee wordt aangegeven dat de afzender al eerder is gesloten.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` kan mislukken met deze foutcode, wat aangeeft dat de gegevensgrootte van het bericht groter is dan de limiet. U kunt de limiet voor de berichtgrootte ophalen met behulp van `getMaxMessageSizeInBytes()` `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` kan mislukken met deze foutcode, wat aangeeft dat er een fout is opgetreden bij het verzenden van het bericht vanwege onvoldoende bandbreedte.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` kan mislukken met deze foutcode, wat aangeeft dat er een fout is opgetreden bij het verzenden van het bericht vanwege het algehele gebruik van het gegevenskanaal dat niet voldoet aan de regels voor de verkeerslimiet. Raadpleeg het Data Channel Concept-document voor meer informatie over de verkeerslimiet.

Methoden

Gegevenskanaalfunctie inschakelen

Haal het doorlopende aanroepobject op dat is ingesteld tijdens de vereiste stappen.
Haal het datakanaalfunctieobject op.

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

Gegevensbericht ontvangen

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

Registreer de receiverCreatedListener.

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

Definieer de 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
    }
};

Definieer de ReceiverClosedListener.

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

Registreer de messageReceivedListener en receiverClosedListener.

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

Gegevensbericht verzenden

Configureer de 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);

De DataChannelSender ophalen en het gegevensbericht verzenden

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

Belangrijk

Houd er rekening mee dat de huidige API voor gegevenskanaalfuncties geen ondersteuning biedt voor directe berichten tussen een webbrowser en een systeemeigen app in een peer-to-peer-oproepscenario.

Overzicht

Vereisten

Raadpleeg de quickstart voor spraakoproepen om een voorbeeld-app in te stellen met spraakoproepen.

Klassen

Name	Beschrijving
DataChannelCallFeature	Wordt gebruikt om de functie voor het gegevenskanaal te starten en te beheren.
DataChannelSender	Wordt gebruikt voor het beheren van een gegevenskanaal als afzender en het verzenden van gegevens.
DataChannelReceiver	Wordt gebruikt voor het beheren van een gegevenskanaal als ontvanger en het ontvangen van gegevens.
DataChannelSenderOptions	Wordt gebruikt voor het weergeven van opties voor het maken van een afzender van een gegevenskanaal.

Enums

Name	Beschrijving
DataChannelPriority	Beschrijft de prioriteitsopties van het gegevenskanaal. Waarden: { `normal`, `high` }.
Betrouwbaarheid van DataChannel	Beschrijft de betrouwbaarheidsopties van het gegevenskanaal. Waarden: { `lossy`, `durable` }.

Foutcode

Name	Beschrijving
dataChannelFailedToStart	`getDataChannelSender()` kan mislukken met deze foutcode, wat aangeeft dat het onderliggende gegevenskanaal niet gereed is om te worden gebruikt.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` kan mislukken met deze foutcode, waarmee wordt aangegeven dat alle beschikbare willekeurige kanaal-id's al zijn gebruikt.
dataChannelSenderClosed	`sendMessage()` kan mislukken met deze foutcode, waarmee wordt aangegeven dat de afzender al eerder is gesloten.
dataChannelMessageSizeOverLimit	`sendMessage()` kan mislukken met deze foutcode, wat aangeeft dat de gegevensgrootte van het bericht groter is dan de limiet. U kunt de limiet voor de berichtgrootte ophalen met behulp van `maxMessageSizeInBytes` `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` kan mislukken met deze foutcode, wat aangeeft dat er een fout is opgetreden bij het verzenden van het bericht vanwege onvoldoende bandbreedte.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` kan mislukken met deze foutcode, wat aangeeft dat er een fout is opgetreden bij het verzenden van het bericht vanwege het algehele gebruik van het gegevenskanaal dat niet voldoet aan de regels voor de verkeerslimiet. Raadpleeg het Data Channel Concept-document voor meer informatie over de verkeerslimiet.

Methoden

Gegevenskanaalfunctie inschakelen

Haal het doorlopende aanroepobject op dat is ingesteld tijdens de vereiste stappen.
Haal het datakanaalfunctieobject op.

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

Gegevensbericht ontvangen

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

Gegevensbericht verzenden

Configureer de 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

De DataChannelSender definiëren en het gegevensbericht verzenden

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)

Belangrijk

Houd er rekening mee dat de huidige API voor gegevenskanaalfuncties geen ondersteuning biedt voor directe berichten tussen een webbrowser en een systeemeigen app in een peer-to-peer-oproepscenario.

Overzicht

Vereisten

Raadpleeg de quickstart voor spraakoproepen om een voorbeeld-app in te stellen met spraakoproepen.

Klassen

Name	Beschrijving
DataChannelCallFeature	Wordt gebruikt om de functie voor het gegevenskanaal te starten en te beheren.
DataChannelSender	Wordt gebruikt voor het beheren van een gegevenskanaal als afzender en het verzenden van gegevens.
DataChannelReceiver	Wordt gebruikt voor het beheren van een gegevenskanaal als ontvanger en het ontvangen van gegevens.
DataChannelSenderOptions	Wordt gebruikt voor het weergeven van opties voor het maken van een afzender van een gegevenskanaal.

Enums

Name	Beschrijving
DataChannelPriority	Beschrijft de prioriteitsopties van het gegevenskanaal. Waarden: { `Normal`, `High` }.
Betrouwbaarheid van DataChannel	Beschrijft de betrouwbaarheidsopties van het gegevenskanaal. Waarden: { `Lossy`, `Durable` }.

Foutcode

Name	Beschrijving
DataChannelFailedToStart	`GetDataChannelSender()` kan mislukken met deze foutcode, wat aangeeft dat het onderliggende gegevenskanaal niet gereed is om te worden gebruikt.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` kan mislukken met deze foutcode, waarmee wordt aangegeven dat alle beschikbare willekeurige kanaal-id's al zijn gebruikt.
DataChannelSenderClosed	`SendMessage()` kan mislukken met deze foutcode, waarmee wordt aangegeven dat de afzender al eerder is gesloten.
DataChannelMessageSizeOverLimit	`SendMessage()` kan mislukken met deze foutcode, wat aangeeft dat de gegevensgrootte van het bericht groter is dan de limiet. U kunt de limiet voor de berichtgrootte ophalen met behulp van `MaxMessageSizeInBytes` `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` kan mislukken met deze foutcode, wat aangeeft dat er een fout is opgetreden bij het verzenden van het bericht vanwege onvoldoende bandbreedte.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` kan mislukken met deze foutcode, wat aangeeft dat er een fout is opgetreden bij het verzenden van het bericht vanwege het algehele gebruik van het gegevenskanaal dat niet voldoet aan de regels voor de verkeerslimiet. Raadpleeg het Data Channel Concept-document voor meer informatie over de verkeerslimiet.

Methoden

Gegevenskanaalfunctie inschakelen

Haal het doorlopende aanroepobject op dat is ingesteld tijdens de vereiste stappen.
Haal het datakanaalfunctieobject op.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Gegevensbericht ontvangen

Definieer de DataChannelReceiverCreated-gebeurtenis-handler.

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

Koppel de DataChannelReceiverCreatedHandler.

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Definieer de MessageReceived-gebeurtenis-handler.

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
}

Definieer de gesloten gebeurtenis-handler.

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

Koppel de MessageReceivedHandler en ReceiverClosedHandler.

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

Gegevensbericht verzenden

Configureer de 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();

De DataChannelSender definiëren en het gegevensbericht verzenden

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

Volgende stappen

Raadpleeg voor meer informatie de volgende artikelen:

Meer informatie over het conceptdocument voor data channel-functies
Meer informatie over de mogelijkheden van calling-SDK

Delen via

Quickstart: Data Channel Messaging toevoegen aan uw aanroepende app

Een DataChannelSender-object maken

Een listener registreren om het DataChannelReceiver-object te verkrijgen

MessageReady verwerken en gebeurtenis van DataChannelReceiver-object sluiten

Deelnemers instellen

Berichten verzenden en ontvangen

Overzicht

Vereisten

Klassen

Enums

Foutcode

Methoden

Gegevenskanaalfunctie inschakelen

Gegevensbericht ontvangen

Gegevensbericht verzenden

Overzicht

Vereisten

Klassen

Enums

Foutcode

Methoden

Gegevenskanaalfunctie inschakelen

Gegevensbericht ontvangen

Gegevensbericht verzenden

Overzicht

Vereisten

Klassen

Enums

Foutcode

Methoden

Gegevenskanaalfunctie inschakelen

Gegevensbericht ontvangen

Gegevensbericht verzenden

Volgende stappen

Feedback

Aanvullende resources