Mulai cepat: Menambahkan pesan Saluran Data ke aplikasi panggilan Anda

Artikel
08/06/2024

API fitur Saluran Data memungkinkan olahpesan real time selama panggilan audio dan video. Dalam panduan mulai cepat ini, kami akan mengilustrasikan cara mengintegrasikan fitur Saluran Data, memungkinkan pertukaran pesan teks di antara peserta dalam panggilan grup. Harap dicatat bahwa ada banyak solusi olahpesan yang berbeda selain fitur Saluran Data, dan Anda harus memilih solusi yang sesuai untuk skenario penggunaan spesifik Anda.

Penting

Perlu diketahui bahwa implementasi API fitur DataChannel kami saat ini tidak mendukung olahpesan langsung antara browser web dan aplikasi asli dalam skenario panggilan peer-to-peer.

Membuat objek DataChannelSender

Pertama, Anda perlu membuat objek DataChannelSender untuk mengirim pesan. Dalam aplikasi olahpesan kustom ini, sebaiknya tetapkan angka ke channelId, yang berfungsi untuk membedakan kasus penggunaan aplikasi yang berbeda. Misalnya, Anda dapat menetapkan channelId 1000 untuk pesan kustom.

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

Ada beberapa opsi lain, seperti keandalan, bandwidth, dan prioritas. Anda dapat mengabaikan ini untuk saat ini dan menggunakan nilai default. Saat objek pengirim dibuat, Anda masih memerlukan objek penerima untuk menerima pesan.

Mendaftarkan pendengar untuk mendapatkan objek DataChannelReceiver

Untuk memperoleh objek penerima, Anda perlu mendaftarkan pendengar yang mengambil dataChannelReceiverCreated peristiwa. Saat objek penerima dibuat, SDK memancarkan peristiwa bersama dengan objek penerima.

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

Dalam fungsi panggilan balik pendengar, Anda dapat mengakses objek penerima dan mengambil informasi seperti channelId dan ID senderParticipantIdentifierpeserta pengirim . Anda bertanggung jawab untuk mempertahankan referensi objek penerima, karena SDK memancarkan peristiwa sekali untuk setiap objek penerima yang dibuat.

Menangani messageReady dan menutup peristiwa objek DataChannelReceiver

Ketika pesan tiba, objek DataChannelReceiver menerima pesan, menyimpannya di buffer internalnya, dan memancarkan messageReady peristiwa. Tidak perlu mendaftarkan messageReady pendengar peristiwa untuk menerima pesan, karena Anda selalu dapat memanggil readMessage API kapan saja. Namun, untuk praktik terbaik, sebaiknya baca pesan dalam messageReady panggilan balik pendengar, jika pemrosesan pesan membutuhkan waktu lama, Anda dapat membongkar pekerjaan ke Pekerja Web untuk mencegah pemblokiran penerimaan pesan.

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

Mengatur peserta

Untuk menentukan penerima pesan, Anda dapat menggunakan DataChannelSender.setParticipants API. Objek pengirim mempertahankan daftar peserta terbaru yang Anda sediakan. Jenis peserta adalah CommunicationIdentifier, yang dapat Anda peroleh dari remoteParticipant.identifier. Untuk informasi selengkapnya, lihat Mengakses properti peserta jarak jauh.

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

Harap dicatat bahwa daftar peserta dibatasi hingga 64 peserta. Jika daftar peserta adalah array kosong, SDK menyiarkan pesan ke semua peserta dalam panggilan.

Mengirim dan menerima pesan

API fitur DataChannel mengharuskan Anda meneruskan data sebagai Uint8Array jenis. Anda tidak dapat langsung mengirim string JavaScript menggunakan sendMessage API. Misalnya, jika Anda ingin mengirim string abc, Anda tidak dapat menggunakan sender.sendMessage('abc'). Sebagai gantinya, Anda perlu menserialisasikan data ke buffer byte terlebih dahulu.

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

Berikut adalah contoh lain untuk mengirim objek JSON.

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

Menerima dan mendekode pesan

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

Anda dapat menemukan sampel lengkap di tautan berikut: https://github.com/Azure-Samples/communication-services-web-calling-tutorial

Penting

Perlu diketahui bahwa API fitur Saluran Data saat ini tidak mendukung olahpesan langsung antara browser web dan aplikasi asli dalam skenario panggilan peer-to-peer.

Gambaran Umum

API fitur Saluran Data memungkinkan olahpesan data real time selama panggilan audio dan video. Dalam panduan mulai cepat ini, kami mengilustrasikan cara mengintegrasikan fitur Saluran Data ke panggilan Anda dan menggunakan API Saluran Data untuk mengirim dan menerima pesan data melalui saluran data.

Prasyarat

Lihat Mulai Cepat Panggilan Suara untuk menyiapkan aplikasi sampel dengan panggilan suara.

