메인 콘텐츠로 바로가기

웹 SDK 프론트엔드 연동

SDK를 불러와 인증 버튼을 추가합니다.

1. 설치

페이지에 스크립트 태그를 넣습니다. 최신 버전은 1.0.0입니다.

HTML
<script src="https://octomo-sdk.octoverse.kr/1.0.0/octomo-sdk.js"
        integrity="sha384-BeD3ER8epnhfqXt/oJFleDWen4lGUYmrcxLmvblQGA//uXCZRESxI+ZXtQepvBrp"
        crossorigin="anonymous"></script>

2. 인증 버튼 추가

코드의 API_BASE를 고객사 백엔드 주소로 바꿉니다.

HTML
<div id="octomo-button"></div>

<!-- 1. SDK 불러오기 (integrity, crossorigin은 빼지 마세요) -->
<script src="https://octomo-sdk.octoverse.kr/1.0.0/octomo-sdk.js"
        integrity="sha384-BeD3ER8epnhfqXt/oJFleDWen4lGUYmrcxLmvblQGA//uXCZRESxI+ZXtQepvBrp"
        crossorigin="anonymous"></script>

<!-- 2. 인증 버튼 추가 -->
<script>
  // 고객사 백엔드 주소. 같은 도메인이면 '' 로 둡니다.
  const API_BASE = 'https://api.your-service.com';

  async function post(path, body) {
    const res = await fetch(API_BASE + path, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    const data = await res.json();
    if (!res.ok) throw new Error(data.message);
    return data;
  }

  Octomo.mount('#octomo-button', {
    // 번호 입력 후: 백엔드가 옥토모에서 발급받은 응답을 그대로 돌려줍니다.
    onPhoneSubmit: ({ phoneNumber }) => post('/verifications', { phoneNumber }),

    // 문자 수신 확인 후: 백엔드가 최종 확인하고 업무를 처리합니다.
    // await하면 실패 시 팝업에 오류가 표시되고 다시 시도할 수 있습니다.
    onComplete: async ({ verificationToken }) => {
      const { message } = await post('/verifications/consume', { verificationToken });
      console.log(message);
    },
  });
</script>

⚠ SDK 화면의 완료는 인증 결과가 아닙니다.

onComplete는 브라우저에서 실행되어 조작될 수 있습니다. 인증 성공은 백엔드의 최종 확인 응답으로만 판단하세요. 백엔드 연동 보기 →

3. 옵션

mount()와 open()은 같은 옵션을 받고 { destroy() }를 반환합니다.

SDK 옵션
옵션필수 여부설명
onPhoneSubmit({ phoneNumber })필수고객사 서버의 발급 응답을 반환하는 Promise
onComplete({ verificationToken })필수verificationToken을 고객사 서버로 보내 최종 확인합니다. 재시도하면 같은 토큰으로 다시 호출됩니다
onError(error)선택발급에 실패했을 때
onClose()선택팝업이 닫힐 때

더 알아보기

버전 목록

최신 버전

복사 버튼으로 태그 전체 또는 integrity 값만 복사할 수 있습니다. 파일을 열려면 버전을 클릭합니다.

웹 SDK 최신 버전
SDK버전배포일
스크립트1.0.02026-11-18
ES 모듈1.0.02026-11-18
  • * 이전 버전 파일도 CDN에 그대로 남아 쓰던 주소는 계속 동작합니다.
  • * 호환되지 않는 변경은 공지사항의 업데이트로 알립니다.

변경 이력

웹 SDK 변경 이력
버전변경 날짜변경 이력
1.0.02026-11-18
  • 첫 정식 버전

ES 모듈로 불러오기

번들러나 <script type="module">을 쓴다면 import로 불러옵니다.

HTML
<script type="importmap">
  {
    "integrity": {
      "https://octomo-sdk.octoverse.kr/1.0.0/octomo-sdk.esm.js": "sha384-OFFooKgnP1U/5OksMYalwG3KIN0h/H0WERzFXdUPTXN5UTMJm6yfbtfjSfIdN6I0"
    }
  }
</script>
<script type="module">
  import * as Octomo from 'https://octomo-sdk.octoverse.kr/1.0.0/octomo-sdk.esm.js';

  Octomo.mount('#octomo-button', { /* 위와 같은 옵션 */ });
</script>

내 버튼 쓰기

mount() 대신 open()을 클릭 핸들러에서 호출합니다.

JavaScript
document.getElementById('my-button').onclick = () => Octomo.open(options);

버튼 꾸미기

버튼은 octomo-mount와 ::part(button)으로 꾸밉니다. 팝업은 바꿀 수 없습니다.

CSS
/* 너비, 위치 */
octomo-mount {
  width: 280px;
  margin: 12px auto;
}

/* 높이, 글자 크기, 모서리, 색 */
octomo-mount::part(button) {
  padding: 9px;
  font-size: 13px;
  border-radius: 999px;
}

페이지 CSP 설정

Content-Security-Policy를 쓰는 페이지만 해당합니다.

CSP에 추가할 값
지시어추가할 값
script-srchttps://octomo-sdk.octoverse.kr
connect-srchttps://api.octoverse.kr (프론트와 다르면 고객사 백엔드 도메인도)
img-srcdata: (QR 이미지)

Safari 16.3 이하를 지원해야 하면 style-src에 'unsafe-inline'도 필요합니다.

자주 겪는 문제

증상별 해결 방법
증상원인과 해결
버튼이 나오지 않음, Octomo is not definedSDK 로드 실패입니다. 주소의 버전과 integrity가 맞는지, crossorigin="anonymous"가 있는지 확인합니다
CSP 오류위의 CSP 값을 추가합니다. .map 파일 경고는 무시해도 됩니다
'다음'을 눌러도 진행되지 않음onPhoneSubmit이 백엔드의 발급 응답을 그대로 반환하는지 확인합니다

다음: 백엔드 연동 →

OCTOMO

주식회사 옥토버스

대표 김종민

사업자 등록번호 803-88-02517

서울특별시 영등포구 국회대로36길 6-1, 2층 디599호

고객센터 1666-3538

이메일 hercules@octoverse.kr