공통 규칙 | Appbox SDK 가이드

공통 규칙

스크립트 넣기

웹 SDK 를 쓰려면 사이트의 모든 페이지에 스크립트 한 줄이 있어야 합니다.
사이트의 <head> 안에 아래 한 줄을 넣습니다.
HTML
1 <script src="https://console.appboxapp.com/import/appbox.v3.js"></script>
  • type="module" 로 넣지 마세요. SDK 는 자기 <script> 태그 주소를 읽어 앱 정보와 서버 주소를 스스로 설정하는데, 모듈 스크립트에서는 이 주소를 읽을 수 없어 인앱 메시지 같은 자동 기능이 켜지지 않습니다.
  • 두 번 넣어도 두 번째는 아무 일도 하지 않습니다. 앱이 SDK 를 따로 넣어 주는 경우와 겹쳐도 괜찮습니다.
  • 이 한 줄이 있는 페이지에서만 앱 기능을 부를 수 있습니다.

준비 시점

스크립트가 실행되면 바로 준비가 끝납니다. 준비가 끝나면 다음 세 가지가 동시에 일어납니다.
신호내용
AppboxSDK.isReadytrue
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 }

결과 받는 법

대부분의 함수는 마지막 인자로 콜백을 받고, 동시에 Promise 를 돌려줍니다. 둘 중 편한 쪽을 쓰면 됩니다.

기본 모양

상황콜백 (err, data)Promise
성공err 는 null, data 에 결과(대개 data.result, data.message)resolve { ack: true, ...data }
앱이 실패를 돌려줌(권한 거부, 사용자가 닫음 등)err.code, err.messageresolve { ack: false, error, code } (reject 하지 않음)
앱 밖(일반 브라우저)에서 부름err.code 가 NOT_APPBOXresolve { ack: false, error, code: "NOT_APPBOX" } (reject 하지 않음)
넘긴 값이 형식에 맞지 않음err.code 가 VALIDATIONreject (err.code 가 VALIDATION)
  • 콜백의 data 에는 ack 가 없습니다. ack 는 Promise 결과에만 있습니다.
  • 실패해도 Promise 가 reject 되지 않는 경우가 많습니다. await 결과의 ack 가 false 인지 꼭 확인하세요.
  • 입력값 오류만 reject 됩니다. 그래서 try 와 ack 확인을 함께 써야 모든 실패를 잡을 수 있습니다.

입력값 오류를 바로 던지는 함수

아래 함수는 메뉴 항목이나 이미지 항목 같은 배열 안의 값이 틀리면 Promise 를 돌려주기 전에 오류를 바로 던집니다(콜백도 불리지 않음). try 로 감싸 주세요.
함수바로 던지는 경우
gmenu.openTabsMenu메뉴 항목에 action 이 없음
gmenu.openHamburgerMenu메뉴 항목에 text 나 action 이 없음
gmenu.openBrowserMenu메뉴 항목의 function 이 허용 값이 아님
gmenu.openFloatingMenu메뉴 항목의 icon 이 없거나 http(s) 주소가 아님
ui.imageViewerOpenitem[].imageUrl 이 없거나 http(s) 주소가 아님
message.subscribeToTopic, message.unsubscribeFromTopictopicScheme 안에 빈 값
배열 자체가 없거나 개수가 틀린 경우는 위 기본 모양처럼 콜백과 reject 로 옵니다.

모양이 다른 함수

함수결과
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 아님)
앱 밖에서 부를 때 오류 코드가 함수마다 다릅니다. 대부분 NOT_APPBOX 이고, getDeviceUserId 와 journey.track 은 NO_DEVICE_ID, getDeviceInfo 는 오류 없이 빈 값입니다. 앱 안인지는 "앱 안인지 확인" 방법으로 먼저 확인하세요.

시간 제한

SDK 는 앱의 응답을 기다리는 시간 제한을 두지 않습니다. 응답이 올 때까지 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 }
함수를 run 으로 넘기는 이유: 위 "입력값 오류를 바로 던지는 함수"는 오류를 바로 던지므로 try 안에서 불러야 잡힙니다.

오류 코드

웹 SDK 가 만드는 코드입니다.
코드뜻받는 곳
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
앱이 실패를 돌려주면 앱의 코드(예: -1000 사용자가 취소, -7000 권한 거부)가 그대로 code 에 들어옵니다. 함수별 코드는 각 기능의 항목 정의를 보세요.

버전 확인

버전은 세 가지가 있습니다. 문의하실 때는 세 값을 함께 알려 주세요.
확인하는 법무엇의 버전
AppboxSDK.version웹 SDK(이 스크립트)
AppboxSDK.application.getSDKVersion()앱에 들어 있는 앱박스 네이티브 SDK
AppboxSDK.application.getAppVersion()고객 앱 자체

디버그 로그

SDK 는 고객 사이트에 들어가므로 평소에는 브라우저 콘솔에 아무것도 찍지 않습니다. 확인이 필요할 때만 켜세요.
방법범위
콘솔에서 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()통로 상태와 최근 호출 기록

앱 호출 기록의 토큰, 키, 이메일, 전화번호 같은 항목은 앞 네 글자만 보이게 가려집니다. 다른 로그는 가리지 않으니 운영 사이트에서는 확인이 끝나면 꺼 주세요.

www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.