Kelas

Nama	Deskripsi
DataChannelCallFeature	Digunakan untuk memulai dan mengelola fitur saluran data.
DataChannelSender	Digunakan untuk mengelola saluran data sebagai pengirim dan mengirim data.
DataChannelReceiver	Digunakan untuk mengelola saluran data sebagai penerima dan menerima data.
DataChannelSenderOptions	Digunakan untuk mewakili opsi untuk membuat pengirim saluran data.

Enums

Nama	Deskripsi
DataChannelPriority	Menjelaskan opsi prioritas saluran data. Nilai: { `NORMAL`, `HIGH` }.
DataChannelReliability	Menjelaskan opsi keandalan saluran data. Nilai: { `LOSSY`, `DURABLE` }.

Kode Kesalahan

Nama	Deskripsi
DATA_CHANNEL_FAILED_TO_START	`getDataChannelSender()` dapat gagal dengan kode kesalahan ini, menunjukkan Saluran Data yang mendasar tidak siap digunakan.
DATA_CHANNEL_RANDOM_ID_NOT_AVAILABLE	`getDataChannelSender()` dapat gagal dengan kode kesalahan ini, menunjukkan semua ID saluran acak yang tersedia telah digunakan.
DATA_CHANNEL_SENDER_CLOSED	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan pengirim telah ditutup sebelumnya.
DATA_CHANNEL_MESSAGE_SIZE_OVER_LIMIT	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan ukuran data pesan melebihi batas. Anda bisa mendapatkan batas ukuran pesan menggunakan `getMaxMessageSizeInBytes()` di `DataChannelSender`.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_BANDWIDTH	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan kegagalan dalam mengirim pesan karena bandwidth yang tidak cukup.
DATA_CHANNEL_MESSAGE_FAILURE_FOR_TRAFFIC_LIMIT	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan kegagalan dalam mengirim pesan karena penggunaan Saluran Data secara keseluruhan tidak sesuai dengan aturan batas lalu lintas. Lihat Dokumen Konsep Saluran Data untuk detail batas lalu lintas.

Metode

Mengaktifkan fitur Saluran Data

Dapatkan objek panggilan yang sedang berlangsung yang dibuat selama langkah-langkah prasyarat.
Dapatkan objek Fitur Saluran Data.

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

Menerima pesan data

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

Daftarkan receiverCreatedListener.

dataChannelCallFeature.addOnReceiverCreatedListener(receiverCreatedListener);

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

Tentukan ReceiverClosedListener.

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

Daftarkan messageReceivedListener dan receiverClosedListener.

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

Mengirim pesan data

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

Dapatkan DataChannelSender dan kirim pesan data

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

Penting

Perlu diketahui bahwa API fitur Saluran Data saat ini tidak mendukung olahpesan langsung antara browser web dan aplikasi asli dalam skenario panggilan peer-to-peer.

Gambaran Umum

Prasyarat

Lihat Mulai Cepat Panggilan Suara untuk menyiapkan aplikasi sampel dengan panggilan suara.

Kelas

Nama	Deskripsi
DataChannelCallFeature	Digunakan untuk memulai dan mengelola fitur saluran data.
DataChannelSender	Digunakan untuk mengelola saluran data sebagai pengirim dan mengirim data.
DataChannelReceiver	Digunakan untuk mengelola saluran data sebagai penerima dan menerima data.
DataChannelSenderOptions	Digunakan untuk mewakili opsi untuk membuat pengirim saluran data.

Enums

Nama	Deskripsi
DataChannelPriority	Menjelaskan opsi prioritas saluran data. Nilai: { `normal`, `high` }.
DataChannelReliability	Menjelaskan opsi keandalan saluran data. Nilai: { `lossy`, `durable` }.

Kode Kesalahan

