InspireMe - 명언 서비스

위젯 사용 중 문제가 발생하면 아래 가이드를 참고하세요.

위젯이 표시되지 않는 경우

1. 스크립트 URL 확인

스크립트 src 경로가 정확한지 확인하세요.

<!-- 올바른 URL -->
<script src="https://inspireme.advenoh.pe.kr/widget/embed.js"></script>

2. CSP(Content Security Policy) 설정

웹사이트에 CSP 정책이 설정되어 있다면 InspireMe 도메인을 허용해야 합니다.

Content-Security-Policy:
  script-src 'self' https://inspireme.advenoh.pe.kr;
  connect-src 'self' https://inspireme.advenoh.pe.kr;
  style-src 'self' 'unsafe-inline';

3. JavaScript 에러 확인

브라우저 개발자 도구(F12)의 Console 탭에서 에러 메시지를 확인하세요.

4. HTTPS 필수

위젯 스크립트는 HTTPS를 통해서만 로드됩니다. HTTP 사이트에서는 mixed content 경고가 발생할 수 있습니다.

스타일이 깨지는 경우

Shadow DOM 미지원

매우 오래된 브라우저에서는 Shadow DOM이 지원되지 않아 스타일이 호스트 페이지와 충돌할 수 있습니다. 최신 브라우저에서 확인해 주세요.

위젯 크기 문제

위젯이 너무 크거나 작다면 data-width와 data-max-width 속성을 조절하세요.

<script
  src="https://inspireme.advenoh.pe.kr/widget/embed.js"
  data-type="quote-of-the-day"
  data-width="100%"
  data-max-width="400px"
></script>

Web Component 관련

커스텀 태그가 인식되지 않는 경우

<inspireme-quote> 태그가 동작하지 않으면 스크립트 로드 순서를 확인하세요. 스크립트가 태그보다 먼저 로드되어야 합니다.

<!-- 올바른 순서: 스크립트 먼저 -->
<script src="https://inspireme.advenoh.pe.kr/widget/inspireme-quote.js"></script>
<inspireme-quote type="quote-of-the-day"></inspireme-quote>

또는 defer 사용 시 DOMContentLoaded 이후에 자동 등록됩니다.

프레임워크에서 사용 시 주의사항

React: JSX에서 Web Component를 사용하면 타입 경고가 발생할 수 있습니다. declare 선언을 추가하세요.

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'inspireme-quote': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
        type?: string; lang?: string; theme?: string;
      };
    }
  }
}

Vue / Angular: 별도 설정 없이 바로 사용 가능합니다.

Rate Limiting

위젯 API는 IP당 분당 60회 호출 제한이 있습니다. 일반적인 사용에서는 문제가 되지 않지만, 트래픽이 매우 높은 사이트에서는 캐싱이 자동 적용됩니다.

플랫폼별 가이드

WordPress

테마 편집기 또는 Custom HTML 블록에 위젯 코드를 붙여넣으세요.

Tistory

HTML 모드에서 위젯 코드를 삽입하세요. 사이드바 위젯으로 추가할 수도 있습니다.

Notion

Notion은 외부 스크립트 실행을 지원하지 않아 위젯을 넣을 수 없습니다.

추가 지원

문제가 해결되지 않으면 GitHub Issues에 문의해 주세요.

문제 해결