문제 해결

위젯 통합 및 사용을 위한 일반적인 문제 및 해결책.

문제가 발생했나요? 당신은 올바른 곳에 있습니다. 이 가이드는 위젯 통합 시 개발자가 자주 겪는 문제와 단계별 해결책을 다룹니다. 대부분의 문제는 몇 분 안에 해결할 수 있습니다.

🔍 빠른 디버깅 팁

문제를 해결하기 전에 브라우저의 개발자 콘솔(F12)을 엽니다. 대부분의 위젯 오류는 문제를 직접 지적하는 명확한 메시지를 콘솔에 표시합니다.

위젯이 페이지에 전혀 나타나지 않으면 다음 문제 해결 단계를 순서대로 따르세요:

❌ 문제: 위젯 스크립트가 로드되지 않음

오류: "위젯이 구성되지 않음" (누락된 각 data-* 속성에 대한 세부정보 포함)

이 오류 메시지에 대한 브라우저 콘솔을 확인하세요.

✅ 해결책: 필수 속성 확인

스크립트 태그에 모든 필수 데이터 속성이 있는지 확인하세요:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ 문제: 인증 실패

오류: "인증 필요" 또는 "잘못된 자격 증명"

위젯이 API와 인증되지 않습니다. 이는 일반적으로 자격 증명이 잘못되었거나 만료되었을 때 발생합니다.

✅ 해결책: OAuth 구성 확인

인증 문제는 일반적으로 간단하게 해결할 수 있습니다. 다음 검사를 진행하세요:

client_id가 OAuth 애플리케이션에서 올바른지 확인하세요 - 오타를 피하기 위해 대시보드에서 직접 복사하세요.
대시보드에서 OAuth 앱이 활성화되어 있고 비활성화되지 않았는지 확인하세요.
OAuth 앱에 적절한 리디렉션 URI가 구성되어 있는지 확인하세요 - 위젯 도메인이 허용되어야 합니다.
백엔드의 CORS 설정에서 위젯 도메인이 허용되는지 확인하세요.
최근에 자격 증명을 재생성한 경우 새 값을 사용하고 있는지 확인하세요.

아직도 막혔나요? 대시보드에서 새 OAuth 애플리케이션을 생성해 보세요. 때때로 새로 시작하는 것이 불명확한 구성 문제를 해결합니다.

❌ 문제: /api/v1/auth/widget-token이 400을 반환합니다 (출처가 허용되지 않음)

오류: "출처가 허용되지 않음" 또는 위젯 토큰 요청이 거부됨

iframe에 포함할 때 호스트 도메인이 OAuth 허용 출처에 나열되지 않은 경우 일반적입니다.

✅ 해결책: 호스트 출처와 OAuth 허용 목록 정렬

