BotFramework WebChat
[4.18.0] - 2024-07-10
Этот репозиторий содержит код для компонента веб-чата Bot Framework. Компонент веб-чата Bot Framework — это веб-клиент с широкими возможностями настройки для пакета SDK Bot Framework v4. Пакет SDK Bot Framework v4 позволяет разработчикам моделировать диалог и создавать сложные бот-приложения.
Этот репозиторий является частью Microsoft Bot Framework — комплексной платформы для создания диалогового интерфейса искусственного интеллекта корпоративного уровня.
Веб-чат поддерживает политику безопасности контента (CSP). Веб-разработчикам рекомендуется включить CSP для повышения безопасности и защиты разговоров. Подробнее о CSP можно прочитать в этой статье.
В этом разделе приведены важные примечания к версии. Для получения дополнительной информации, пожалуйста, перейдите по соответствующим ссылкам и посетите
CHANGELOG.md
Примечания: веб-разработчикам рекомендуется использовать ~ (диапазон тильды) для выбора второстепенных версий, которые содержат новые функции и/или исправления. Используйте ^ (диапазон символов), чтобы выбрать основные версии, которые могут содержать критические изменения.
В этом выпуске мы концентрируемся на улучшении производительности, включая оптимизацию памяти и времени загрузки.
Боты теперь могут транслировать свои ответы в прямом эфире. Прежде чем Bot Framework SDK поддержит эту функцию, авторы ботов могут следить за подробностями в LIVESTREAMING.md, чтобы создавать ответы в прямом эфире.
Веб-чат теперь экспортируется как модули ES (именованный экспорт) вместе с CommonJS (именованный и безымянный экспорт).
Конечный пользователь теперь может добавить сообщение и подтвердить его перед загрузкой файла в бот. Чтобы отказаться от нового интерфейса, передайте sendAttachmentOn: 'send' в параметрах стиля.
Мы рады добавить поддержку пакетов тем. Теперь разработчики могут упаковать все свои настройки в один пакет и опубликовать его в NPM.
Мы рады сообщить, что пакет тем Fluent UI находится в разработке и в настоящее время находится на экспериментальной стадии. Этот пакет тем предназначен для веб-разработчиков, которые хотят предоставить своим клиентам удобный пользовательский интерфейс Copilot.
Мы продолжим добавлять новые функции и поддерживать как White-label, так и Fluent UI с тем же уровнем паритета.
Вы можете обернуть веб-чат с помощью <FluentThemeProvider> чтобы опробовать новые возможности.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} Веб-чат теперь отображает HTML-в-Markdown. Мы перенесли наше дезинфицирующее средство и средство исправления специальных возможностей для работы на уровне HTML. И Markdown, и HTML-in-Markdown будут обрабатываться одинаково и соответствовать нашим требованиям безопасности и доступности.
Вы можете отключить эту опцию, установив для styleOptions.markdownRenderHTML значение false .
Веб-чат теперь поддерживает схему адаптивных карточек до версии 1.6. Некоторые функции Adaptive Cards находятся в предварительной версии или предназначены для использования за пределами Bot Framework. Веб-чат не поддерживает эти функции.
Начиная с версии 4.16.0, Internet Explorer больше не поддерживается. После более чем года официального прекращения поддержки Internet Explorer 11 мы решили прекратить поддержку Internet Explorer. Это поможет нам добавить новые функции в веб-чат. 4.15.9 — последняя версия, которая ограниченно поддерживает Internet Explorer.
adaptiveCardsParserMaxVersionПатч веб-чата 4.12.1 включает новое свойство стиля, позволяющее разработчикам выбирать максимальную версию схемы адаптивных карточек. См. PR № 3778 для изменений кода.
Чтобы указать другую максимальную версию, вы можете настроить параметры стиля, как показано ниже:
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ; В веб-чат было добавлено новое обновление специальных возможностей из PR № 3703. Это изменение по умолчанию создает визуальный фокус для расшифровки (жирная черная рамка) и сфокусированной активности aria-activedescendent (черная пунктирная рамка). Там, где это применимо, значения transcriptVisualKeyboardIndicator... также будут применяться к дочерним элементам карусели ( CarouselFilmStrip.js ). Это сделано для того, чтобы соответствовать текущему стилю фокуса по умолчанию для адаптивных карточек, которые могут быть дочерними элементами карусели.
Чтобы изменить эти стили, вы можете изменить следующие реквизиты с помощью styleOptions :
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
В приведенном выше коде показаны значения по умолчанию, которые вы увидите в веб-чате.
API веб-чата был выделен в отдельный пакет. Чтобы узнать больше, ознакомьтесь со сводкой по рефакторингу API.
Начиная с версии веб-чата 4.7.0 поддерживается прямая речь, и это предпочтительный способ обеспечения встроенной голосовой функции в веб-чате. Мы работаем над устранением пробелов в функциях между Direct Line Speech и Web Speech API (включая Cognitive Services и речевые функции, предоставляемые браузером).
Начиная с веб-чата 4.6.0, для веб-чата требуется React 16.8.6 или более поздняя версия.
Хотя мы рекомендуем вам обновить ведущее приложение при первой же возможности, мы понимаем, что ведущему приложению может потребоваться некоторое время, прежде чем его зависимости React будут обновлены, особенно в отношении огромных приложений.
Если ваше приложение еще не готово для React 16.8.6, вы можете воспользоваться примером гибридного React, чтобы использовать React с двумя хостами в своем приложении.
Произошли серьезные изменения в ожиданиях относительно поведения в отношении речи и подсказок при вводе в веб-чате. Подробности см. в разделе о поведении подсказок при вводе до версии 4.5.0.
Просмотрите документацию по миграции, чтобы узнать о переходе с веб-чата v3.
Сначала создайте бота с помощью службы Azure Bot. После создания бота вам потребуется получить секрет веб-чата бота на портале Azure. Затем используйте секрет для создания токена и передайте его в свой веб-чат.
Веб-чат предоставляет пользовательский интерфейс поверх прямой линии и речевых каналов прямой линии. Существует два способа подключения к вашему боту через HTTP-вызовы от клиента: отправив секрет бота или сгенерировав токен с помощью секрета.
Мы настоятельно рекомендуем использовать API токена вместо того, чтобы предоставлять приложению свой секрет. Чтобы узнать больше о том, почему, см. документацию по аутентификации по API токена и безопасности клиента.
Для дальнейшего чтения, пожалуйста, перейдите по следующим ссылкам:
Использование веб-чата с аутентификацией Azure Bot Services
Расширенные функции аутентификации по прямой линии.
Веб-чат предназначен для интеграции с вашим существующим веб-сайтом с помощью JavaScript или React. Интеграция с JavaScript предоставит вам умеренные возможности стилизации и настройки.
Вы можете использовать полный типичный пакет веб-чата (называемый полнофункциональным пакетом), который содержит наиболее часто используемые функции.
Вот как можно добавить элемент управления веб-чатом на свой веб-сайт:
<!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иlocale— все это необязательные параметры для передачи в методrenderWebChat. Дополнительные сведения о реквизитах веб-чата см. в справочной документации по API веб-чата.
Назначать
userIDв качестве статического значения не рекомендуется, так как это приведет к тому, что все пользователи будут делиться состоянием. Дополнительную информацию см.API userID entry.
Более подробную информацию о локализации можно найти в документации по локализации.
См. рабочий образец полного пакета веб-чата.
Для полной настройки вы можете использовать React для перекомпоновки компонентов веб-чата.
Чтобы установить производственную сборку из NPM, запустите npm install botframework-webchat . О том, как выбрать версию, см. в наших примечаниях к версии.
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" / > ;
} ;Вы также можете запустить
npm install botframework-webchat@main, чтобы установить сборку для разработки, которая синхронизируется сmainветкой GitHub веб-чата.
См. рабочий пример веб-чата, созданный с помощью React.
Веб-чат внутри использует Redux для управления состоянием. Redux DevTools включен в сборке NPM в качестве дополнительной функции.
Это сделано для того, чтобы взглянуть на то, как работает веб-чат. Это не проводник API и не одобрение использования хранилища Redux для программного доступа к пользовательскому интерфейсу. Вместо этого следует использовать API перехватчиков.
Чтобы использовать Redux DevTools, используйте функцию createStoreWithDevTools для создания хранилища с поддержкой 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" />;
};При использовании Redux DevTools существуют некоторые ограничения:
redux-saga . Путешествие во времени может привести к поломке пользовательского интерфейса.Веб-чат спроектирован таким образом, чтобы его можно было настраивать без изменения исходного кода. В таблице ниже показано, какие настройки можно выполнить при импорте веб-чата различными способами. Этот список не является исчерпывающим.
| пакет CDN | Реагировать | |
|---|---|---|
| Изменить цвета | ✔ | ✔ |
| Изменить размеры | ✔ | ✔ |
| Обновить/заменить стили CSS | ✔ | ✔ |
| Слушайте события | ✔ | ✔ |
| Взаимодействие с веб-страницей хостинга | ✔ | ✔ |
| Пользовательские действия по рендерингу | ✔ | |
| Пользовательские вложения для рендеринга | ✔ | |
| Добавить новые компоненты пользовательского интерфейса | ✔ | |
| Перекомпонуйте весь пользовательский интерфейс | ✔ |
Узнайте больше о настройке веб-чата, чтобы узнать больше о настройке.
Bot Framework имеет множество типов действий, но не все они поддерживаются в веб-чате. Чтобы узнать больше, просмотрите документацию по типам действий.
Просмотрите полный список примеров веб-чата, чтобы получить дополнительные идеи по настройке веб-чата.
Просмотрите документацию по API для реализации веб-чата.
Веб-чат поддерживает две последние версии современных браузеров, таких как Chrome, Microsoft Edge и FireFox. Если вам нужен веб-чат в Internet Explorer 11, см. демонстрационную версию пакета ES5.
Однако обратите внимание:
babel . Просмотрите документацию о специальных возможностях.
Просмотрите документацию по локализации для реализации в веб-чате.
Просмотрите документацию по уведомлениям для реализации в веб-чате.
Просмотрите документацию по телеметрии для реализации в веб-чате.
Прежде чем сообщать о новой проблеме, просмотрите Руководство по технической поддержке, чтобы получить рекомендации и помощь по устранению неполадок в репозитории веб-чата.
Веб-чат поддерживает широкий спектр речевых движков для естественного общения с ботом. В этом разделе описаны различные поддерживаемые движки:
Прямая речь — это предпочтительный способ добавления речевых функций в веб-чат. Подробную информацию см. в документации по прямой речи.
Вы можете использовать речевые службы Cognitive Services, чтобы добавить речевые функции в веб-чат. Подробную информацию см. в документации по речевым службам Cognitive Services.
Вы также можете использовать любые речевые движки, поддерживающие стандарт W3C Web Speech API. Некоторые браузеры поддерживают API распознавания речи и API синтеза речи. Вы можете комбинировать различные механизмы, включая речевые службы Cognitive Services, для обеспечения наилучшего взаимодействия с пользователем.
Последние новости веб-чата доступны на странице ежедневных выпусков веб-чата.
Ежедневные газеты будут выпускаться после 3:00 утра по тихоокеанскому стандартному времени, когда изменения будут внесены в основную ветку.
Подробную информацию о том, как создать проект, а также наши рекомендации по репозиторию для запросов на включение см. на нашей странице «Вклад».
Подробную информацию о Кодексе поведения Microsoft см. на странице КОДЕКС ПОВЕДЕНИЯ.
Просмотрите документацию по безопасности, чтобы узнать больше о том, как сообщать о проблемах безопасности.
