Rychlý start: Přidání zasílání zpráv datového kanálu do volající aplikace

Rozhraní API funkce datového kanálu umožňuje zasílání zpráv v reálném čase během hlasových hovorů a videohovorů. V této úvodní příručce si ukážeme, jak integrovat funkci datového kanálu a umožnit výměnu textových zpráv mezi účastníky během skupinového hovoru. Upozorňujeme, že existuje mnoho různých řešení pro zasílání zpráv kromě funkce Datový kanál a měli byste zvolit vhodné řešení pro váš konkrétní scénář použití.

Důležité

Mějte na paměti, že naše aktuální implementace rozhraní API funkce DataChannel nepodporuje přímé zasílání zpráv mezi webovým prohlížečem a nativní aplikací ve scénáři volání peer-to-peer.

Vytvoření objektu DataChannelSender

Nejprve musíte vytvořit objekt DataChannelSender pro odesílání zpráv. V této vlastní aplikaci pro zasílání zpráv doporučujeme přiřadit číslo channelId, které slouží k rozlišení různých případů použití aplikace. Můžete například přiřadit channelId 1000 pro vlastní zprávy.

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

Existuje několik dalších možností, jako je spolehlivost, šířka pásma a priorita. Prozatím je můžete ignorovat a použít výchozí hodnoty. Během vytváření objektu odesílatele stále potřebujete objekt příjemce pro příjem zpráv.

Registrace naslouchacího procesu pro získání objektu DataChannelReceiver

Pokud chcete získat objekt příjemce, musíte zaregistrovat naslouchací dataChannelReceiverCreated proces, který zachycuje událost. Při vytvoření objektu příjemce sada SDK vygeneruje událost spolu s objektem příjemce.

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

V rámci funkce zpětného volání naslouchacího procesu můžete získat přístup k objektu příjemce a načíst informace, jako channelId je a ID senderParticipantIdentifierúčastníka odesílatele . Je vaší zodpovědností udržovat odkaz na objekt příjemce, protože sada SDK generuje událost jednou pro každý vytvořený objekt příjemce.

Zpracování zprávyReady a zavření události Objektu DataChannelReceiver

Při příchodu zprávy obdrží objekt DataChannelReceiver zprávu, uloží ji do vnitřní vyrovnávací paměti a vygeneruje messageReady událost. Není nutné registrovat messageReady naslouchací proces událostí pro příjem zpráv, protože rozhraní API můžete kdykoli volat readMessage . Pro osvědčený postup však doporučujeme přečíst zprávu v zpětném volání naslouchacího messageReady procesu, pokud zpracování zpráv trvá dlouhou dobu, můžete práci přesměrovat na webový pracovní proces, aby se zabránilo blokování příjmu zpráv.

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

Nastavení účastníků

Pokud chcete určit příjemce vašich zpráv, můžete použít DataChannelSender.setParticipants rozhraní API. Objekt odesílatele udržuje seznam posledních účastníků, který zadáte. Typ účastníka je CommunicationIdentifier, který lze získat od remoteParticipant.identifier. Další informace najdete ve vlastnostech vzdáleného účastníka aplikace Access.

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

Upozorňujeme, že seznam účastníků je omezen na 64 účastníků. Pokud je seznam účastníků prázdným polem, sada SDK odešle zprávu všem účastníkům hovoru.

Odesílání a příjem zpráv

Rozhraní API funkce DataChannel vyžaduje předání dat jako Uint8Array typu. Pomocí rozhraní API nemůžete přímo odeslat řetězec sendMessage JavaScriptu. Pokud například chcete odeslat řetězec abc, nemůžete použít sender.sendMessage('abc'). Místo toho je potřeba nejprve serializovat data do vyrovnávací paměti bajtů.

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

Tady je další příklad odeslání objektu JSON.

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

Příjem a dekódování zprávy

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

Kompletní ukázku najdete na následujícím odkazu: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Důležité

Mějte na paměti, že aktuální rozhraní API funkce datového kanálu nepodporuje přímé zasílání zpráv mezi webovým prohlížečem a nativní aplikací ve scénáři volání mezi dvěma účastníky.

Přehled

Rozhraní API pro funkci datového kanálu umožňuje zasílání zpráv v reálném čase během hlasových hovorů a videohovorů. V této úvodní příručce si ukážeme, jak integrovat funkci datového kanálu do volání a pomocí rozhraní API datového kanálu odesílat a přijímat datové zprávy prostřednictvím datového kanálu.

Požadavky

