이 튜토리얼은 Kore.ai 봇을 웹 애플리케이션과 통합하는 데 사용할 수 있는 라이브러리의 모음인 Kore.ai 봇 웹 SDK의 인스턴스를 설정하고 실행하기 위한 엔드투엔드 워크스루입니다.
웹 SDK 튜토리얼 개요
이 튜토리얼에서는, Kore.ai 샘플 봇 설치, 봇 호스팅을 위한 테스트 애플리케이션 설치, 로컬 서버의 봇과 Kore.ai 봇 플랫폼 간에 통신을 위해 로컬 호스트 서버를 사용하여 JSON 웹 토큰(JWT) 생성 웹 서비스를 설치합니다. 다음 목록에서는 웹 SDK 설치 및 설정을 위해 수행하는 일반적인 단계를 설명합니다.
- 통합할 봇 구축 – 이 튜토리얼에서는, 날씨 보고서와 함께 항공편 및 위치 정보를 얻기 위해 개방형 API를 사용하는 여행 계획 샘플 봇을 설치합니다.
- 웹/모바일 클라이언트 채널 설정 – 웹 SDK를 이용하여 여행 계획 샘플 봇을 사용하려면, 웹/모바일 클라이언트 채널을 위한 봇을 설정해야 합니다.
- 새 클라이언트 앱 생성 – 여행 계획 샘플 봇을 위한 웹/모바일 클라이언트 채널을 설정할 때, 클라이언트 앱을 생성하고 인증 토큰을 생성하는 데 사용되는 JWT 서명 알고리즘을 선택해야 합니다.
- 봇 게시 – 여행 계획 샘플 봇을 설정한 후, 봇을 게시하고 관리자에게 보내서 승인을 받아야 합니다.
- 봇 승인 및 배포 – 봇 관리자 콘솔에서, 배포하려면 게시된 봇과 작업을 승인해야 합니다.
- Node.js 다운로드 및 설치 – 테스트 애플리케이션의 봇과 Kore.ai 봇 플랫폼 간에 통신하기 위해 웹 SDK를 위한 JWT 토큰 생성 웹 서비스를 호스팅하는 데 사용되는 Node.js를 설치해야 합니다.
- 테스트 애플리케이션 다운로드 및 압축 해제 – 테스트 애플리케이션, SDKApp은 컴퓨터 로컬 호스트 서버를 사용하여 웹 페이지에서 채널로 Kore.ai 봇을 호스팅할 애플리케이션을 시뮬레이션하는 데 사용됩니다.
- Kore.ai 웹 SDK 다운로드 및 압축 해제 – 웹 SDK에는 웹/모바일 클라이언트 채널을 사용하여 테스트 애플리케이션에서 통신하고 봇을 실행하는 데 사용되는 라이브러리가 포함되어 있습니다. 컴퓨터의 index.html 파일에서 설정값을 설정해야 합니다.
- 애플리케이션 시작 및 웹 브라우저에서 봇 보기 – 터미널 창에서, JWT 서비스를 시작한 다음, 웹 브라우저에서 봇을 봅니다.
이제 단계별 구현에 대해 자세히 알아보겠습니다.
Kore.ai 웹 SDK 설치 및 실행하기
이 섹션에서는 웹 SDK와 로컬 호스트 서버 컴퓨터에서 실행 중인 테스트 애플리케이션을 사용한 Kore.ai 샘플 봇을 실행하는 방법을 자세히 설명합니다. 시작하려면, 테스트 애플리케이션에서 실행할 봇을 빌드한 다음 웹/모바일 클라이언트 채널에서 실행할 봇을 설정해야 합니다. 이 튜토리얼에서는, 샘플 봇을 설치하겠습니다(자세한 단계는 여기를 참조하세요)
- 봇 빌더에 로그인하고, +새 봇 옆에 있는 아래쪽 화살표를 클릭하고 샘플 봇 설치를 선택합니다.
- 여행 계획 샘플위로 마우스를 가져간 다음, 설치를 클릭합니다.
- 여행 계획 샘플이 성공적으로 설치됨 메시지가 표시되고 샘플 봇이 왼쪽 탐색 메뉴에 있는 봇에 추가됩니다.
이 다음 섹션에서는, 새 클라이언트 앱을 생성하고 채널 설정을 정의하여 여행 계획 샘플 봇을 위한 웹/모바일 클라이언트 채널을 정의합니다. 단계에 대한 자세한 설명은 여기를 참조하세요.
- 봇 빌더 상단 메뉴에서, 배포 탭을 선택합니다
- 왼쪽 메뉴에서, 연동 > 웹/모바일 SDK를 클릭합니다.
- 앱 선택 드롭다운 목록에서, 앱 생성을 클릭합니다. 클라이언트 앱 생성 대화 상자가 표시됩니다.
- 이름 필드에서, 앱의 이름을 입력합니다. 예: 내 SDK 클라이언트 앱.
- JWT 서명 알고리즘 섹션에서, HS256을 선택하여 인증 토큰을 생성합니다.
- 다음 -> 완료를 클릭합니다.
- 웹/모바일 클라이언트 채널 페이지는 다음 JWT 자격 증명과 함께 표시되며, 이러한 모든 세부 정보를 기록합니다. 나중에 웹 SDK 설정에서 사용할 것입니다.
- 봇 이름
- 봇 ID
- 클라이언트 ID
- 클라이언트 시크릿
- 저장을 클릭합니다.
이제 봇을 생성하고 웹/모바일 클라이언트 채널에 정의했으므로, 봇을 게시하고 배포할 준비가 되었습니다.
- 배포 탭에서, 봇 관리 -> 게시를 클릭합니다.
- 게시 페이지에서, 모든 작업을 선택한 다음, 계속을 클릭합니다.
- 의견을 입력하고 확인을 클릭하고 게시합니다.
엔터프라이즈 개발자가 봇을 게시한 후, 해당 봇을 승인하고 사용할 사용자에게 할당해야 합니다.
- 봇의 엔터프라이즈 관리자는 봇의 이용 대상이 엔터프라이즈 사용자 또는 일반 대중 중에 어느 것으로 설정되어 있는지에 따라 봇 관리자 콘솔에서 다음 봇 배포 중 하나를 완료해야 합니다. 다음 중 하나를 완료합니다.
- 봇 관리자 콘솔에서, 봇 관리 모듈의 엔터프라이즈 봇 페이지에서, 배포하려는 여행 계획 샘플 봇의 줄임표 아이콘을 클릭한 다음 봇 작업 관리를 클릭합니다. 봇 작업 관리 대화 상자가 표시됩니다.
- 봇 작업 필드에서, 확장 아이콘을 클릭하여 사용 가능한 작업과 배포 가능한 작업을 표시하고, 이 봇의 모든 작업을 선택한 다음 확인을 클릭합니다.
- 봇 작업 관리 대화 상자에서, 확인을 클릭합니다. 봇 상태가 성공적으로 변경됨 메시지가 표시됩니다.
- 엔터프라이즈 봇 페이지에서, 사용자를 할당하려는 여행 계획 샘플 봇의 줄임표 아이콘을 클릭한 다음 봇 및 작업 할당을 클릭합니다.
- 봇 및 작업 할당 대화 상자가 표시됩니다. 모든 작업에 대해 본인을 포함한 모든 사용자에게 봇을 할당합니다.
이제 웹 SDK와 로컬 호스트 서버에서 봇을 로컬로 실행하는 테스트 애플리케이션에 필요한 소프트웨어 패키지를 다운로드, 압축 해제, 설치 및 설정해야 합니다.
- 컴퓨터에 node.js를 다운로드하여 설치하려면, https://nodejs.org/en/download/로 이동한 다음, Mac의 경우 .pkg를, Windows의 경우 .msi를 선택합니다.
- 터미널 창에서,
node -v
명령어를 실행하여 설치 및 버전(예:v6.10.2
)을 확인합니다. - Kore 봇을 연동하려는 앱을 호스팅하는 웹 서버의 SDKApp/sdk 폴더를 찾습니다. 이 튜토리얼에서는, 테스트 애플리케이션과 JWT 웹 서비스를 다운로드하려면, SDKApp을 클릭하고 압축을 해제합니다.
- Kore.ai 웹 SDK를 다운로드하려면, https://github.com/Koredotcom/web-kore-sdk로 이동한 다음, 다운로드를 클릭합니다. 위의 단계에서 언급한 …/SDKApp/sdk 폴더로 모든 파일을 압축 해제합니다. 릴리스 정보에서 릴리스 호환성을 확인합니다.
- 배포 -> 채널 메뉴의 봇 빌더 웹/모바일 클라이언트 채널 페이지에서, 다음을 복사합니다(위의 8단계에서 언급한 대로):
- clientSecret
- clientId
- 봇 이름
- 플랫폼의 버전 7.2에서는, 웹 SDK repo 구조가 크게 변경되었습니다. 어떤 repo를 사용하느냐에 따라 단계가 다릅니다.
- 플랫폼 버전 7.2 이후(즉, 2020년 2월 이후) 다운로드한 최신 웹 SDK 파일의 경우 이 단계를 따르세요.
- 텍스트 편집기를 사용하여 …/SDKApp/sdk/UI 폴더에서 index.html 파일을 엽니다. UI 폴더에 대한 경로를 추가하여 다음 줄을 업데이트합니다:
- kore-config.js를 열고 botOptions 매개변수인 botInfo, clientId, clientSecret, 이메일 ID를 userIdentity로 업데이트합니다.
“clientSecret”: “{client secret}” $.ajax({ url: “http://localhost:3000/api/users/getJWT”, //this is sample url of a localhost. //This should include the url where you are hosting the bot. botOptions.userIdentity = ‘ ‘; // Provide users email id here botOptions.clientId= "{client id} "; // secure client-id _botOptions.botInfo= {name:"{bot name}","id":"{bot id"}; // Kore bot name is case sensitive })
JWTUrl은 앱이 호스팅 되는 위치(Kore.ai 봇을 연동하려는 위치)를 나타냅니다. 이 튜토리얼에서는, JWT 서버(19단계의 설정대로)를 사용하고 여기서도 동일하게 사용합니다.
- kore-config.js에서 봇의 이용 대상을 설정했는지 확인합니다. 다음 중 하나를 선택합니다.
"isAnonymous": < false >;
봇이 엔터프라이즈 사용자용으로 배포되고 다음과 같이 설정된 경우botOptions.userIdentity = '< Your email ID>';
– 또는 –"isAnonymous": < true >;
봇이 소비자 용으로 배포된 경우
- 텍스트 편집기를 사용하여 …/SDKApp/sdk/UI 폴더에서 index.html 파일을 엽니다. UI 폴더에 대한 경로를 추가하여 다음 줄을 업데이트합니다:
- 이 단계는 플랫폼 버전 7.2 이전(즉, 2020년 2월 이전)에 다운로드한 이전 Web SDK 파일에 유효합니다.
- 텍스트 편집기를 사용하여 …/SDKApp/sdk/UI 폴더에서 index.html 파일을 엽니다.
- UI 폴더에 대한 경로를 추가하여 다음 줄을 업데이트합니다:
<script src="libs/jquery.js" type="text/javascript"></script>
<script src="libs/jquery.tmpl.min.js" type="text/javascript"></script>
<script src="libs/jquery-ui.min.js" type="text/javascript"></script>
<link href="libs/jquery-ui.min.css" rel="stylesheet"></link>
<script src="chatWindow.js" type="text/javascript"></script>
<link href="chatWindow.css" rel="stylesheet"></link> - 로컬 호스트로 실행하려면 다음 매개변수를 업데이트합니다
“clientSecret”: “{client secret}” $.ajax({ url: “http://localhost:3000/api/users/getJWT”, //this is sample url of a local host. //This should include the url where you are hosting the bot. botOptions.userIdentity = ‘ ‘; // Provide users email id here botOptions.clientId= "{client id} "; // secure client-id _botOptions.botInfo= {name:"{bot name}","id":"{bot id"}; // Kore bot name is case sensitive })
참고: 위의 코드 조각에 언급된 URL은 앱이 호스팅되는 위치(Kore.ai 봇을 연동하려는 위치)를 나타냅니다. 이 튜토리얼에서는, JWT 서버(18단계의 설정대로)를 사용하고 여기서도 동일하게 사용합니다.
- 다음 중 하나를 선택합니다.
"isAnonymous": < false >;
봇이 엔터프라이즈 사용자용으로 배포되고 다음과 같이 설정된 경우botOptions.userIdentity = '< Your email ID>';
– 또는 –"isAnonymous": < true >;
봇이 소비자 용으로 배포된 경우
- UI 폴더에 대한 경로를 추가하여 다음 줄을 업데이트합니다:
- 텍스트 편집기를 사용하여 …/SDKApp/sdk/UI 폴더에서 index.html 파일을 엽니다.
- 플랫폼 버전 7.2 이후(즉, 2020년 2월 이후) 다운로드한 최신 웹 SDK 파일의 경우 이 단계를 따르세요.
- 변경 사항을 저장합니다. JWT 토큰 생성 서비스를 시작하고 로컬 웹 브라우저에서 설정된 웹 SDK를 사용하여 테스트 애플리케이션을 액세스할 준비가 되었습니다.
- 홈 디렉토리로 이동합니다
cd SDKApp
- 다음 명령어를 사용하여 종속성을 설치합니다
npm install
- SDKApp을 시작합니다
node startServer.js
- localhost:3000을 사용하여 모든 브라우저에서 애플리케이션에 액세스합니다
webSDK를 통해 데이터 전달하기
index.html 파일 내의 botInfo에서 사용자 정의 데이터를 추가하여 채널에 액세스하는 사용자의 추가 정보를 전달할 수 있습니다.
botOptions.botInfo = {name: "Banking Bot", "_id": "<bot_id>", customData: "value" };
전화번호, 주소 또는 위치 등과 같은 세부 정보는 customData 내부에서 전달할 수 있는 데이터의 예시입니다. customData
컨텍스트 개체의 BotUserSession
아래 lastMessage
에서 액세할 수 있습니다. 이 데이터는 webSDK를 사용하는 사용자에게만 해당되며 사용자 세션 동안 지속됩니다. 여러 값을 키-값 쌍으로 index.html
파일의 customData
에 추가할 수도 있습니다.
botOptions.botInfo = {name:"<bot_name>", "_id":"<bot_id", customData:{"name":"John", "age":30, "cars": {"car1":"Ford", "car2":"BMW", "car3":"Fiat" } } };
매핑된 ID 전달하기
웹/모바일 SDK는 사용자가 봇과 인터렉션 하는 동안 한 ID에서 다른 ID로 전환할 때 사용자의 매핑된 ID 전달을 지원합니다. 이 과정을 통해 사용자는 이전 ID를 사용하여 시작된 진행 중인 대화를 계속할 수 있습니다. 예를 들어, 사용자가 익명 또는 무작위로 생성된 ID를 사용하여 봇과 대화를 시작했을 수 있습니다. 메시지를 몇 개 교환한 후, 사용자는 웹 사이트 또는 애플리케이션에 로그인하여 인증된 사용자 또는 알려진 사용자가 될 수 있습니다. 이 시점에서, 사용자의 알려진 ID는 매개변수 identityToMerge를 사용하여 ‘JWT Grant API’ 호출의 일부로 SDK에서 봇으로 전달될 수 있습니다. 플랫폼은 이 정보를 사용하여 사용자 ID를 병합하고 사용자가 새로운 알려진 ID를 사용하여 진행 중인 대화를 재개할 수 있도록 합니다.
{ "iat": 1611810186883, "exp": 1611813786.883, "aud": "https://idproxy.kore.com/authorize", "iss": "cs-d3042d3e-7da4-55da-a94d-783349270cc0", "sub": "knowuser1@test.com", "isAnonymous": "false", "identityToMerge": "anonymoususer1@test.com" }
다음 시나리오는 새 ID 및 병합된 ID를 처리할 때 봇 행동을 설명합니다.
- 새 ID 및 병합된 ID가 시스템에 없는 경우, 새 ID가 생성되고 새 ID를 사용하여 새 대화가 시작됩니다.
- 시스템에 새 ID가 있지만 병합된 ID는 없는 경우, 새 ID를 사용하여 대화를 시작하거나 (활성 세션의 경우)계속합니다
- 시스템에 병합된 ID는 있지만 새 ID는 없는 경우, 새 ID가 생성되고 새 ID를 사용하여 대화가 계속됩니다. 병합된 ID에 대한 모든 참조는 새 ID로 대체되고 병합된 ID는 제거됩니다.
- 병합된 ID 및 새 ID가 모두 시스템에 있고 새 ID는 활성 세션이 없는 경우, 대화는 새 ID를 사용하여 계속됩니다. 병합된 ID에 대한 모든 참조는 새 ID로 대체되고 병합된 ID는 제거됩니다.
- 병합된 ID 및 새 ID가 모두 시스템에 있으면서 활성 세션이 있는 경우, 병합된 ID의 대화는 새 ID를 사용하여 계속됩니다. 병합된 ID에 대한 모든 참조는 새 ID로 대체되고 병합된 ID는 제거됩니다. 새 ID의 활성 세션이 "드롭오프"로 표시되고 종료됩니다
위에서 언급한 사용자 ID의 동작으로 인해 다음의 변경 사항이 확인될 수 있습니다.
- 병합된 ID와 관련된 모든 세션을 새 ID와 연결하여 분석 및 채팅 기록이 업데이트됩니다
- 병합된 ID를 새 ID로 대체하여 세션 데이터가 업데이트됩니다
- 병합된 ID의 대화를 추적하는 청구 세션은 새 ID로 표시됩니다
webSDK를 통한 메타 태그 사용자 정의
플랫폼 버전 8.0 릴리스로, 지원되는 모든 내부 채널(웹 SDK/IVR / IVRVoice / Webhook 채널)에서 직접 사용자 정의 메타 태그를 추가할 수 있습니다. 세션, 사용자, 메시지 수준 메타 태그를 정의할 수 있습니다. 이러한 태그는 생성되는 즉시 대화 세션에 추가됩니다.
botOptions.botInfo = {name:"<bot_name>", "_id":"<bot_id", customData :{"name":"John"}, "metaTags": { "messageLevelTags": [{ "name": "tag1", value: "message"}], "sessionLevelTags": [{ "name": "tag2", value: "session"}], "userLevelTags": [{ "name": "tag3", value: "user"}] } };
일반적으로 발생하는 몇 가지 오류들
- index.html에 잘못된 URL이 있으면, 사용자에게 404 오류가 표시됩니다. URL을 다시 확인합니다. 봇을 자체 웹 SDK 또는 Kore의 웹 SDK 중 어느 곳에서 호스팅하는지에 따라 URL이 변경됩니다. Kore 웹 SDK인 경우, URL은
http://demo.kore.net:3000/users/sts 7
입니다. 사내 웹 SDK에서 호스팅하는 경우, 해당 URL을 제공하세요. - 누락된/유효하지 않은 jwt.sub(): 이 오류는 사용자의 이메일 id가 index.html 파일에 지정되지 않은 경우, 엔터프라이즈 봇에서 발생합니다. index.html에서 아래와 같이 사용자 ID를 제공합니다
botOptions.userIdentity = ‘x@gmail.com’;// Provide users email id here.
- 찾을 수 없음: 잘못된 클라이언트 ID 또는 클라이언트 ID가 제공되지 않은 경우, 사용자에게 이 오류가 표시됩니다. 봇 – API 확장 옵션에서 클라이언트 ID가 올바른지 확인합니다
botOptions.clientId = “{clientID}”; // secure client-id
- jwt 확인 오류: 잘못된 클라이언트 시크릿이 index.html 파일에 제공되었습니다: 봇 – API 확장 옵션에서 얻은 클라이언트 시크릿이 올바른지 확인합니다
“clientSecret”: "{clientSecret}” //provide clientSecret here
테스트 애플리케이션과 로컬 호스트 서버를 사용하여 웹 SDK를 설치하고 테스트한 후, 동일한 개념으로 자신의 엔터프라이즈 애플리케이션에서 웹 SDK를 설치하고 설정할 수 있습니다. 귀하의 웹 사이트와 서버를 가리키도록 웹 SDK의 index.html 파일에 있는 파일 경로와 URL을 재설정하고, 엔터프라이즈를 위한 JWT 자격 증명을 사용한 웹/모바일 클라이언트 채널용 Kore.ai 봇을 설정해야 합니다.