트러블슈팅
Web SDK v2 연동 시 자주 겪는 문제와 해결법입니다.
아바타가 안 보입니다
컨테이너 요소의 크기가 없을 가능성이 큽니다. 아바타는 래퍼를 채우도록 그려지므로 0 × 0 래퍼는 아무것도
안 보입니다.
<div id="AIPlayerWrapper" style="width: 480px; height: 720px;"></div>
또한 init()가 정상 resolve됐는지 확인하세요 — AI 로드에 실패하면 reject됩니다.
아바타는 보이는데 소리가 안 납니다
브라우저는 사용자가 페이지와 상호작용하기 전까지 오디오를 막습니다.
첫 send()는 사용자 동작(클릭/탭)에서 호출하세요. 페이지 로드 시 바로 send()를 부르면 아바타는
나타나지 만 무음입니다.
button.onclick = () => AI_PLAYER.send("안녕하세요!");
generateToken이 실패합니다
| 증상 | 원인 | 해결 |
|---|---|---|
status가 "success"가 아님 | ClientToken이 유효하지 않거나 만료 됨 | 고객사 서버에서 ClientToken을 재발급하고 generateToken() 재호출 |
| 즉시 거부됨 | appId가 틀리거나 appId/토큰 불일치 | ClientToken 발급에 쓴 appId와 동일한지 확인 |
ClientToken을 브라우저에서 생성하지 마세요 — 장기 시크릿인 userKey가 필요합니다. 서버에서 생성해
단명 ClientToken만 클라이언트로 전달하세요.
토큰 만료(1402) / 무효(1407)
SDK는 이 코드를 onAIPlayerErrorV2로 올립니다. 토큰을 재발급하거나 release()를 호출하지 않습니다.
아바타는 화면에 두고 앱에서 코드를 처리하세요.
최신 v2 SDK는 1402 / 1407을 그 숫자 그대로 전달합니다. 구빌드는 같은 실패를 13000(init)으로
감쌀 수 있습니다.
| 코드 | 의미 | 할 일 |
|---|---|---|
1402 | 세션 JWT 만료 | 고객사 서버에서 ClientToken을 재발급하고 generateToken() 후 reconnect(). release() 하지 마세요. 옛 JWT로 reconnect만 반복하지 마세요. |
1407 | 토큰 무효(시크릿 불일치, 위조 JWT, ClientToken을 세션 JWT로 사용) | 재시도 루프에 넣지 마세요. 발급·전달 방식을 고치세요. |
AI_PLAYER.onAIPlayerErrorV2 = async (err) => {
if (err?.code === 1402) {
const { appId, token: clientToken } = await getClientToken();
await AI_PLAYER.generateToken({ appId, token: clientToken });
AI_PLAYER.reconnect();
return;
}
if (err?.code === 1407) {
console.error(err.code, err.message);
return;
}
console.error(err?.code, err?.message);
};
잠깐 끊기거나 1402에서 release()하면 세션이 끝납니다. release() 없이 reconnect하면 같은
세션이 이어집니다. release() 후 다음 init()은 새 세션입니다.
init에서 "아바타를 찾을 수 없음"
AI_PLAYER.getAIList()결과의result.data.ai[].ai_name에 해당 값이 있는지 확인하세요. UI 라벨은ai_display_name이고,init({ aiName })에는ai_name이 필요합니다.- 해당 아바타에 대한 계정 접근 권한이 있는지 확인하세요.
12000 — "The source image could not be decoded"
SDK가 이미지가 아닌 응답(대개 HTML/XML 404)을 이미지로 디코드하려다 난 오류입니다. 공개 npm 패키지
(npm install @deepbrainai/aihuman-web-sdk, latest)를 쓰는지, 폐기된 호스트로 resourceServer를
덮어쓰지 않았는지 확인하세요. 기본 리소스 호스트는 https://media.aistudios.com/sdk입니다.
발화가 시작됐다가 멈추거나 끊깁니다
- 브라우저 콘솔의 네트워크 에러를 확인하고 연결이 안정적인지 보세요.
onAIPlayerErrorV2를 수신해 에러code/message를 확인하세요.
아무것도 안 되고 콘솔에 에러가 납니다
에러/로그 훅을 붙여 출력을 지원팀과 공유하세요:
AI_PLAYER.onAIPlayerErrorV2 = (err) => console.error(err?.code, err?.message);
그래도 안 되면 콘솔 출력과 aiName을 첨부해 DeepBrain AI 지원팀에 문의하세요.