공통 규칙 | Appbox SDK 가이드
공통 규칙
스크립트 넣기
HTML
1 <script src="https://console.appboxapp.com/import/appbox.v3.js"></script>
- type="module" 로 넣지 마세요. SDK 는 자기 <script> 태그 주소를 읽어 앱 정보와 서버 주소를 스스로 설정하는데, 모듈 스크립트에서는 이 주소를 읽을 수 없어 인앱 메시지 같은 자동 기능이 켜지지 않습니다.
- 두 번 넣어도 두 번째는 아무 일도 하지 않습니다. 앱이 SDK 를 따로 넣어 주는 경우와 겹쳐도 괜찮습니다.
- 이 한 줄이 있는 페이지에서만 앱 기능을 부를 수 있습니다.
준비 시점
| 신호 | 내용 |
|---|---|
| AppboxSDK.isReady | true |
| window 이벤트 appboxsdk:ready | 한 번 발생(event.detail 에 version, env) |
| AppboxSDK.whenReady(fn) | 이미 준비된 상태라 fn 을 바로 실행 |
- appboxsdk:ready 는 스크립트가 실행되는 순간 한 번만 발생합니다. 이 이벤트를 쓰려면 SDK 스크립트 앞에서 리스너를 등록해야 합니다.
- AppboxSDK.whenReady 는 SDK 가 로드된 뒤에만 있습니다. SDK 보다 먼저 실행되는 코드에서는 아래처럼 나눠 쓰세요.
Javascript
1 function onAppboxReady(fn) {
2 if (window.AppboxSDK && window.AppboxSDK.isReady) {
3 fn(window.AppboxSDK);
4 return;
5 }
6 window.addEventListener("appboxsdk:ready", function () {
7 fn(window.AppboxSDK);
8 }, { once: true });
9 }
10
11 onAppboxReady(function (sdk) {
12 console.log("앱박스 SDK 준비", sdk.version);
13 });
앱 안인지 확인
| 방법 | 결과 | 특징 |
|---|---|---|
| AppboxSDK.application.isAppBoxSDK() | true 또는 false (바로 돌려줌) | 브라우저 User Agent 에 appbox 가 있는지만 봅니다. 앱을 부르지 않습니다 |
| AppboxSDK.env().bridge | "android", "ios", "none" | 앱과 통신할 통로가 실제로 있는지 봅니다 |
Javascript
1 if (AppboxSDK.application.isAppBoxSDK()) {
2 // 앱 안에서만 할 일
3 } else {
4 // 일반 브라우저에서 할 일
5 }
결과 받는 법
기본 모양
| 상황 | 콜백 (err, data) | Promise |
|---|---|---|
| 성공 | err 는 null, data 에 결과(대개 data.result, data.message) | resolve { ack: true, ...data } |
| 앱이 실패를 돌려줌(권한 거부, 사용자가 닫음 등) | err.code, err.message | resolve { ack: false, error, code } (reject 하지 않음) |
| 앱 밖(일반 브라우저)에서 부름 | err.code 가 NOT_APPBOX | resolve { ack: false, error, code: "NOT_APPBOX" } (reject 하지 않음) |
| 넘긴 값이 형식에 맞지 않음 | err.code 가 VALIDATION | reject (err.code 가 VALIDATION) |
- 콜백의 data 에는 ack 가 없습니다. ack 는 Promise 결과에만 있습니다.
- 실패해도 Promise 가 reject 되지 않는 경우가 많습니다. await 결과의 ack 가 false 인지 꼭 확인하세요.
- 입력값 오류만 reject 됩니다. 그래서 try 와 ack 확인을 함께 써야 모든 실패를 잡을 수 있습니다.
입력값 오류를 바로 던지는 함수
| 함수 | 바로 던지는 경우 |
|---|---|
| gmenu.openTabsMenu | 메뉴 항목에 action 이 없음 |
| gmenu.openHamburgerMenu | 메뉴 항목에 text 나 action 이 없음 |
| gmenu.openBrowserMenu | 메뉴 항목의 function 이 허용 값이 아님 |
| gmenu.openFloatingMenu | 메뉴 항목의 icon 이 없거나 http(s) 주소가 아님 |
| ui.imageViewerOpen | item[].imageUrl 이 없거나 http(s) 주소가 아님 |
| message.subscribeToTopic, message.unsubscribeFromTopic | topicScheme 안에 빈 값 |
모양이 다른 함수
| 함수 | 결과 |
|---|---|
| AppboxSDK.getDeviceInfo() | { deviceUserId, pushToken, message }. ack 없음. 실패해도 오류가 없고 값이 빈 문자열 "" 입니다(앱 밖에서도 같음) |
| AppboxSDK.getDeviceUserId() | 성공 { result, message }(ack 없음), 실패 { ack: false, error, code: "NO_DEVICE_ID" } |
| AppboxSDK.journey.track() | { ok, status } 또는 { ok: false, error } |
| message.updateTopics() | 일부라도 실패하면 reject(UPDATE_TOPICS_PARTIAL, 상세는 err.result). 앱 밖에서 부르면 reject 하지 않고 { ack: false, code: "NOT_APPBOX" } |
| application.isAppBoxSDK() | true 또는 false 를 바로 돌려줌(Promise 아님) |
시간 제한
권장 코드
Javascript
1 async function callAppbox(run) {
2 try {
3 const res = await run();
4 if (res && res.ack === false) {
5 return { ok: false, code: res.code, message: res.error };
6 }
7 return { ok: true, data: res };
8 } catch (err) {
9 return { ok: false, code: err.code, message: err.message };
10 }
11 }
12
13 const r = await callAppbox(function () {
14 return AppboxSDK.application.getAppVersion();
15 });
16 if (r.ok) {
17 console.log("앱 버전", r.data.result);
18 } else {
19 console.warn("실패", r.code, r.message);
20 }
오류 코드
| 코드 | 뜻 | 받는 곳 |
|---|---|---|
| NOT_APPBOX | 앱 밖(일반 브라우저)에서 부름 | 콜백 err, Promise { ack: false } |
| VALIDATION | 넘긴 값이 형식에 맞지 않음 | 콜백 err 와 reject(배열 항목 오류는 바로 던짐) |
| NO_BRIDGE | 앱 통로는 보이는데 그 기능을 받을 곳이 없음 | 콜백 err 와 reject |
| NATIVE_ERROR | 앱이 코드 없이 실패를 돌려줌 | 콜백 err, Promise { ack: false } |
| NO_DEVICE_ID | 기기 식별값을 받지 못함(앱 밖 포함) | getDeviceUserId, journey.track |
| UPDATE_TOPICS_PARTIAL | 구독 그룹 갱신 중 일부 실패 | updateTopics reject(err.result) |
| INVALID_EVENT_KEY, UNKNOWN_EVENT_KEY, SERVER_REJECTED, INVALID_PROPERTIES, NO_APP_ID, NETWORK | 여정 이벤트 오류 | journey.track 의 error |
버전 확인
| 확인하는 법 | 무엇의 버전 |
|---|---|
| AppboxSDK.version | 웹 SDK(이 스크립트) |
| AppboxSDK.application.getSDKVersion() | 앱에 들어 있는 앱박스 네이티브 SDK |
| AppboxSDK.application.getAppVersion() | 고객 앱 자체 |
디버그 로그
| 방법 | 범위 |
|---|---|
| 콘솔에서 window.__appboxVerbose = true | 지금 페이지에서 바로 |
| localStorage.setItem("appbox:verbose", "1") | 새로고침해도 유지(끌 때는 localStorage.removeItem("appbox:verbose")) |
| window.addEventListener("appboxsdk:log", fn) | 콘솔을 켜지 않고 SDK 로그를 받아 직접 표시(event.detail 에 level, msg, data, ts) |
| window.__appboxDebug.getStatus(), getHistory() | 통로 상태와 최근 호출 기록 |
앱 호출 기록의 토큰, 키, 이메일, 전화번호 같은 항목은 앞 네 글자만 보이게 가려집니다. 다른 로그는 가리지 않으니 운영 사이트에서는 확인이 끝나면 꺼 주세요.