귀하의 포함 페이지 출처(예: http://localhost:3000)를 OAuth allowed_origins에 추가하세요.
전체 스킴 + 호스트 (+ 포트) 형식을 사용하고 후행 경로는 생략하세요.
iframe에 포함할 때 토큰 호출이 X-Embed-Origin에 호스트 페이지 출처를 포함하는지 확인하세요.
요청 URL이 /api/v1/auth/widget-token인지 확인하세요 (레거시 경로가 아님).

검증 팁: 브라우저 네트워크 탭에서 토큰 요청 헤더를 확인하고 X-Embed-Origin을 OAuth allowed_origins 항목과 비교하세요.

❌ 문제: 위젯이 축소되어 있지만 버튼이 보이지 않음

버튼 위치 문제

위젯이 로드되지만 버튼이 뷰포트 밖에 있습니다.

✅ 해결책: 구성 위치 확인

위젯 구성 위치 설정을 확인하세요.
position: fixed와 CSS 충돌이 있는지 확인하세요.
부모 컨테이너에 overflow: hidden이 없도록 하세요.

❌ 문제: 모바일에서 위젯이 숨겨짐

✅ 해결책: 모바일 설정 조정

구성에서 hide_on_mobile가 활성화되어 있으면 위젯이 모바일 장치에서 숨겨집니다. 이 설정을 비활성화하거나 모바일 중단점을 조정하세요.

스타일 문제

시각적 문제는 일반적이며 보통 쉽게 해결할 수 있습니다. 위젯은 페이지와 시각적으로 격리되도록 설계되었지만 때때로 충돌이 발생할 수 있습니다.

❌ 문제: 색상이 적용되지 않음

✅ 해결책: 캐시 지우기 및 구성 확인

색상 문제를 진단하기 위해 다음 단계를 따르세요:

브라우저 캐시를 지우고 페이지를 새로 고침하세요 (Ctrl+Shift+R 또는 Cmd+Shift+R로 하드 새로 고침)
색상 값이 유효한 16진수 코드인지 확인하세요 (반드시 #로 시작하고 6자여야 하며, 예: #FF5733)
구성이 대시보드에 저장되었는지 확인하세요 - "저장됨" 확인을 찾으세요.
올바른 구성을 편집하고 있는지 확인하세요 - 구성 ID가 스크립트 태그와 일치하는지 확인하세요.
저장 후 몇 초 기다리세요 - 구성 변경 사항이 전파되는 데 5-10초가 걸릴 수 있습니다.

디버그 팁: 브라우저에서 위젯을 열고 요소 검사 도구를 사용하여 실제로 적용되고 있는 CSS 값을 확인하세요. 이렇게 하면 색상이 로드되고 있는지 또는 덮어쓰여지고 있는지를 알 수 있습니다.

❌ 문제: 글꼴이 로드되지 않음

✅ 해결책: 글꼴 구성

글꼴 패밀리가 "system-ui" 또는 웹 안전 글꼴로 설정되어 있는지 확인하세요.
사용자 정의 글꼴은 CORS 제한으로 인해 로드되지 않을 수 있습니다.
지원되는 글꼴 두께 값을 확인하세요.

기능 문제

위젯이 올바르게 로드되지만 기능이 예상대로 작동하지 않을 때 이러한 해결책이 도움이 됩니다.

❌ 문제: 메시지가 전송되지 않음

네트워크 오류, 시간 초과 또는 세션 만료

사용자가 메시지를 입력하고 전송을 클릭하지만 아무 일도 일어나지 않거나 오류가 나타납니다. 실패한 요청에 대해 브라우저 네트워크 탭을 확인하세요 (네트워크 탭에서 빨간색으로 표시되어야 합니다).

✅ 해결책: 세션 및 네트워크 확인

메시지 전송 문제는 일반적으로 네트워크 연결 또는 만료된 세션과 관련이 있습니다. 체계적으로 진단하세요:

API 엔드포인트에 접근할 수 있는지 확인하세요 - 브라우저에서 API URL에 직접 접근해 보세요.
인증 토큰이 유효한지 확인하세요 - 네트워크 탭에서 401/403 오류를 찾으세요.
세션이 만료되지 않았는지 확인하세요 - 세션은 일반적으로 비활동 상태에서 30분 동안 지속됩니다.
네트워크 연결 문제를 확인하세요 - 인터넷 연결이 안정적인가요?
콘솔에서 CORS 오류를 찾으세요 - 이는 귀하의 도메인이 화이트리스트에 없을 수 있음을 나타냅니다.
방화벽/보안 소프트웨어가 API를 차단하고 있지 않은지 확인하세요 - 기업 네트워크는 때때로 외부 API를 차단합니다.

빠른 테스트: 메시지가 시크릿 창에서는 작동하지만 일반 브라우저에서는 작동하지 않는 경우, 문제는 브라우저 확장 프로그램이나 캐시된 인증 데이터와 관련이 있을 가능성이 높습니다.

❌ 문제: 대화 흐름이 작동하지 않음

✅ 해결책: 흐름 구성 유효성 검사

트리거 키워드가 정확히 일치하는지 확인하세요.
흐름 응답이 올바르게 구성되었는지 확인하세요.
버튼 작업이 유효한지 확인하세요.

성능 문제

❌ 문제: 위젯이 느리게 로드됨

✅ 해결책: 로딩 최적화

개발 대신 프로덕션 빌드를 사용하세요.
정적 자산에 대한 브라우저 캐싱을 활성화하세요.
사용자 정의 CSS 및 이미지를 최소화하세요.
중요하지 않은 경우 지연 로딩을 고려하세요.

❌ 문제: 높은 메모리 사용량

✅ 해결책: 자원 사용량 줄이기

메시지 기록 길이를 제한하세요.
이미지 및 미디어를 최적화하세요.
사용하지 않는 기능을 비활성화하세요.

브라우저 호환성

❌ 문제: 구형 브라우저에서 위젯이 작동하지 않음

✅ 해결책: 브라우저 지원 확인

위젯은 현대 브라우저 기능이 필요합니다:

ES6+ 자바스크립트 지원
PostMessage API
CSS Grid 및 Flexbox
현대 iframe 기능

최소 지원 브라우저: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

도움 받기

이 가이드 외에 추가 지원이 필요할 때, 이러한 도구와 리소스가 문제를 진단하거나 지원을 받을 수 있도록 도와줍니다.

디버그 모드

디버그 모드를 활성화하여 브라우저 콘솔에서 자세한 로깅을 확인하세요. 이는 위젯이 각 단계에서 수행하는 작업에 대한 통찰력을 제공합니다:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

브라우저 개발자 도구

JavaScript 오류에 대한 콘솔 탭 확인
실패한 요청에 대한 네트워크 탭 확인
로컬 저장소 문제에 대한 애플리케이션 탭 확인
요소 탭을 사용하여 위젯 DOM 검사

일반적인 디버그 단계

브라우저 캐시 및 쿠키 지우기
시크릿/개인 브라우징 모드에서 시도하기
다른 브라우저로 테스트하기
네트워크 연결 확인하기
모든 구성 값 확인하기

아직도 문제가 있나요?

우리의 구성 가이드 를 확인하거나 브라우저 콘솔 로그 및 구성 세부정보와 함께 지원에 문의하세요.

뒤로

문제 해결

위젯 통합 및 사용을 위한 일반적인 문제 및 해결책.

🔍 빠른 디버깅 팁

문제를 해결하기 전에 브라우저의 개발자 콘솔(F12)을 엽니다. 대부분의 위젯 오류는 문제를 직접 지적하는 명확한 메시지를 콘솔에 표시합니다.

위젯이 페이지에 전혀 나타나지 않으면 다음 문제 해결 단계를 순서대로 따르세요:

❌ 문제: 위젯 스크립트가 로드되지 않음

오류: "위젯이 구성되지 않음" (누락된 각 data-* 속성에 대한 세부정보 포함)

이 오류 메시지에 대한 브라우저 콘솔을 확인하세요.

✅ 해결책: 필수 속성 확인

스크립트 태그에 모든 필수 데이터 속성이 있는지 확인하세요:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ 문제: 인증 실패

오류: "인증 필요" 또는 "잘못된 자격 증명"

위젯이 API와 인증되지 않습니다. 이는 일반적으로 자격 증명이 잘못되었거나 만료되었을 때 발생합니다.

✅ 해결책: OAuth 구성 확인

인증 문제는 일반적으로 간단하게 해결할 수 있습니다. 다음 검사를 진행하세요:

client_id가 OAuth 애플리케이션에서 올바른지 확인하세요 - 오타를 피하기 위해 대시보드에서 직접 복사하세요.
대시보드에서 OAuth 앱이 활성화되어 있고 비활성화되지 않았는지 확인하세요.
OAuth 앱에 적절한 리디렉션 URI가 구성되어 있는지 확인하세요 - 위젯 도메인이 허용되어야 합니다.
백엔드의 CORS 설정에서 위젯 도메인이 허용되는지 확인하세요.
최근에 자격 증명을 재생성한 경우 새 값을 사용하고 있는지 확인하세요.

아직도 막혔나요? 대시보드에서 새 OAuth 애플리케이션을 생성해 보세요. 때때로 새로 시작하는 것이 불명확한 구성 문제를 해결합니다.

❌ 문제: /api/v1/auth/widget-token이 400을 반환합니다 (출처가 허용되지 않음)

오류: "출처가 허용되지 않음" 또는 위젯 토큰 요청이 거부됨

iframe에 포함할 때 호스트 도메인이 OAuth 허용 출처에 나열되지 않은 경우 일반적입니다.

✅ 해결책: 호스트 출처와 OAuth 허용 목록 정렬

귀하의 포함 페이지 출처(예: http://localhost:3000)를 OAuth allowed_origins에 추가하세요.
전체 스킴 + 호스트 (+ 포트) 형식을 사용하고 후행 경로는 생략하세요.
iframe에 포함할 때 토큰 호출이 X-Embed-Origin에 호스트 페이지 출처를 포함하는지 확인하세요.
요청 URL이 /api/v1/auth/widget-token인지 확인하세요 (레거시 경로가 아님).

검증 팁: 브라우저 네트워크 탭에서 토큰 요청 헤더를 확인하고 X-Embed-Origin을 OAuth allowed_origins 항목과 비교하세요.

❌ 문제: 위젯이 축소되어 있지만 버튼이 보이지 않음

버튼 위치 문제

위젯이 로드되지만 버튼이 뷰포트 밖에 있습니다.

✅ 해결책: 구성 위치 확인

위젯 구성 위치 설정을 확인하세요.
position: fixed와 CSS 충돌이 있는지 확인하세요.
부모 컨테이너에 overflow: hidden이 없도록 하세요.

❌ 문제: 모바일에서 위젯이 숨겨짐

✅ 해결책: 모바일 설정 조정

구성에서 hide_on_mobile가 활성화되어 있으면 위젯이 모바일 장치에서 숨겨집니다. 이 설정을 비활성화하거나 모바일 중단점을 조정하세요.

스타일 문제

시각적 문제는 일반적이며 보통 쉽게 해결할 수 있습니다. 위젯은 페이지와 시각적으로 격리되도록 설계되었지만 때때로 충돌이 발생할 수 있습니다.

❌ 문제: 색상이 적용되지 않음

✅ 해결책: 캐시 지우기 및 구성 확인

색상 문제를 진단하기 위해 다음 단계를 따르세요:

브라우저 캐시를 지우고 페이지를 새로 고침하세요 (Ctrl+Shift+R 또는 Cmd+Shift+R로 하드 새로 고침)
색상 값이 유효한 16진수 코드인지 확인하세요 (반드시 #로 시작하고 6자여야 하며, 예: #FF5733)
구성이 대시보드에 저장되었는지 확인하세요 - "저장됨" 확인을 찾으세요.
올바른 구성을 편집하고 있는지 확인하세요 - 구성 ID가 스크립트 태그와 일치하는지 확인하세요.
저장 후 몇 초 기다리세요 - 구성 변경 사항이 전파되는 데 5-10초가 걸릴 수 있습니다.

❌ 문제: 글꼴이 로드되지 않음

✅ 해결책: 글꼴 구성

글꼴 패밀리가 "system-ui" 또는 웹 안전 글꼴로 설정되어 있는지 확인하세요.
사용자 정의 글꼴은 CORS 제한으로 인해 로드되지 않을 수 있습니다.
지원되는 글꼴 두께 값을 확인하세요.

기능 문제

위젯이 올바르게 로드되지만 기능이 예상대로 작동하지 않을 때 이러한 해결책이 도움이 됩니다.

❌ 문제: 메시지가 전송되지 않음

네트워크 오류, 시간 초과 또는 세션 만료

✅ 해결책: 세션 및 네트워크 확인

메시지 전송 문제는 일반적으로 네트워크 연결 또는 만료된 세션과 관련이 있습니다. 체계적으로 진단하세요:

API 엔드포인트에 접근할 수 있는지 확인하세요 - 브라우저에서 API URL에 직접 접근해 보세요.
인증 토큰이 유효한지 확인하세요 - 네트워크 탭에서 401/403 오류를 찾으세요.
세션이 만료되지 않았는지 확인하세요 - 세션은 일반적으로 비활동 상태에서 30분 동안 지속됩니다.
네트워크 연결 문제를 확인하세요 - 인터넷 연결이 안정적인가요?
콘솔에서 CORS 오류를 찾으세요 - 이는 귀하의 도메인이 화이트리스트에 없을 수 있음을 나타냅니다.
방화벽/보안 소프트웨어가 API를 차단하고 있지 않은지 확인하세요 - 기업 네트워크는 때때로 외부 API를 차단합니다.

❌ 문제: 대화 흐름이 작동하지 않음

✅ 해결책: 흐름 구성 유효성 검사

트리거 키워드가 정확히 일치하는지 확인하세요.
흐름 응답이 올바르게 구성되었는지 확인하세요.
버튼 작업이 유효한지 확인하세요.

성능 문제

❌ 문제: 위젯이 느리게 로드됨

✅ 해결책: 로딩 최적화

개발 대신 프로덕션 빌드를 사용하세요.
정적 자산에 대한 브라우저 캐싱을 활성화하세요.
사용자 정의 CSS 및 이미지를 최소화하세요.
중요하지 않은 경우 지연 로딩을 고려하세요.

❌ 문제: 높은 메모리 사용량

✅ 해결책: 자원 사용량 줄이기

메시지 기록 길이를 제한하세요.
이미지 및 미디어를 최적화하세요.
사용하지 않는 기능을 비활성화하세요.

브라우저 호환성

❌ 문제: 구형 브라우저에서 위젯이 작동하지 않음

✅ 해결책: 브라우저 지원 확인

위젯은 현대 브라우저 기능이 필요합니다:

ES6+ 자바스크립트 지원
PostMessage API
CSS Grid 및 Flexbox
현대 iframe 기능

최소 지원 브라우저: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

도움 받기

이 가이드 외에 추가 지원이 필요할 때, 이러한 도구와 리소스가 문제를 진단하거나 지원을 받을 수 있도록 도와줍니다.

디버그 모드

디버그 모드를 활성화하여 브라우저 콘솔에서 자세한 로깅을 확인하세요. 이는 위젯이 각 단계에서 수행하는 작업에 대한 통찰력을 제공합니다:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

브라우저 개발자 도구

JavaScript 오류에 대한 콘솔 탭 확인
실패한 요청에 대한 네트워크 탭 확인
로컬 저장소 문제에 대한 애플리케이션 탭 확인
요소 탭을 사용하여 위젯 DOM 검사

일반적인 디버그 단계

브라우저 캐시 및 쿠키 지우기
시크릿/개인 브라우징 모드에서 시도하기
다른 브라우저로 테스트하기
네트워크 연결 확인하기
모든 구성 값 확인하기

아직도 문제가 있나요?

우리의 구성 가이드 를 확인하거나 브라우저 콘솔 로그 및 구성 세부정보와 함께 지원에 문의하세요.

뒤로

문제 해결

위젯이 로드되지 않음

❌ 문제: 위젯 스크립트가 로드되지 않음

✅ 해결책: 필수 속성 확인

❌ 문제: 인증 실패

✅ 해결책: OAuth 구성 확인

❌ 문제: /api/v1/auth/widget-token이 400을 반환합니다 (출처가 허용되지 않음)

✅ 해결책: 호스트 출처와 OAuth 허용 목록 정렬

위젯이 보이지 않음

❌ 문제: 위젯이 축소되어 있지만 버튼이 보이지 않음

✅ 해결책: 구성 위치 확인

❌ 문제: 모바일에서 위젯이 숨겨짐

✅ 해결책: 모바일 설정 조정

스타일 문제

❌ 문제: 색상이 적용되지 않음

✅ 해결책: 캐시 지우기 및 구성 확인

❌ 문제: 글꼴이 로드되지 않음

✅ 해결책: 글꼴 구성

기능 문제

❌ 문제: 메시지가 전송되지 않음

✅ 해결책: 세션 및 네트워크 확인

❌ 문제: 대화 흐름이 작동하지 않음

✅ 해결책: 흐름 구성 유효성 검사

성능 문제

❌ 문제: 위젯이 느리게 로드됨

✅ 해결책: 로딩 최적화

❌ 문제: 높은 메모리 사용량

✅ 해결책: 자원 사용량 줄이기

브라우저 호환성

❌ 문제: 구형 브라우저에서 위젯이 작동하지 않음

✅ 해결책: 브라우저 지원 확인

도움 받기

디버그 모드

브라우저 개발자 도구

일반적인 디버그 단계

문제 해결

위젯이 로드되지 않음

❌ 문제: 위젯 스크립트가 로드되지 않음

✅ 해결책: 필수 속성 확인

❌ 문제: 인증 실패

✅ 해결책: OAuth 구성 확인

❌ 문제: /api/v1/auth/widget-token이 400을 반환합니다 (출처가 허용되지 않음)

✅ 해결책: 호스트 출처와 OAuth 허용 목록 정렬

위젯이 보이지 않음

❌ 문제: 위젯이 축소되어 있지만 버튼이 보이지 않음

✅ 해결책: 구성 위치 확인

❌ 문제: 모바일에서 위젯이 숨겨짐

✅ 해결책: 모바일 설정 조정

스타일 문제

❌ 문제: 색상이 적용되지 않음

✅ 해결책: 캐시 지우기 및 구성 확인

❌ 문제: 글꼴이 로드되지 않음

✅ 해결책: 글꼴 구성

기능 문제

❌ 문제: 메시지가 전송되지 않음

✅ 해결책: 세션 및 네트워크 확인

❌ 문제: 대화 흐름이 작동하지 않음

✅ 해결책: 흐름 구성 유효성 검사

성능 문제

❌ 문제: 위젯이 느리게 로드됨

✅ 해결책: 로딩 최적화

❌ 문제: 높은 메모리 사용량

✅ 해결책: 자원 사용량 줄이기

브라우저 호환성

❌ 문제: 구형 브라우저에서 위젯이 작동하지 않음

✅ 해결책: 브라우저 지원 확인

도움 받기

디버그 모드

브라우저 개발자 도구

일반적인 디버그 단계