웹 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() }를 반환합니다.
| 옵션 | 필수 여부 | 설명 |
|---|---|---|
| onPhoneSubmit({ phoneNumber }) | 필수 | 고객사 서버의 발급 응답을 반환하는 Promise |
| onComplete({ verificationToken }) | 필수 | verificationToken을 고객사 서버로 보내 최종 확인합니다. 재시도하면 같은 토큰으로 다시 호출됩니다 |
| onError(error) | 선택 | 발급에 실패했을 때 |
| onClose() | 선택 | 팝업이 닫힐 때 |
더 알아보기
버전 목록
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를 쓰는 페이지만 해당합니다.
| 지시어 | 추가할 값 |
|---|---|
| script-src | https://octomo-sdk.octoverse.kr |
| connect-src | https://api.octoverse.kr (프론트와 다르면 고객사 백엔드 도메인도) |
| img-src | data: (QR 이미지) |
Safari 16.3 이하를 지원해야 하면 style-src에 'unsafe-inline'도 필요합니다.
자주 겪는 문제
| 증상 | 원인과 해결 |
|---|---|
버튼이 나오지 않음, Octomo is not defined | SDK 로드 실패입니다. 주소의 버전과 integrity가 맞는지, crossorigin="anonymous"가 있는지 확인합니다 |
| CSP 오류 | 위의 CSP 값을 추가합니다. .map 파일 경고는 무시해도 됩니다 |
| '다음'을 눌러도 진행되지 않음 | onPhoneSubmit이 백엔드의 발급 응답을 그대로 반환하는지 확인합니다 |