Nama	Deskripsi
dataChannelFailedToStart	`getDataChannelSender()` dapat gagal dengan kode kesalahan ini, menunjukkan Saluran Data yang mendasar tidak siap digunakan.
dataChannelRandomIdNotAvailable	`getDataChannelSender()` dapat gagal dengan kode kesalahan ini, menunjukkan semua ID saluran acak yang tersedia telah digunakan.
dataChannelSenderClosed	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan pengirim telah ditutup sebelumnya.
dataChannelMessageSizeOverLimit	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan ukuran data pesan melebihi batas. Anda bisa mendapatkan batas ukuran pesan menggunakan `maxMessageSizeInBytes` di `DataChannelSender`.
dataChannelMessageFailureForBandwidth	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan kegagalan dalam mengirim pesan karena bandwidth yang tidak cukup.
dataChannelMessageFailureForTrafficLimit	`sendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan kegagalan dalam mengirim pesan karena penggunaan Saluran Data secara keseluruhan tidak sesuai dengan aturan batas lalu lintas. Lihat Dokumen Konsep Saluran Data untuk detail batas lalu lintas.

Metode

Mengaktifkan fitur Saluran Data

Dapatkan objek panggilan yang sedang berlangsung yang dibuat selama langkah-langkah prasyarat.
Dapatkan objek Fitur Saluran Data.

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

Menerima pesan data

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

Mengirim pesan data

Konfigurasikan 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

Tentukan DataChannelSender dan kirim pesan data

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)

Penting

Perlu diketahui bahwa API fitur Saluran Data saat ini tidak mendukung olahpesan langsung antara browser web dan aplikasi asli dalam skenario panggilan peer-to-peer.

Gambaran Umum

Prasyarat

Lihat Mulai Cepat Panggilan Suara untuk menyiapkan aplikasi sampel dengan panggilan suara.

Kelas

Nama	Deskripsi
DataChannelCallFeature	Digunakan untuk memulai dan mengelola fitur saluran data.
DataChannelSender	Digunakan untuk mengelola saluran data sebagai pengirim dan mengirim data.
DataChannelReceiver	Digunakan untuk mengelola saluran data sebagai penerima dan menerima data.
DataChannelSenderOptions	Digunakan untuk mewakili opsi untuk membuat pengirim saluran data.

Enums

Nama	Deskripsi
DataChannelPriority	Menjelaskan opsi prioritas saluran data. Nilai: { `Normal`, `High` }.
DataChannelReliability	Menjelaskan opsi keandalan saluran data. Nilai: { `Lossy`, `Durable` }.

Kode Kesalahan

Nama	Deskripsi
DataChannelFailedToStart	`GetDataChannelSender()` dapat gagal dengan kode kesalahan ini, menunjukkan Saluran Data yang mendasar tidak siap digunakan.
DataChannelRandomIdNotAvailable	`GetDataChannelSender()` dapat gagal dengan kode kesalahan ini, menunjukkan semua ID saluran acak yang tersedia telah digunakan.
DataChannelSenderClosed	`SendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan pengirim telah ditutup sebelumnya.
DataChannelMessageSizeOverLimit	`SendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan ukuran data pesan melebihi batas. Anda bisa mendapatkan batas ukuran pesan menggunakan `MaxMessageSizeInBytes` di `DataChannelSender`.
DataChannelMessageFailureForBandwidth	`SendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan kegagalan dalam mengirim pesan karena bandwidth yang tidak cukup.
DataChannelMessageFailureForTrafficLimit	`SendMessage()` dapat gagal dengan kode kesalahan ini, menunjukkan kegagalan dalam mengirim pesan karena penggunaan Saluran Data secara keseluruhan tidak sesuai dengan aturan batas lalu lintas. Lihat Dokumen Konsep Saluran Data untuk detail batas lalu lintas.

Metode

Mengaktifkan fitur Saluran Data

Dapatkan objek panggilan yang sedang berlangsung yang dibuat selama langkah-langkah prasyarat.
Dapatkan objek Fitur Saluran Data.

DataChannelCallFeature dataChannelCallFeature = call.Features.DataChannel;

Menerima pesan data

Tentukan penanganan aktivitas 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;
}

Lampirkan DataChannelReceiverCreatedHandler.

dataChannelCallFeature.ReceiverCreated += DataChannelReceiverCreatedHandler;

Tentukan penanganan aktivitas 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
}

Tentukan Penanganan aktivitas tertutup.

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

Lampirkan MessageReceivedHandler dan ReceiverClosedHandler.

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

Mengirim pesan data

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

Tentukan DataChannelSender dan kirim pesan data

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

Langkah berikutnya

Untuk informasi lebih lanjut, baca artikel berikut:

Pelajari tentang dokumen konsep fitur Saluran Data
Pelajari selengkapnya tentang Kemampuan Memanggil SDK

Bagikan melalui

Mulai cepat: Menambahkan pesan Saluran Data ke aplikasi panggilan Anda

Membuat objek DataChannelSender

Mendaftarkan pendengar untuk mendapatkan objek DataChannelReceiver

Menangani messageReady dan menutup peristiwa objek DataChannelReceiver

Mengatur peserta

Mengirim dan menerima pesan

Gambaran Umum

Prasyarat

Kelas

Enums

Kode Kesalahan

Metode

Mengaktifkan fitur Saluran Data

Menerima pesan data

Mengirim pesan data

Gambaran Umum

Prasyarat

Kelas

Enums

Kode Kesalahan

Metode

Mengaktifkan fitur Saluran Data

Menerima pesan data

Mengirim pesan data

Gambaran Umum

Prasyarat

Kelas

Enums

Kode Kesalahan

Metode

Mengaktifkan fitur Saluran Data

Menerima pesan data

Mengirim pesan data

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: