BotFramework WebChat
[4.18.0] - 2024-07-10
이 리포지토리에는 Bot Framework 웹 채팅 구성 요소에 대한 코드가 포함되어 있습니다. Bot Framework 웹 채팅 구성 요소는 Bot Framework v4 SDK용 고도로 사용자 지정 가능한 웹 기반 클라이언트입니다. Bot Framework SDK v4를 사용하면 개발자는 대화를 모델링하고 정교한 봇 애플리케이션을 구축할 수 있습니다.
이 리포지토리는 엔터프라이즈급 대화형 AI 환경을 구축하기 위한 포괄적인 프레임워크인 Microsoft Bot Framework의 일부입니다.
웹 채팅은 CSP(콘텐츠 보안 정책)를 지원합니다. 웹 개발자는 보안을 강화하고 대화를 보호하기 위해 CSP를 활성화하는 것이 좋습니다. 이 문서에서 CSP에 대해 자세히 알아볼 수 있습니다.
이 섹션에서는 중요한 버전 참고 사항을 설명합니다. 자세한 내용은 관련 링크를 확인하시고
CHANGELOG.md를 확인해주세요.
참고: 웹 개발자는 새로운 기능 및/또는 수정 사항이 포함된 부 버전을 선택하려면 ~ (물결표 범위)를 사용하는 것이 좋습니다. 주요 변경 사항이 포함될 수 있는 주요 버전을 선택하려면 ^ (캐럿 범위)를 사용하세요.
이번 릴리스에서는 메모리 및 로드 시간 최적화를 포함한 성능 개선에 중점을 두고 있습니다.
이제 봇은 응답을 실시간 스트리밍할 수 있습니다. Bot Framework SDK가 이 기능을 지원하기 전에 봇 작성자는 LIVESTREAMING.md의 세부 정보에 따라 라이브 스트림 응답을 구성할 수 있습니다.
이제 웹 채팅은 CommonJS(이름이 지정된 내보내기 및 이름이 없는 내보내기)와 함께 ES 모듈(이름이 지정된 내보내기)로 내보냅니다.
이제 최종 사용자는 파일을 봇에 업로드하기 전에 메시지를 추가하고 확인할 수 있습니다. 새로운 환경을 선택 해제하려면 스타일 옵션에 sendAttachmentOn: 'send' 전달하세요.
테마 팩 지원을 추가하게 되어 기쁘게 생각합니다. 이제 개발자는 모든 사용자 정의를 단일 패키지에 담아 NPM에 게시할 수 있습니다.
Fluent UI 테마 팩이 작업 중이며 현재 실험 단계에 있음을 알리게 되어 기쁘게 생각합니다. 이 테마 팩은 고객에게 기본 Copilot 사용자 경험을 제공하려는 웹 개발자를 위해 설계되었습니다.
우리는 계속해서 새로운 기능을 추가하고 동일한 수준의 패리티로 화이트 라벨 환경과 Fluent UI 환경을 모두 지원할 것입니다.
<FluentThemeProvider> 로 웹 채팅을 래핑하여 새로운 환경을 시험해 볼 수 있습니다.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} 이제 웹 채팅은 HTML-in-Markdown을 렌더링합니다. 우리는 HTML 수준에서 작동하도록 살균제 및 접근성 수정 프로그램을 이식했습니다. Markdown과 HTML-in-Markdown은 모두 동일한 처리를 받으며 보안 및 접근성 요구 사항을 충족합니다.
styleOptions.markdownRenderHTML 을 false 로 설정하여 이 옵션을 끌 수 있습니다.
이제 웹 채팅은 최대 1.6의 적응형 카드 스키마를 지원합니다. 적응형 카드의 일부 기능은 미리 보기 상태이거나 Bot Framework 외부에서 사용하도록 설계되었습니다. 웹 채팅은 이러한 기능을 지원하지 않습니다.
4.16.0부터 Internet Explorer는 더 이상 지원되지 않습니다. Internet Explorer 11이 공식적으로 종료된 지 1년이 넘은 후, 우리는 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가 지원되며 이는 웹 채팅에서 통합 음성 기능을 제공하는 데 선호되는 방법입니다. 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 이전의 입력 힌트 동작 섹션을 참조하세요.
Web Chat v3에서 마이그레이션하는 방법을 알아보려면 마이그레이션 문서를 확인하세요.
먼저 Azure Bot Service를 사용하여 봇을 만듭니다. 봇이 생성되면 Azure Portal에서 봇의 웹 채팅 비밀을 얻어야 합니다. 그런 다음 비밀을 사용하여 토큰을 생성하고 웹 채팅에 전달합니다.
웹 채팅은 Direct Line 및 Direct Line 음성 채널 위에 UI를 제공합니다. 클라이언트의 HTTP 호출을 통해 봇에 연결하는 방법에는 Bot 비밀을 보내거나 비밀을 통해 토큰을 생성하는 두 가지 방법이 있습니다.
앱에 비밀 정보를 제공하는 대신 토큰 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실행하여 웹 채팅의 GitHubmain분기와 동기화되는 개발 빌드를 설치할 수도 있습니다.
React를 통해 렌더링된 웹 채팅의 작업 샘플을 참조하세요.
웹 채팅은 상태 관리를 위해 내부적으로 Redux를 사용합니다. Redux DevTools는 NPM 빌드에서 옵트인 기능으로 활성화됩니다.
이는 웹 채팅이 어떻게 작동하는지 살펴보기 위한 것입니다. 이는 API 탐색기가 아니며 프로그래밍 방식으로 UI에 액세스하기 위해 Redux 저장소를 사용하는 것을 보증하지 않습니다. 대신 후크 API를 사용해야 합니다.
Redux DevTools를 사용하려면 Redux DevTools 지원 저장소를 생성하기 위한 createStoreWithDevTools 함수를 사용하세요.
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 통해 부작용을 사용합니다. 시간 이동으로 인해 UI가 손상될 수 있습니다.웹 채팅은 소스 코드를 포크하지 않고도 사용자 정의할 수 있도록 설계되었습니다. 아래 표에는 다양한 방법으로 웹 채팅을 가져올 때 달성할 수 있는 사용자 정의 유형이 간략하게 설명되어 있습니다. 이 목록은 완전한 것이 아닙니다.
| CDN 번들 | 반응하다 | |
|---|---|---|
| 색상 변경 | ✔ | ✔ |
| 사이즈 변경 | ✔ | ✔ |
| CSS 스타일 업데이트/교체 | ✔ | ✔ |
| 이벤트 듣기 | ✔ | ✔ |
| 호스팅 웹페이지와 상호작용 | ✔ | ✔ |
| 사용자 정의 렌더링 활동 | ✔ | |
| 사용자 정의 렌더링 첨부 파일 | ✔ | |
| 새로운 UI 구성 요소 추가 | ✔ | |
| 전체 UI 재구성 | ✔ |
사용자 정의에 대해 자세히 알아보려면 웹 채팅 사용자 정의에 대해 자세히 알아보세요.
Bot Framework에는 다양한 활동 유형이 있지만 웹 채팅에서 모든 활동 유형이 지원되는 것은 아닙니다. 자세히 알아보려면 활동 유형 문서를 확인하세요.
웹 채팅 사용자 정의에 대한 더 많은 아이디어를 보려면 웹 채팅 샘플의 전체 목록을 확인하세요.
웹 채팅 구현에 대한 API 설명서를 확인하세요.
웹 채팅은 Chrome, Microsoft Edge, FireFox 등 최신 2가지 버전의 최신 브라우저를 지원합니다. Internet Explorer 11에서 웹 채팅이 필요한 경우 ES5 번들 데모를 참조하세요.
그러나 다음 사항에 유의하십시오.
babel 과 같은 폴리필 및 트랜스파일러를 사용하여 ES6+에서 ES5로 코드를 변환하는 방법을 살펴보는 것이 좋습니다. 접근성 문서를 확인하세요.
웹 채팅 구현에 대한 현지화 문서를 확인하세요.
웹 채팅 구현에 대한 알림 설명서를 확인하세요.
웹 채팅 구현에 대한 원격 측정 설명서를 확인하세요.
새로운 문제를 제출하기 전에 웹 채팅 저장소에서 문제 해결에 대한 지침과 도움을 받으려면 기술 지원 가이드를 확인하세요.
웹 채팅은 봇과의 자연스러운 채팅 경험을 위해 광범위한 음성 엔진을 지원합니다. 이 섹션에서는 지원되는 다양한 엔진에 대해 간략하게 설명합니다.
직접 회선 음성은 웹 채팅에 음성 기능을 추가하는 데 선호되는 방법입니다. 자세한 내용은 Direct Line Speech 문서를 참고하세요.
Cognitive Services 음성 서비스를 사용하여 웹 채팅에 음성 기능을 추가할 수 있습니다. 자세한 내용은 Cognitive Services 음성 서비스 설명서를 참조하세요.
W3C Web Speech API 표준을 지원하는 모든 음성 엔진을 사용할 수도 있습니다. 일부 브라우저는 음성 인식 API 및 음성 합성 API를 지원합니다. Cognitive Services 음성 서비스를 비롯한 다양한 엔진을 조합하여 최상의 사용자 경험을 제공할 수 있습니다.
웹 채팅 최신 정보는 웹 채팅 일일 릴리스 페이지에서 확인할 수 있습니다.
데일리는 메인 브랜치에 변경 사항이 적용된 오전 3시(태평양 표준시) 이후에 출시됩니다.
프로젝트 빌드 방법과 끌어오기 요청에 대한 저장소 지침에 대한 자세한 내용은 기여 페이지를 참조하세요.
Microsoft 행동 강령에 대한 자세한 내용은 행동 강령 페이지를 참조하세요.
보안 문제 보고에 대한 자세한 내용은 보안 설명서를 참조하세요.