Informace o nastavení ukázkové aplikace s hlasovým voláním najdete v rychlém startu hlasového volání.

Třídy

Název	Popis
DataChannelCallFeature	Používá se ke spuštění a správě funkce datového kanálu.
DataChannelSender	Slouží ke správě datového kanálu jako odesílatele a odesílání dat.
DataChannelReceiver	Slouží ke správě datového kanálu jako příjemce a příjmu dat.
DataChannelSenderOptions	Slouží k reprezentaci možností pro vytvoření odesílatele datového kanálu.

Výčty

Název	Popis
DataChannelPriority	Popisuje možnosti priority datového kanálu. Hodnoty: { NORMAL, HIGH }.
DataChannelReliability	Popisuje možnosti spolehlivosti datového kanálu. Hodnoty: { LOSSY, DURABLE }.

Kód chyby

Název	Popis
DATA_CHANNEL_FAILED_TO_START	getDataChannelSender() může selhat s tímto kódem chyby, což znamená, že podkladový datový kanál není připravený k použití.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	getDataChannelSender() může selhat s tímto kódem chyby, což znamená, že všechna dostupná ID náhodných kanálů už byla použita.
DATA_CHANNEL_SENDER_CLOSED	sendMessage() může selhat s tímto kódem chyby, což znamená, že odesílatel již byl dříve zavřený.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	sendMessage() může selhat s tímto kódem chyby, což značí, že velikost dat zprávy překračuje limit. Limit velikosti zprávy můžete získat pomocí funkce getMaxMessageSizeInBytes() DataChannelSender.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	sendMessage() může selhat s tímto kódem chyby, což značí selhání při odesílání zprávy kvůli nedostatečné šířce pásma.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	sendMessage() může selhat s tímto kódem chyby, což značí selhání při odesílání zprávy kvůli celkovému využití datového kanálu, který není v souladu s pravidly omezení provozu. Podrobnosti o limitu provozu najdete v dokumentu konceptů datového kanálu.

Metody

Povolení funkce datového kanálu

1. Získejte probíhající objekt volání vytvořený během požadovaných kroků.
2. Získejte objekt funkce datového kanálu.

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

Příjem zprávy o datech

1. Definujte 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. Zaregistrujte .receiverCreatedListener

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

3. Definujte 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. Definujte ReceiverClosedListener.

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

5. Zaregistrujte a messageReceivedListener receiverClosedListener.

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

Odesílání datových zpráv

1. Nakonfigurujte 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. Získání DataChannelSenderu a odeslání datové zprávy

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

Důležité

Mějte na paměti, že aktuální rozhraní API funkce datového kanálu nepodporuje přímé zasílání zpráv mezi webovým prohlížečem a nativní aplikací ve scénáři volání mezi dvěma účastníky.

Přehled

Rozhraní API pro funkci datového kanálu umožňuje zasílání zpráv v reálném čase během hlasových hovorů a videohovorů. V této úvodní příručce si ukážeme, jak integrovat funkci datového kanálu do volání a pomocí rozhraní API datového kanálu odesílat a přijímat datové zprávy prostřednictvím datového kanálu.

Požadavky

Informace o nastavení ukázkové aplikace s hlasovým voláním najdete v rychlém startu hlasového volání.

Třídy

Název	Popis
DataChannelCallFeature	Používá se ke spuštění a správě funkce datového kanálu.
DataChannelSender	Slouží ke správě datového kanálu jako odesílatele a odesílání dat.
DataChannelReceiver	Slouží ke správě datového kanálu jako příjemce a příjmu dat.
DataChannelSenderOptions	Slouží k reprezentaci možností pro vytvoření odesílatele datového kanálu.

Výčty

Název	Popis
DataChannelPriority	Popisuje možnosti priority datového kanálu. Hodnoty: { normal, high }.
DataChannelReliability	Popisuje možnosti spolehlivosti datového kanálu. Hodnoty: { lossy, durable }.

Kód chyby

