BotFramework WebChat
[4.18.0] - 2024-07-10
Repositori ini berisi kode untuk komponen Bot Framework Web Chat. Komponen Bot Framework Web Chat adalah klien berbasis web yang sangat dapat disesuaikan untuk Bot Framework v4 SDK. Bot Framework SDK v4 memungkinkan pengembang memodelkan percakapan dan membangun aplikasi bot yang canggih.
Repositori ini adalah bagian dari Microsoft Bot Framework - kerangka kerja komprehensif untuk membangun pengalaman AI percakapan tingkat perusahaan.
Obrolan Web mendukung Kebijakan Keamanan Konten (CSP). Pengembang web disarankan untuk mengaktifkan CSP untuk meningkatkan keamanan dan melindungi percakapan. Anda dapat membaca lebih lanjut tentang CSP di artikel ini.
Bagian ini menunjukkan catatan versi penting. Untuk informasi lebih lanjut, silakan lihat tautan terkait dan periksa
CHANGELOG.md
Catatan: pengembang web disarankan untuk menggunakan ~ (kisaran tilde) untuk memilih versi minor, yang berisi fitur dan/atau perbaikan baru. Gunakan ^ (rentang tanda sisipan) untuk memilih versi utama, yang mungkin berisi perubahan yang dapat menyebabkan gangguan.
Dalam rilis ini, kami berfokus pada peningkatan kinerja, termasuk optimalisasi memori dan waktu buka.
Bot sekarang dapat melakukan streaming langsung tanggapan mereka. Sebelum Bot Framework SDK mendukung fitur ini, pembuat bot dapat mengikuti detailnya di LIVESTREAMING.md untuk membuat respons streaming langsung.
Obrolan Web sekarang diekspor sebagai Modul ES (ekspor bernama) bersama dengan CommonJS (ekspor bernama dan tanpa nama).
Pengguna akhir sekarang dapat menambahkan pesan dan mengonfirmasi sebelum mengunggah file mereka ke bot. Untuk memilih tidak ikut pengalaman baru, teruskan sendAttachmentOn: 'send' dalam opsi gaya.
Kami sangat bersemangat untuk menambahkan dukungan paket tema. Pengembang kini dapat mengemas semua penyesuaian mereka dalam satu paket dan mempublikasikannya ke NPM.
Kami sangat gembira mengumumkan bahwa paket tema UI Lancar sedang dalam pengerjaan dan saat ini sedang dalam tahap percobaan. Paket tema ini dirancang untuk pengembang web yang ingin menghadirkan pengalaman pengguna Copilot asli kepada pelanggan mereka.
Kami akan terus menambahkan fitur baru dan mendukung pengalaman label putih dan pengalaman UI Lancar dengan tingkat keseimbangan yang sama.
Anda dapat menyelesaikan Obrolan Web dengan <FluentThemeProvider> untuk mencoba pengalaman baru.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} Obrolan Web sekarang akan merender HTML-in-Markdown. Kami telah mem-porting pembersih dan pemecah aksesibilitas kami agar berfungsi pada tingkat HTML. Markdown dan HTML-in-Markdown akan menerima perlakuan yang sama dan memenuhi persyaratan keamanan dan aksesibilitas kami.
Anda dapat menonaktifkan opsi ini dengan menyetel styleOptions.markdownRenderHTML ke false .
Obrolan Web sekarang mendukung skema Kartu Adaptif hingga 1.6. Beberapa fitur di Kartu Adaptif sedang dalam pratinjau atau dirancang untuk digunakan di luar Kerangka Bot. Obrolan Web tidak mendukung fitur ini.
Mulai dari 4.16.0, Internet Explorer tidak lagi didukung. Setelah lebih dari setahun Internet Explorer 11 resmi dihentikan, kami memutuskan untuk berhenti mendukung Internet Explorer. Ini akan membantu kami menghadirkan fitur baru ke Obrolan Web. 4.15.9 adalah versi terakhir yang mendukung Internet Explorer secara terbatas.
adaptiveCardsParserMaxVersionPatch Web Chat 4.12.1 menyertakan properti gaya baru yang memungkinkan pengembang memilih versi skema Kartu Adaptif maksimal. Lihat PR #3778 untuk perubahan kode.
Untuk menentukan versi maksimal yang berbeda, Anda dapat menyesuaikan opsi gaya, seperti yang ditunjukkan di bawah ini:
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ; Pembaruan aksesibilitas baru telah ditambahkan ke Obrolan Web dari PR #3703. Perubahan ini menciptakan fokus visual untuk transkrip (batas hitam tebal) dan aktivitas terfokus aria-activedescendent (batas putus-putus hitam) secara default. Jika berlaku, nilai transcriptVisualKeyboardIndicator... juga akan diterapkan pada turunan carousel ( CarouselFilmStrip.js ). Hal ini dilakukan untuk mencocokkan gaya fokus default saat ini untuk Kartu Adaptif, yang mungkin merupakan turunan dari carousel.
Untuk memodifikasi gaya ini, Anda dapat mengubah props berikut melalui styleOptions :
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
Kode di atas menunjukkan nilai default yang akan Anda lihat di Web Chat.
API Obrolan Web telah difaktorkan ulang menjadi paket terpisah. Untuk mempelajari lebih lanjut, lihat ringkasan pemfaktoran ulang API.
Mulai dari Web Chat 4.7.0, Direct Line Speech didukung, dan ini merupakan cara pilihan untuk menyediakan fungsionalitas ucapan terintegrasi di Web Chat. Kami sedang berupaya untuk menutup kesenjangan fitur antara Direct Line Speech dan Web Speech API (termasuk Layanan Kognitif dan fungsi ucapan yang disediakan browser).
Mulai dari Web Chat 4.6.0, Web Chat memerlukan React 16.8.6 atau lebih tinggi.
Meskipun kami menyarankan agar Anda mengupgrade aplikasi host Anda sesegera mungkin, kami memahami bahwa aplikasi host mungkin memerlukan beberapa waktu sebelum dependensi React-nya diperbarui, terutama yang berkaitan dengan aplikasi berukuran besar.
Jika aplikasi Anda belum siap untuk React 16.8.6, Anda dapat mengikuti contoh React hybrid untuk menghosting ganda React di aplikasi Anda.
Ada perubahan besar pada ekspektasi perilaku terkait ucapan dan petunjuk masukan di Obrolan Web. Silakan merujuk ke bagian tentang perilaku petunjuk masukan sebelum 4.5.0 untuk detailnya.
Lihat dokumen migrasi untuk mempelajari tentang migrasi dari Web Chat v3.
Pertama, buat bot menggunakan Azure Bot Service. Setelah bot dibuat, Anda perlu mendapatkan rahasia Obrolan Web bot di Portal Azure. Kemudian gunakan rahasianya untuk menghasilkan token dan meneruskannya ke Obrolan Web Anda.
Obrolan Web menyediakan UI di atas Saluran Ucapan Jalur Langsung dan Jalur Langsung. Ada dua cara untuk terhubung ke bot Anda melalui panggilan HTTP dari klien: dengan mengirimkan rahasia Bot atau membuat token melalui rahasia tersebut.
Kami sangat menyarankan penggunaan token API daripada memberikan rahasia Anda kepada aplikasi. Untuk mempelajari lebih lanjut alasannya, lihat dokumentasi autentikasi pada API token dan keamanan klien.
Untuk bacaan lebih lanjut, silakan lihat tautan berikut:
Menggunakan Obrolan Web dengan autentikasi Azure Bot Services
Fitur otentikasi Direct Line yang ditingkatkan
Obrolan Web dirancang untuk berintegrasi dengan situs web Anda yang sudah ada menggunakan JavaScript atau React. Mengintegrasikan dengan JavaScript akan memberi Anda opsi gaya dan penyesuaian yang moderat.
Anda dapat menggunakan paket Obrolan Web lengkap dan umum (disebut paket fitur lengkap) yang berisi fitur-fitur yang paling sering digunakan.
Berikut ini cara menambahkan kontrol Obrolan Web ke situs web Anda:
<!DOCTYPE html >
< html >
< head >
< script
crossorigin =" anonymous "
src =" https://cdn.botframework.com/botframework-webchat/latest/webchat.js "
> </ script >
< style >
html,
body {
height: 100%;
}
body {
margin: 0;
}
#webchat {
height: 100%;
width: 100%;
}
</ style >
</ head >
< body >
< div id =" webchat " role =" main " > </ div >
< script >
window . WebChat . renderWebChat (
{
directLine : window . WebChat . createDirectLine ( {
token : 'YOUR_DIRECT_LINE_TOKEN'
} ) ,
userID : 'YOUR_USER_ID' ,
username : 'Web Chat User' ,
locale : 'en-US'
} ,
document . getElementById ( 'webchat' )
) ;
</ script >
</ body >
</ html >
userID,username, danlocalemerupakan parameter opsional untuk diteruskan ke metoderenderWebChat. Untuk mempelajari selengkapnya tentang alat peraga Obrolan Web, lihat dokumentasi Referensi API Obrolan Web.
Menetapkan
userIDsebagai nilai statis tidak disarankan karena ini akan menyebabkan semua pengguna berbagi status. Silakan lihatAPI userID entryuntuk informasi lebih lanjut.
Informasi lebih lanjut tentang pelokalan dapat ditemukan di dokumentasi Pelokalan.
Lihat contoh kerja paket Obrolan Web lengkap.
Untuk penyesuaian penuh, Anda dapat menggunakan React untuk menyusun ulang komponen Obrolan Web.
Untuk menginstal build produksi dari NPM, jalankan npm install botframework-webchat . Lihat catatan versi kami tentang cara memilih versi.
import React , { useMemo } from 'react' ;
import ReactWebChat , { createDirectLine } from 'botframework-webchat' ;
export default ( ) => {
const directLine = useMemo ( ( ) => createDirectLine ( { token : 'YOUR_DIRECT_LINE_TOKEN' } ) , [ ] ) ;
return < ReactWebChat directLine = { directLine } userID = "YOUR_USER_ID" / > ;
} ;Anda juga dapat menjalankan
npm install botframework-webchat@mainuntuk menginstal build pengembangan yang disinkronkan dengan cabangmainGitHub Obrolan Web.
Lihat contoh kerja Obrolan Web yang dirender melalui React.
Obrolan Web secara internal menggunakan Redux untuk manajemen negara. Redux DevTools diaktifkan di build NPM sebagai fitur keikutsertaan.
Ini untuk melihat sekilas cara kerja Obrolan Web. Ini bukan penjelajah API dan bukan merupakan dukungan penggunaan toko Redux untuk mengakses UI secara terprogram. API kait harus digunakan sebagai gantinya.
Untuk menggunakan Redux DevTools, gunakan fungsi createStoreWithDevTools untuk membuat penyimpanan yang mendukung Redux DevTools.
import React, { useMemo } from 'react';
- import ReactWebChat, { createDirectLine, createStore } from 'botframework-webchat';
+ import ReactWebChat, { createDirectLine, createStoreWithDevTools } from 'botframework-webchat';
export default () => {
const directLine = useMemo(() => createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }), []);
- const store = useMemo(() => createStore(), []);
+ const store = useMemo(() => createStoreWithDevTools(), []);
return <ReactWebChat directLine={directLine} store={store} userID="YOUR_USER_ID" />;
};Ada beberapa batasan saat menggunakan Redux DevTools:
redux-saga . Perjalanan waktu dapat merusak UI.Obrolan Web dirancang agar dapat disesuaikan tanpa memalsukan kode sumber. Tabel di bawah menguraikan jenis penyesuaian yang dapat Anda capai saat mengimpor Obrolan Web dengan berbagai cara. Daftar ini tidak lengkap.
| Paket CDN | Bereaksi | |
|---|---|---|
| Ubah warna | ✔ | ✔ |
| Ubah ukuran | ✔ | ✔ |
| Perbarui/ganti gaya CSS | ✔ | ✔ |
| Dengarkan acara | ✔ | ✔ |
| Berinteraksi dengan halaman web hosting | ✔ | ✔ |
| Aktivitas render khusus | ✔ | |
| Lampiran render khusus | ✔ | |
| Tambahkan komponen UI baru | ✔ | |
| Komposisi ulang seluruh UI | ✔ |
Lihat selengkapnya tentang menyesuaikan Obrolan Web untuk mempelajari lebih lanjut tentang penyesuaian.
Bot Framework memiliki banyak jenis aktivitas, namun tidak semuanya didukung di Web Chat. Lihat dokumen jenis aktivitas untuk mempelajari lebih lanjut.
Lihat daftar lengkap contoh Obrolan Web untuk mengetahui lebih banyak ide tentang menyesuaikan Obrolan Web.
Lihat dokumentasi API untuk mengimplementasikan Obrolan Web.
Obrolan Web mendukung 2 versi terbaru browser modern seperti Chrome, Microsoft Edge, dan FireFox. Jika Anda memerlukan Obrolan Web di Internet Explorer 11, silakan lihat demo bundel ES5.
Namun harap diperhatikan:
babel . Lihat dokumentasi aksesibilitas.
Lihat dokumentasi pelokalan untuk diterapkan di Web Chat.
Lihat dokumentasi notifikasi untuk penerapan di Web Chat.
Lihat dokumentasi telemetri untuk penerapan di Web Chat.
Lihat Panduan Dukungan Teknis untuk mendapatkan panduan dan bantuan dalam pemecahan masalah di repo Obrolan Web untuk informasi lebih lanjut sebelum mengajukan masalah baru.
Obrolan Web mendukung berbagai mesin ucapan untuk pengalaman obrolan alami dengan bot. Bagian ini menguraikan berbagai mesin yang didukung:
Direct Line Speech adalah cara pilihan untuk menambahkan fungsionalitas ucapan di Obrolan Web. Silakan merujuk ke dokumentasi Direct Line Speech untuk detailnya.
Anda dapat menggunakan Layanan Pidato Layanan Kognitif untuk menambahkan fungsionalitas ucapan ke Obrolan Web. Silakan merujuk ke dokumentasi Layanan Pidato Layanan Kognitif untuk detailnya.
Anda juga dapat menggunakan mesin ucapan apa pun yang mendukung standar W3C Web Speech API. Beberapa browser mendukung Speech Recognition API dan Speech Synthesis API. Anda dapat memadupadankan mesin yang berbeda - termasuk Layanan Kognitif Layanan Pidato - untuk memberikan pengalaman pengguna terbaik.
Bit terbaru Obrolan Web tersedia di halaman rilis harian Obrolan Web.
Harian akan dirilis setelah pukul 03.00 Waktu Standar Pasifik ketika perubahan telah diterapkan pada cabang utama.
Lihat halaman Kontribusi kami untuk detail tentang cara membangun proyek dan pedoman repositori kami untuk Permintaan Tarik.
Lihat halaman KODE ETIK kami untuk rincian tentang Kode Etik Microsoft.
Lihat dokumentasi keamanan untuk mempelajari lebih lanjut tentang pelaporan masalah keamanan.
