ApsaraVideo Real-time Communication (ARTC) Web SDK adalah toolkit yang disediakan oleh Alibaba Cloud untuk mengembangkan aplikasi komunikasi real-time berbasis web. SDK ini memungkinkan Anda mengintegrasikan fitur berkualitas tinggi, seperti panggilan audio/video dan pesan real-time, ke dalam aplikasi web secara cepat. Panduan ini menjelaskan cara membangun aplikasi ARTC pertama Anda dengan cepat.
ApsaraVideo Real-time Communication (ARTC) Web SDK adalah toolkit yang disediakan oleh Alibaba Cloud untuk mengembangkan aplikasi komunikasi real-time berbasis web. SDK ini memungkinkan Anda mengintegrasikan fitur berkualitas tinggi, seperti panggilan audio/video dan pesan real-time, ke dalam aplikasi web secara cepat. Panduan ini menjelaskan cara membangun aplikasi ARTC pertama Anda dengan cepat.
Langkah 1: Buat aplikasi
Masuk ke ApsaraVideo Live console.
Pada panel navigasi kiri, pilih .
Klik Create Application.
Masukkan instance name kustom, centang kotak Terms of Service, lalu klik Create Now.
Setelah muncul pesan sukses, refresh halaman Applications untuk melihat aplikasi ApsaraVideo Real-time Communication baru Anda.
CatatanPembuatan aplikasi tidak dikenai biaya. Anda akan dikenai biaya berdasarkan penggunaan aktual dengan skema pay-as-you-go. Untuk informasi selengkapnya, lihat Billing of audio and video calls.
Langkah 2: Dapatkan Application ID dan AppKey
Setelah membuat aplikasi, temukan aplikasi tersebut di daftar aplikasi. Pada kolom Actions, klik Manage untuk membuka halaman Basic Information. Di halaman ini, temukan Application ID dan AppKey.
Langkah 3: Integrasikan SDK
ARTC Web SDK adalah SDK JavaScript standar yang kompatibel dengan semua framework front-end utama, termasuk Vue 2, Vue 3, dan React. Contoh kode dalam topik ini ditulis dalam JavaScript native. Jika Anda mengembangkan dengan framework seperti Vue 2, Anda harus menyesuaikan contoh JavaScript resmi ke dalam konvensi framework Anda sendiri (misalnya, manajemen lifecycle dan enkapsulasi komponen). Saat ini, kode contoh khusus framework belum tersedia.
Integrasikan SDK.
Script
Dalam halaman HTML Anda, sertakan skrip SDK.
<script src="https://g.alicdn.com/apsara-media-box/imp-web-rtc/7.3.4/aliyun-rtc-sdk.js"></script>NPM
Dalam proyek Anda, jalankan perintah berikut untuk menginstal SDK.
npm install aliyun-rtc-sdk --saveInisialisasi engine.
// Pilih salah satu dari dua metode impor berikut. // Gunakan ini jika Anda mengimpor dari paket npm. import AliRtcEngine from 'aliyun-rtc-sdk'; // Gunakan ini jika Anda menyertakan SDK dengan tag script. const AliRtcEngine = window.AliRtcEngine; // Periksa kompatibilitas browser. const checkResult = await AliRtcEngine.isSupported(); if (!checkResult.support) { // Lingkungan saat ini tidak didukung. Minta pengguna untuk beralih atau memperbarui browser mereka. } // Buat instans engine. Anda dapat menyimpannya sebagai variabel global. const aliRtcEngine = AliRtcEngine.getInstance();Setelah membuat instans AliRtcEngine, dengarkan dan tangani event terkait.
// Dipicu ketika pengguna lokal meninggalkan channel. aliRtcEngine.on('bye', (code) => { // `code` adalah kode alasan. Untuk detailnya, lihat referensi API. console.log(`bye, code=${code}`); // Tangani logika bisnis Anda di sini, misalnya keluar dari halaman panggilan. }); // Dipicu ketika pengguna jarak jauh online. aliRtcEngine.on('remoteUserOnLineNotify', (userId, elapsed) => { console.log(`User ${userId} bergabung ke channel dalam ${elapsed} detik.`); // Tangani logika bisnis Anda di sini, misalnya menampilkan modul UI untuk pengguna ini. }); // Dipicu ketika pengguna jarak jauh offline. aliRtcEngine.on('remoteUserOffLineNotify', (userId, reason) => { // `reason` adalah kode alasan. Untuk detailnya, lihat referensi API. console.log(`User ${userId} meninggalkan channel. Kode alasan: ${reason}`); // Tangani logika bisnis Anda di sini, misalnya menghapus modul UI untuk pengguna ini. }); // Dipicu ketika status langganan aliran jarak jauh berubah. aliRtcEngine.on('videoSubscribeStateChanged', (userId, oldState, newState, interval, channelId) => { // 'oldState' dan 'newState' adalah nilai AliRtcSubscribeState. // Nilai: 0 (diinisialisasi), 1 (tidak berlangganan), 2 (sedang berlangganan), 3 (berlangganan). // `interval` adalah waktu antar perubahan status, dalam milidetik. console.log(`Status langganan pengguna jarak jauh ${userId} di channel ${channelId} berubah dari ${oldState} menjadi ${newState}.`); // Tangani logika untuk melihat aliran jarak jauh di sini. // Ketika `newState` menjadi 3, Anda dapat memutar aliran jarak jauh dengan memanggil setRemoteViewConfig. // Ketika `newState` menjadi 1, Anda dapat menghentikan pemutaran. }); // Dipicu ketika informasi otentikasi kedaluwarsa. aliRtcEngine.on('authInfoExpired', () => { // Callback ini menunjukkan bahwa informasi otentikasi telah kedaluwarsa. // Dapatkan token baru dan data lainnya, lalu panggil metode refreshAuthInfo untuk memperbarui data otentikasi. aliRtcEngine.refreshAuthInfo({ userId, token, timestamp }); }); // Dipicu ketika informasi otentikasi akan segera kedaluwarsa. aliRtcEngine.on('authInfoWillExpire', () => { // Callback ini dipicu 30 detik sebelum kedaluwarsa. Anda harus segera memperbarui informasi otentikasi. // Untuk tetap dalam sesi, dapatkan token baru dan data lainnya, lalu panggil joinChannel untuk bergabung kembali ke channel. });(Opsional) Atur mode channel. Mode default adalah mode communication. Untuk informasi selengkapnya, lihat Set the channel mode and user role.
// Atur mode channel. Nilai valid: 'communication' (mode communication), 'interactive_live' (mode interaktif). aliRtcEngine.setChannelProfile('interactive_live'); // Atur peran pengguna. Metode ini hanya berlaku dalam mode interaktif. // Nilai valid: 'interactive' (streamer, dapat mempublikasikan dan berlangganan aliran), 'live' (penonton, hanya dapat berlangganan aliran). aliRtcEngine.setClientRole('interactive');Bergabung ke channel. Untuk informasi tentang cara menghasilkan token, lihat token-based authentication. Anda dapat memilih untuk bergabung dengan satu parameter atau beberapa parameter sesuai kebutuhan.
Bergabung dengan satu parameter
const userName = 'Test User 1'; // Anda dapat mengganti ini dengan username Anda. Karakter Tionghoa didukung. try { // Anda perlu mengimplementasikan fetchToken untuk mendapatkan token yang diencode Base64 dari server Anda. const base64Token = await fetchToken(); await aliRtcEngine.joinChannel(base64Token, userName); // Berhasil bergabung ke channel. Lanjutkan dengan operasi lainnya. } catch (error) { // Gagal bergabung ke channel. }Bergabung dengan beberapa parameter
// Hasilkan informasi otentikasi di server Anda atau secara lokal mengikuti panduan otentikasi berbasis token. // PENTING: Untuk keamanan data, jangan pernah memublikasikan logika perhitungan token yang mencakup AppKey Anda kepada pengguna akhir. const appId = 'yourAppId'; // Dapatkan ini dari konsol. const appKey = 'yourAppKey'; // Dapatkan ini dari konsol. Jangan paparkan AppKey Anda di lingkungan produksi. const channelId = 'AliRtcDemo'; // Anda dapat mengganti ini dengan ID channel Anda. Hanya huruf dan angka yang didukung. const userId = 'test1'; // Anda dapat mengganti ini dengan ID pengguna Anda. Hanya huruf dan angka yang didukung. const userName = 'Test User 1'; // Anda dapat mengganti ini dengan username Anda. Karakter Tionghoa didukung. const timestamp = Math.floor(Date.now() / 1000) + 3600; // Kedaluwarsa dalam satu jam. try { const token = await generateToken(appId, appKey, channelId, userId, timestamp); // Bergabung ke channel. Parameter seperti token dan timestamp biasanya dikembalikan dari server. // Catatan: Saat memanggil metode ini, pastikan parameter channelId, userId, appId, dan timestamp sesuai dengan yang digunakan untuk menghasilkan token. await aliRtcEngine.joinChannel({ channelId, userId, appId, token, timestamp, }, userName); // Berhasil bergabung ke channel. Lanjutkan dengan operasi lainnya. } catch (error) { // Gagal bergabung ke channel. }
Ikuti langkah-langkah berikut untuk pratinjau video lokal Anda. Secara default, setelah Anda bergabung ke channel, data audio dan video lokal secara otomatis ditangkap dan dipublikasikan ke Global Realtime Transport Network (GRTN).
Dalam kode HTML, tambahkan elemen VIDEO dengan
idlocalPreviewer.<video id="localPreviewer" muted style="display: block;width: 320px;height: 180px;background-color: black;" ></video>Panggil metode
setLocalViewConfigdan berikan ID elemen untuk memulai pratinjau.// Parameter pertama menerima HTMLVideoElement atau ID-nya. Berikan null untuk menghentikan pratinjau. // Parameter kedua menentukan jenis aliran: 1 untuk aliran kamera, 2 untuk aliran berbagi layar. aliRtcEngine.setLocalViewConfig('localPreviewer', 1);
Berlangganan aliran audio dan video jarak jauh. Secara default, setelah bergabung ke channel, SDK secara otomatis berlangganan aliran audio dan video streamer lainnya. Aliran audio diputar secara otomatis. Untuk melihat aliran kamera atau aliran berbagi layar, panggil metode
setRemoteViewConfig.Dalam kode HTML, tambahkan elemen
DIVdenganidremoteVideoContainersebagai wadah.<div id="remoteVideoContainer"></div>Dengarkan perubahan langganan aliran video jarak jauh. Saat aliran berlangganan, putar dengan memanggil metode
setRemoteViewConfig. Saat tidak berlangganan, hapus elemen video tersebut.// Simpan elemen Video. const remoteVideoElMap = {}; // Elemen wadah jarak jauh. const remoteVideoContainer = document.querySelector('#remoteVideoContainer'); function removeRemoteVideo(userId) { const el = remoteVideoElMap[userId]; if (el) { aliRtcEngine.setRemoteViewConfig(null, userId, 1); el.pause(); remoteVideoContainer.removeChild(el); delete remoteVideoElMap[userId]; } } // Ini adalah contoh yang sama seperti pada langkah "dengarkan dan tangani event terkait" untuk `videoSubscribeStateChanged`. aliRtcEngine.on('videoSubscribeStateChanged', (userId, oldState, newState, interval, channelId) => { // `oldState` dan `newState` bertipe AliRtcSubscribeState. // Nilai: 0 (diinisialisasi), 1 (tidak berlangganan), 2 (sedang berlangganan), 3 (berlangganan). // `interval` adalah waktu antar perubahan status, dalam milidetik. console.log(`Status langganan pengguna jarak jauh ${userId} di channel ${channelId} berubah dari ${oldState} menjadi ${newState}.`); // Penangan contoh if (newState === 3) { const video = document.createElement('video'); video.autoplay = true; video.setAttribute('style', 'display: block;width: 320px;height: 180px;background-color: black;'); remoteVideoElMap[userId] = video; remoteVideoContainer.appendChild(video); // Parameter pertama adalah HTMLVideoElement. // Parameter kedua adalah ID pengguna jarak jauh. // Parameter ketiga menentukan jenis aliran: 1 untuk aliran kamera, 2 untuk aliran berbagi layar. aliRtcEngine.setRemoteViewConfig(video, userId, 1); } else if (newState === 1) { removeRemoteVideo(userId); } });
Akhiri sesi dan bersihkan sumber daya.
// Hentikan pratinjau lokal. await aliRtcEngine.stopPreview(); // Tinggalkan channel. await aliRtcEngine.leaveChannel(); // Hapus instans untuk melepaskan sumber daya. aliRtcEngine.destroy();
Demo quick start
JavaScript dalam demo ini mencakup metode generateToken untuk menghitung token. Untuk alasan keamanan, jangan pernah memublikasikan kode ini atau AppKey Anda dalam file JavaScript sisi klien, karena dapat menyebabkan kebocoran informasi dan penyalahgunaan. Kami menyarankan agar Anda melakukan penandatanganan token di server Anda dan mengambil token melalui API terotentikasi di sisi klien.
Prasyarat
Demo ini memerlukan server HTTP di lingkungan pengembangan Anda. Jika Anda belum memiliki paket npm http-server, jalankan npm install --global http-server untuk menginstalnya secara global.
Langkah 1: Buat direktori
Buat folder demo yang berisi dua file: quick.html dan quick.js.
- demo
- quick.html
- quick.jsLangkah 2: Edit quick.html
Salin kode berikut ke dalam quick.html dan simpan file tersebut.
Langkah 3: Edit quick.js
Salin kode berikut ke dalam quick.js. Tempelkan application ID dan AppKey Anda ke dalam variabel yang ditentukan dan simpan file tersebut.
Langkah 4: Jalankan demo
Di terminal Anda, buka folder
demodan jalankanhttp-server -p 8080untuk memulai server HTTP.Buka tab browser baru dan akses
localhost:8080/quick.html. Masukkan Channel ID dan User ID, lalu klik Join Channel.Buka tab browser kedua dan akses
localhost:8080/quick.html. Masukkan Channel ID yang sama tetapi User ID yang berbeda, lalu klik Join Channel.Verifikasi bahwa aliran media dari pengguna lain secara otomatis berlangganan dan ditampilkan di halaman.
Pertanyaan umum
Apa yang harus saya lakukan jika koneksi ulang manual gagal atau koneksi ulang gagal setelah refresh halaman?
Koneksi ulang manual melaporkan error pembuatan aliran duplikat: SDK memiliki mekanisme koneksi ulang bawaan, dan intervensi tingkat kode hanya diperlukan ketika koneksi ulang gagal. Jika Anda memicu koneksi ulang secara manual, Anda harus menghapus aliran yang ada atau menggunakan kembali instans yang ada sebelum bergabung kembali ke channel, untuk menghindari pembuatan aliran duplikat saat satu aliran sudah ada.
Koneksi ulang gagal setelah refresh halaman: Refresh halaman menghancurkan instans SDK, sehingga Anda harus menjalani proses bergabung penuh lagi dengan memanggil
joinChannel. Kami menyarankan agar Anda mendengarkan eventconnectionStatusChange, dan ketika terdeteksi pemutusan koneksi atau kegagalan, panggilleaveChannellalu bergabung kembali ke channel untuk menyelesaikan koneksi ulang.