Název	Popis
dataChannelFailedToStart	getDataChannelSender() může selhat s tímto kódem chyby, což znamená, že podkladový datový kanál není připravený k použití.
dataChannelRandomIdNotAvailable	getDataChannelSender() může selhat s tímto kódem chyby, což znamená, že všechna dostupná ID náhodných kanálů už byla použita.
dataChannelSenderClosed	sendMessage() může selhat s tímto kódem chyby, což znamená, že odesílatel již byl dříve zavřený.
dataChannelMessageSizeOverLimit	sendMessage() může selhat s tímto kódem chyby, což značí, že velikost dat zprávy překračuje limit. Limit velikosti zprávy můžete získat pomocí funkce maxMessageSizeInBytes DataChannelSender.
dataChannelMessageFailureForBandwidth	sendMessage() může selhat s tímto kódem chyby, což značí selhání při odesílání zprávy kvůli nedostatečné šířce pásma.
dataChannelMessageFailureForTrafficLimit	sendMessage() může selhat s tímto kódem chyby, což značí selhání při odesílání zprávy kvůli celkovému využití datového kanálu, který není v souladu s pravidly omezení provozu. Podrobnosti o limitu provozu najdete v dokumentu konceptů datového kanálu.

Metody

Povolení funkce datového kanálu

1. Získejte probíhající objekt volání vytvořený během požadovaných kroků.
2. Získejte objekt funkce datového kanálu.

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

Příjem zprávy o datech

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

Odesílání datových zpráv

1. Nakonfigurujte 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. Definování DataChannelSender a odeslání datové zprávy

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)

Důležité

Mějte na paměti, že aktuální rozhraní API funkce datového kanálu nepodporuje přímé zasílání zpráv mezi webovým prohlížečem a nativní aplikací ve scénáři volání mezi dvěma účastníky.

Přehled

Rozhraní API pro funkci datového kanálu umožňuje zasílání zpráv v reálném čase během hlasových hovorů a videohovorů. V této úvodní příručce si ukážeme, jak integrovat funkci datového kanálu do volání a pomocí rozhraní API datového kanálu odesílat a přijímat datové zprávy prostřednictvím datového kanálu.

Požadavky

Informace o nastavení ukázkové aplikace s hlasovým voláním najdete v rychlém startu hlasového volání.

Třídy

Název	Popis
DataChannelCallFeature	Používá se ke spuštění a správě funkce datového kanálu.
DataChannelSender	Slouží ke správě datového kanálu jako odesílatele a odesílání dat.
DataChannelReceiver	Slouží ke správě datového kanálu jako příjemce a příjmu dat.
DataChannelSenderOptions	Slouží k reprezentaci možností pro vytvoření odesílatele datového kanálu.

Výčty

Název	Popis
DataChannelPriority	Popisuje možnosti priority datového kanálu. Hodnoty: { Normal, High }.
DataChannelReliability	Popisuje možnosti spolehlivosti datového kanálu. Hodnoty: { Lossy, Durable }.

Kód chyby

Název	Popis
DataChannelFailedToStart	GetDataChannelSender() může selhat s tímto kódem chyby, což znamená, že podkladový datový kanál není připravený k použití.
DataChannelRandomIdNotAvailable	GetDataChannelSender() může selhat s tímto kódem chyby, což znamená, že všechna dostupná ID náhodných kanálů už byla použita.
DataChannelSenderClosed	SendMessage() může selhat s tímto kódem chyby, což znamená, že odesílatel již byl dříve zavřený.
DataChannelMessageSizeOverLimit	SendMessage() může selhat s tímto kódem chyby, což značí, že velikost dat zprávy překračuje limit. Limit velikosti zprávy můžete získat pomocí funkce MaxMessageSizeInBytes DataChannelSender.
DataChannelMessageFailureForBandwidth	SendMessage() může selhat s tímto kódem chyby, což značí selhání při odesílání zprávy kvůli nedostatečné šířce pásma.
DataChannelMessageFailureForTrafficLimit	SendMessage() může selhat s tímto kódem chyby, což značí selhání při odesílání zprávy kvůli celkovému využití datového kanálu, který není v souladu s pravidly omezení provozu. Podrobnosti o limitu provozu najdete v dokumentu konceptů datového kanálu.

Metody

Povolení funkce datového kanálu

1. Získejte probíhající objekt volání vytvořený během požadovaných kroků.
2. Získejte objekt funkce datového kanálu.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Příjem zprávy o datech

1. Definujte obslužnou rutinu události 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. Připojte .DataChannelReceiverCreatedHandler

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

3. Definujte obslužnou rutinu události 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. Definujte obslužnou rutinu uzavřené události.

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

5. Připojte a MessageReceivedHandler ReceiverClosedHandler.

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

Odesílání datových zpráv

1. Nakonfigurujte 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. Definování DataChannelSender a odeslání datové zprávy

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

Další kroky

Další informace najdete v následujících článcích:

• Informace o konceptu funkce datového kanálu
• Další informace o možnostech volání sady SDK