Snabbstart: Lägga till datakanalmeddelanden i din samtalsapp

Artikel
08/06/2024

Funktions-API:et för Data Channel möjliggör realtidsmeddelanden under ljud- och videosamtal. I den här snabbstartsguiden visar vi hur du integrerar datakanalfunktionen, vilket möjliggör utbyte av textmeddelanden mellan deltagare i ett gruppsamtal. Observera att det finns många andra meddelandelösningar än datakanalfunktionen, och du bör välja lämplig lösning för ditt specifika användningsscenario.

Viktigt!

Tänk på att vår aktuella implementering av DataChannel-funktions-API:et inte stöder direktmeddelanden mellan en webbläsare och en inbyggd app i ett peer-to-peer-anropsscenario.

Skapa ett DataChannelSender-objekt

Först måste du skapa ett DataChannelSender-objekt för att skicka meddelanden. I det här anpassade meddelandeprogrammet föreslår vi att du tilldelar ett tal till channelId, som tjänar till att skilja mellan olika användningsfall för program. Du kan till exempel tilldela channelId 1 000 för anpassade meddelanden.

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

Det finns flera andra alternativ, till exempel tillförlitlighet, bandbredd och prioritet. Du kan ignorera dessa för tillfället och använda standardvärdena. När avsändarobjektet har skapats behöver du fortfarande ett mottagarobjekt för att ta emot meddelanden.

Registrera en lyssnare för att hämta DataChannelReceiver-objektet

Om du vill hämta ett mottagarobjekt måste du registrera en lyssnare som registrerar dataChannelReceiverCreated händelsen. När ett mottagarobjekt skapas genererar SDK-filen händelsen tillsammans med mottagarobjektet.

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

I funktionen för återanrop till lyssnaren kan du komma åt mottagarobjektet och hämta information som channelId och avsändarens deltagar-ID senderParticipantIdentifier. Det är ditt ansvar att underhålla referensen för mottagarobjektet, eftersom SDK genererar händelsen en gång för varje skapat mottagarobjekt.

Hantera messageReady och stäng händelse för DataChannelReceiver-objekt

När ett meddelande tas emot tar DataChannelReceiver-objektet emot meddelandet, lagrar det i sin interna buffert och genererar en messageReady händelse. Det är inte nödvändigt att registrera messageReady händelselyssnare för att ta emot meddelanden, eftersom du alltid kan anropa API:et readMessage när som helst. För bästa praxis rekommenderar vi dock att du läser meddelandet i lyssnarens messageReady återanrop. Om meddelandebearbetningen tar lång tid kan du avlasta arbetet till en webbarbetare för att förhindra att meddelandets mottagning blockeras.

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

Ange deltagare

Om du vill ange mottagarna för dina meddelanden kan du använda DataChannelSender.setParticipants API:et. Avsändarobjektet har den senaste deltagarlistan som du anger. Deltagartypen är CommunicationIdentifier, som du kan hämta från remoteParticipant.identifier. Mer information finns i Åtkomst till egenskaper för fjärrdeltagare.

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

Observera att deltagarlistan är begränsad till 64 deltagare. Om deltagarlistan är en tom matris sänder SDK meddelandet till alla deltagare i anropet.

Skicka och ta emot meddelanden

DataChannel-funktions-API kräver att du skickar data som Uint8Array typ. Du kan inte skicka en JavaScript-sträng direkt med hjälp av sendMessage API: et. Om du till exempel vill skicka en sträng abckan du inte använda sender.sendMessage('abc'). I stället måste du serialisera data till en bytebuffert först.

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

Här är ett annat exempel för att skicka ett JSON-objekt.

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

Ta emot och avkoda meddelandet

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

Du hittar ett fullständigt exempel på följande länk: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Viktigt!

Tänk på att det aktuella funktions-API:et för Data Channel inte stöder direktmeddelanden mellan en webbläsare och en inbyggd app i ett peer-to-peer-samtalsscenario.

Översikt

Funktions-API:et för Data Channel möjliggör datameddelanden i realtid under ljud- och videosamtal. I den här snabbstartsguiden visar vi hur du integrerar datakanalfunktionen i ditt anrop och använder API:erna för datakanalen för att skicka och ta emot datameddelanden via en datakanal.

Förutsättningar

Gå till snabbstarten för röstsamtal för att konfigurera en exempelapp med röstsamtal.

Klasser

Name	beskrivning
DataChannelCallFeature	Används för att starta och hantera datakanalfunktionen.
DataChannelSender	Används för att hantera en datakanal som avsändare och skicka data.
DataChannelReceiver	Används för att hantera en datakanal som mottagare och ta emot data.
DataChannelSenderOptions	Används för att representera alternativ för att skapa en datakanalssändare.

Uppräkningar

Name	beskrivning
DataChannelPriority	Beskriver prioritetsalternativen för datakanalen. Värden: { `NORMAL`, `HIGH` }.
DataChannelReliability	Beskriver tillförlitlighetsalternativen för datakanalen. Värden: { `LOSSY`, `DURABLE` }.

Felkod

Name	beskrivning
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` kan misslyckas med den här felkoden, vilket indikerar att den underliggande datakanalen inte är redo att användas.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` kan misslyckas med den här felkoden, vilket indikerar att alla tillgängliga slumpmässiga kanal-ID:er redan har använts.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar att avsändaren redan har stängts tidigare.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar att meddelandedatastorleken överskrider gränsen. Du kan hämta storleksgränsen för meddelanden med hjälp av `getMaxMessageSizeInBytes()` i `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar ett fel i att skicka meddelandet på grund av otillräcklig bandbredd.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar ett fel i att skicka meddelandet på grund av att den totala användningen av Data Channel inte överensstämmer med trafikgränsreglerna. Mer information om trafikgränsen finns i konceptdokumentet för Data Channel.

Metoder

Aktivera funktionen DataKanal

Hämta det pågående anropsobjektet som upprättades under de nödvändiga stegen.
Hämta datakanalens funktionsobjekt.

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

Ta emot datameddelande

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

receiverCreatedListenerRegistrera .

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

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

Definiera ReceiverClosedListener.

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

messageReceivedListener Registrera och receiverClosedListener.

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

Skicka datameddelande

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

Hämta DataChannelSender och skicka datameddelande

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

Viktigt!

Tänk på att det aktuella funktions-API:et för Data Channel inte stöder direktmeddelanden mellan en webbläsare och en inbyggd app i ett peer-to-peer-samtalsscenario.

Översikt

Förutsättningar

Gå till snabbstarten för röstsamtal för att konfigurera en exempelapp med röstsamtal.

Klasser

Name	beskrivning
DataChannelCallFeature	Används för att starta och hantera datakanalfunktionen.
DataChannelSender	Används för att hantera en datakanal som avsändare och skicka data.
DataChannelReceiver	Används för att hantera en datakanal som mottagare och ta emot data.
DataChannelSenderOptions	Används för att representera alternativ för att skapa en datakanalssändare.

Uppräkningar

Name	beskrivning
DataChannelPriority	Beskriver prioritetsalternativen för datakanalen. Värden: { `normal`, `high` }.
DataChannelReliability	Beskriver tillförlitlighetsalternativen för datakanalen. Värden: { `lossy`, `durable` }.

Felkod

Name	beskrivning
dataChannelFailedToStart	`getDataChannelSender()` kan misslyckas med den här felkoden, vilket indikerar att den underliggande datakanalen inte är redo att användas.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` kan misslyckas med den här felkoden, vilket indikerar att alla tillgängliga slumpmässiga kanal-ID:er redan har använts.
dataChannelSenderClosed	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar att avsändaren redan har stängts tidigare.
dataChannelMessageSizeOverLimit	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar att meddelandedatastorleken överskrider gränsen. Du kan hämta storleksgränsen för meddelanden med hjälp av `maxMessageSizeInBytes` i `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar ett fel i att skicka meddelandet på grund av otillräcklig bandbredd.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` kan misslyckas med den här felkoden, vilket indikerar ett fel i att skicka meddelandet på grund av att den totala användningen av Data Channel inte överensstämmer med trafikgränsreglerna. Mer information om trafikgränsen finns i konceptdokumentet för Data Channel.

Metoder

Aktivera funktionen DataKanal

Hämta det pågående anropsobjektet som upprättades under de nödvändiga stegen.
Hämta datakanalens funktionsobjekt.

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

Ta emot datameddelande

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

Skicka datameddelande

Konfigurera 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

Definiera DataChannelSender och skicka datameddelande

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)

Viktigt!

Tänk på att det aktuella funktions-API:et för Data Channel inte stöder direktmeddelanden mellan en webbläsare och en inbyggd app i ett peer-to-peer-samtalsscenario.

Översikt

Förutsättningar

Gå till snabbstarten för röstsamtal för att konfigurera en exempelapp med röstsamtal.

Klasser

Name	beskrivning
DataChannelCallFeature	Används för att starta och hantera datakanalfunktionen.
DataChannelSender	Används för att hantera en datakanal som avsändare och skicka data.
DataChannelReceiver	Används för att hantera en datakanal som mottagare och ta emot data.
DataChannelSenderOptions	Används för att representera alternativ för att skapa en datakanalssändare.

Uppräkningar

Name	beskrivning
DataChannelPriority	Beskriver prioritetsalternativen för datakanalen. Värden: { `Normal`, `High` }.
DataChannelReliability	Beskriver tillförlitlighetsalternativen för datakanalen. Värden: { `Lossy`, `Durable` }.

Felkod

Name	beskrivning
DataChannelFailedToStart	`GetDataChannelSender()` kan misslyckas med den här felkoden, vilket indikerar att den underliggande datakanalen inte är redo att användas.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` kan misslyckas med den här felkoden, vilket indikerar att alla tillgängliga slumpmässiga kanal-ID:er redan har använts.
DataChannelSenderClosed	`SendMessage()` kan misslyckas med den här felkoden, vilket indikerar att avsändaren redan har stängts tidigare.
DataChannelMessageSizeOverLimit	`SendMessage()` kan misslyckas med den här felkoden, vilket indikerar att meddelandedatastorleken överskrider gränsen. Du kan hämta storleksgränsen för meddelanden med hjälp av `MaxMessageSizeInBytes` i `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` kan misslyckas med den här felkoden, vilket indikerar ett fel i att skicka meddelandet på grund av otillräcklig bandbredd.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` kan misslyckas med den här felkoden, vilket indikerar ett fel i att skicka meddelandet på grund av att den totala användningen av Data Channel inte överensstämmer med trafikgränsreglerna. Mer information om trafikgränsen finns i konceptdokumentet för Data Channel.

Metoder

Aktivera funktionen DataKanal

Hämta det pågående anropsobjektet som upprättades under de nödvändiga stegen.
Hämta datakanalens funktionsobjekt.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Ta emot datameddelande

Definiera DataChannelReceiverSkapad händelsehanterare.

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

DataChannelReceiverCreatedHandlerBifoga .

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Definiera händelsehanteraren 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
}

Definiera händelsehanteraren Stängd.

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

MessageReceivedHandler Bifoga och ReceiverClosedHandler.

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

Skicka datameddelande

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

Definiera DataChannelSender och skicka datameddelande

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ästa steg

Mer information finns i följande artiklar:

Lär dig mer om dokument för funktionskoncept för Data Channel
Läs mer om funktioner för samtals-SDK

Dela via

Snabbstart: Lägga till datakanalmeddelanden i din samtalsapp

Skapa ett DataChannelSender-objekt

Registrera en lyssnare för att hämta DataChannelReceiver-objektet

Hantera messageReady och stäng händelse för DataChannelReceiver-objekt

Ange deltagare

Skicka och ta emot meddelanden

Översikt

Förutsättningar

Klasser

Uppräkningar

Felkod

Metoder

Aktivera funktionen DataKanal

Ta emot datameddelande

Skicka datameddelande

Översikt

Förutsättningar

Klasser

Uppräkningar

Felkod

Metoder

Aktivera funktionen DataKanal

Ta emot datameddelande

Skicka datameddelande

Översikt

Förutsättningar

Klasser

Uppräkningar

Felkod

Metoder

Aktivera funktionen DataKanal

Ta emot datameddelande

Skicka datameddelande

Nästa steg

Feedback

Ytterligare resurser