AskAIs
무료로 시작하기
문서 둘러보기웹 위젯
가이드

웹 위젯

스크립트 태그 하나로 웹사이트에 AskAIs 채팅을 추가하고, 로그인한 방문자를 식별하고, 모양을 조정합니다.

코드의 window.SingChat 등은 위젯과 API의 기술 이름입니다. 적힌 그대로 사용하세요.

웹 위젯은 askais.com에서 제공되는 스크립트 widget.js 하나입니다. 페이지에 채팅 런처를 추가하고 Shadow DOM 안에 채팅 창을 그리므로, 사이트의 스타일과 위젯의 스타일이 서로 섞이지 않습니다.

사이트에 추가하기

채팅을 표시할 모든 페이지의 </body> 앞에 아래 코드를 붙여 넣으세요. App ID는 설정 → 받은 메시지함에 있습니다.

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

자체 사이트에서는 data-base-url이 필수입니다. 이 속성이 없으면 위젯이 askais.com 대신 여러분의 도메인에서 서버를 찾습니다.

⚠️ widget.js는 askais.com에서 불러오세요

widget.js를 내려받거나 자체 코드에 번들링하지 마세요. askais.com에서 불러오면 항상 최신 버전이 실행되지만, 복사본은 그 상태로 멈춰 이후의 수정 사항과 새 기능을 모두 놓치게 됩니다.

스크립트 속성

모든 설정은 스크립트 태그의 data- 속성으로 지정합니다:

  • data-app-id — 필수. 받은 메시지함의 App ID.
  • data-base-url — 사이트에서 필수. 항상 https://askais.com.
  • data-locale — 선택. 위젯 언어를 고정합니다(예: ja, zh-Hant). 생략하면 위젯은 방문자 기기의 언어를 따르고, 그다음으로 페이지의 lang을 따릅니다.
  • data-external-id — 로그인한 사용자를 가리키는 여러분 시스템의 ID.
  • data-email — 사용자의 이메일. 팀에 표시됩니다.
  • data-name — 사용자의 이름. 팀에 표시됩니다.
  • data-avatar-url — 사용자 프로필 사진 링크.
  • data-hmac — 신원 서명. 아래를 참고하세요.
  • data-attrs — JSON 형식의 추가 정보(예: {"plan":"Pro"}). 방문자 프로필에서 팀에 표시됩니다. 잘못된 JSON은 무시됩니다.

data-embed, data-platform, data-app-version, data-device-model은 앱 내 채팅 페이지가 설정합니다. 앱 내 채팅(WebView)을 참고하세요.

로그인한 방문자

로그인한 사용자라면 스크립트 태그에 사용자 정보를 추가하세요. 팀은 누구와 대화하는지 알 수 있고, 채팅은 사용자를 따라 다른 기기로 이어집니다:

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

data-external-id가 없으면 위젯은 브라우저마다 고유한 익명 ID를 부여해 브라우저의 로컬 스토리지에 저장합니다. 그래서 해당 브라우저에서는 페이지를 새로고침해도 채팅 기록이 유지됩니다. 받은 메시지함에 채팅 전 양식이 있으면, 익명 방문자는 채팅을 시작하기 전에 이를 작성합니다.

신원 확인(HMAC)

  • hmac은 받은 메시지함 시크릿 키를 키로 사용한 externalId의 HMAC-SHA256 값이며, 소문자 16진수로 표기합니다.
  • 서버에서 계산하세요. 시크릿 키는 절대 페이지나 앱에 넣지 않습니다.
  • 시크릿 키는 받은 메시지함을 만들 때 한 번 표시되고, 설정 → 받은 메시지함에서 교체할 때(해당 받은 메시지함의 ⋮ 메뉴 → 시크릿 키 교체) 다시 표시됩니다. sk_ 접두사를 포함한 키 전체를 사용하세요. 키를 교체하면 이전 서명은 모두 무효가 됩니다.
  • data-external-id는 항상 data-hmac과 함께 보내고, 바로 그 값에 서명하세요. 위젯은 항상 외부 ID를 보내므로(전달하지 않으면 익명 ID를 자동 생성), 이메일만으로 만든 서명으로는 아무도 인증되지 않습니다.
  • 서명이 틀리거나 없어도 채팅은 멈추지 않습니다. 방문자는 계속 대화할 수 있지만 미인증으로 처리됩니다. 미인증 정보는 페이지가 전달한 그대로 받아들이므로, 페이지를 수정할 수 있는 사람은 누구나 다른 사람인 척할 수 있습니다. 신원 확인 필수를 켜면 미인증 방문자는 익명 방문자로 처리되어 이전 대화를 볼 수 없습니다.

Node.js 예시:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

JavaScript로 위젯 시작하기

위젯을 직접 시작하려면(예: 페이지가 사용자가 누구인지 알게 된 뒤), data-app-id 없이 스크립트를 불러오고 로드가 끝난 뒤 window.SingChat.start()를 호출하세요:

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

스크립트가 제공하는 메서드는 start()뿐입니다. 위젯을 열거나 닫거나 이벤트를 수신하는 메서드는 없으며, 방문자는 런처에서 위젯을 엽니다.

모양과 동작

  • 설정 → 받은 메시지함에서 받은 메시지함을 펼치면 기본 색상과 텍스트 색상, 위치(오른쪽 아래 또는 왼쪽 아래), 버블 크기, 밝은 배경 또는 어두운 배경, 창 제목과 부제목을 실시간 미리보기와 함께 설정할 수 있습니다.
  • 채팅 전 양식(같은 위치): 채팅을 시작하기 전에 익명 방문자에게 이메일, 이름, 전화번호 또는 회사명을 묻습니다.
  • 허용된 출처(같은 위치): 이 받은 메시지함의 위젯을 불러올 수 있는 웹사이트입니다. 목록이 비어 있으면 모든 사이트를 허용합니다.
  • 위젯 브랜딩(같은 위치): 채팅 하단의 “Powered by” 문구입니다. 이 문구를 숨기거나 여기에 원하는 이름을 표시할 수 있는지는 요금제에 따라 다릅니다.
  • AI 환영 메시지는 AI 상담원에서, 클릭할 수 있는 FAQ 버블은 설정 → 자주 묻는 질문에서, 도움말 문서는 Help Center에서 설정합니다.

보안

  • App ID는 공개 정보이므로 HTML에 넣어도 안전합니다.
  • 받은 메시지함 시크릿 키는 서버에만 두어야 합니다.
  • 페이지가 사용자가 누구인지 알고 있다면 항상 신원 확인(HMAC)을 사용하세요.
  • 허용된 출처를 자체 도메인으로 제한해 다른 사이트에서 위젯을 불러오지 못하게 하세요.
이전MCP 서버(AI 에이전트)다음지식 베이스 (RAG)