앱 UX·알림·인터랙션 설계 가이드 | Appbox SDK
사용자 경험•알림•인터페이스
생체 인증
Touch ID 또는 Face ID를 활용해 특정 화면이나 기능 실행 전 사용자 인증을 요청할 수 있으며, 인증 결과는 웹으로 전달됩니다.
생체정보 인증하기
AppboxSDK.application.biometricAuth(...)
Javascript
1
// 생체 인증
2
AppboxSDK.application.biometricAuth( { haptic : true
}, (err, data) => {
3
if (err) {
4
console.error(
"생체 인증 실패:",
"code:", err.code,
"message:", err.message
);
5
} else {
6
console.log(
"생체 인증 OK:",
data.result
);
7
}
8
});
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| haptic | - | 성공 또는 실패시 진동 햅틱 (true, false) | ||
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
| err.code | 에러코드 (-1000 : 사용자가 닫음, -7000 : 권한 없음) |
| err.message | 에러 메시지 |
생체인증을 사용하려면, 생체인증을 지원하는 디바이스 이여야 하며, 생체인증이 등록되어 있어야 합니다.
생체인증이 등록되지 않은 경우 또는 카메라 권한을 승인하지 않은 경우 err.code=-7000 으로 리턴됩니다.
토스트 메시지
메시지를 토스트로 알리며 메시지 유지시간, 백그라운드 칼라, 텍스트 사이즈를 자유롭게 설정할 수 있습니다.
토스트 메시지 띄우기
AppboxSDK.application.toastShow(...)
Javascript
1
// 토스트 메시지
2
AppboxSDK.application.toastShow(
3
{
4
delaySecond: 3.5,
5
message: "정상적으로 완료되었습니다.",
6
fontSize: 12,
7
textColor: "#FFFFFF",
8
backColor: "#000000",
9
haptic: true
10
}, (err, data) => {
11
if (err) {
12
console.error(
"토스트 실패:",
"code:", err.code,
"message:", err.message
);
13
} else {
14
console.log(
"토스트 OK:",
data.result
);
15
}
16
});
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| delaySecond | 필수 | 유지 시간 (초), 0으로 설정시 토스트 사라지지 않으며 터치하면 사라집니다. | ||
| message | 필수 | 메시지 | ||
| fontSize | - | 텍스트 사이즈 | 12 | |
| textColor | - | 텍스트 칼라 | #FFFFFF | |
| backColor | - | 백그라운드 칼라 | #000000 | |
| haptic | - | 토스트 메시지시 햅틱 진동 여부 | true | |
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
앱 업데이트
앱스토어에 새 버전의 앱이 있다면 업데이트 팝업을 띄워 사용자가 최신 버전으로 업데이트 하도록 유도할 수 있으며, 사용자에게 선택적으로 ‘권장 업데이트’로 노출하거나, 또는 필수로 업데이트를 요청하는 ‘강제 업데이트’ 방식으로 설정할 수 있습니다.
앱을 최신 버전으로 업데이트
AppboxSDK.application.updatePrompt(...)
Javascript
1
// 앱 업데이트 팝업
2
AppboxSDK.application.updatePrompt(
3
{
4
require: false,
5
message: "마켓에 새로운 버전이 있습니다. 업데이트하시겠어요?",
6
appStore: "https://apps.apple.com/app/id1234567890",
7
googlePlay: "https://play.google.com/store/apps/details?id=com.example.app",
8
updateButton: "업데이트",
9
cancelButton: "나중에",
10
updateAlert: true
11
}, (err, data) => {
12
if (err) {
13
console.error(
"업데이트 안내(권장) 실패:",
"code:", err.code,
"message:", err.message
);
14
} else {
15
console.log(
"업데이트 안내(권장) OK:",
data.result
);
16
}
17
});
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| require | 필수 | true :강제, false : 권장 (새로운 버전을 업데이트 하지 않으면 앱 진입을 들어가지 못하도록 강제하거나, 업데이트를 권장만 하고 앱 진입은 가능하도록 할 수 있습니다.) | ||
| message | 필수 | 업데이트 메시지, 예) "마켓에 새로운 버전이 있습니다. 업데이트하여 주세요." | ||
| appStore | 필수 | 애플 앱스토어 앱 다운로드 URL 입력 - ex) https://apps.apple.com/kr/app/id{Apple ID} - Apple ID 확인 방법 : https://apps.apple.com/kr/iphone/charts (위 링크에서 해당 앱을 검색하여 URL 링크에서 Apple ID를 확인하세요.) |
||
| googlePlay | 필수 | 구글 플레이 앱 다운로드 URL 입력 - ex) https://play.google.com/store/apps/details?id={패키지명} - 패키지명 확인 방법 : https://play.google.com (위 링크에서 해당 앱을 검색하여 URL 링크에서 패키지명을 확인하세요.) |
||
| updateButton | 필수 | 업데이트 버튼의 텍스트 ex) 업데이트 하기, 앱 업데이트 | ||
| cancelButton | - | 취소 버튼의 텍스트 (require 항목의 값이 false 일때 필수) ex) 다음에, 그냥 입장 | ||
| updateAlert | - | 업데이트가 필요할때 메시지얼럿을 어디서 띄울지 선택 (true : AppBox에서 띄움, false : 웹에서 띄움), 권장 false | true | |
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
| err.code | 에러코드 ( -6000 : 마켓에 해당 앱이 존재 하지 않음, 마켓에 등록하지 않은 상태에서 테스트하는 경우 발생) |
| err.message | 에러 메시지 |
로딩 인디케이터
웹페이지 로딩 시 웹페이지의 로딩 상태를 시각적으로 표시하는 애니메이션을 지원합니다. 화면이 진행중 일때 다른 터치로 인해 오작동을 막고, 웹페이지가 확실히 실행되고 있다는 신뢰를 줄 수 있습니다.
로딩 인디케이터
AppboxSDK.application.loadingShow(...)
Javascript
1
// 로딩 인디케이터
2
AppboxSDK.application.loadingShow(
3
{
4
loadingIcon: "https://www.appboxapp.com/app/load0.gif",
5
sizePercentage: 30,
6
backColor: "#99554bff"
7
}, (err, data) => {
8
if (err) {
9
console.error(
"로딩 실패:",
"code:", err.code,
"message:", err.message
);
10
} else {
11
console.log(
"로딩 표시 OK:",
data.result
);
12
}
13
});
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| loadingIcon | 필수 | 로딩시 노출될 gif 이미지 URL | ||
| sizePercentage | 필수 | 아이콘 크기(화면 가로 폭 대비 %) | ||
| backColor | - | 로딩 아이콘 노출시 dimmed되는 화면의 백그라운드 칼라, Alpha 값은 기본 10% | #000000 | |
로딩 인디케이 아이콘 이미지는 한번 다운로드 받은 후 앱내 저장되어 다시 변경전까지 사용됩니다.
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
진동 울리기
짧은 진동부터 강한 햅틱까지, 진동의 강도와 횟수, 길이를 자유롭게 설정할 수 있어 상황에 맞는 감각적 피드백을 제공할 수 있습니다. 이 기능을 활용하면 사용자 행동에 즉각적인 반응을 줄 수 있어, 인터랙션의 몰입감과 전달력을 크게 높일 수 있습니다.
진동으로 알림을 명확하게
AppboxSDK.application.vibrate(...)
Javascript
1
// 진동 울리기
2
AppboxSDK.application.vibrate(
3
{
4
vibrationCount: 2,
5
type: "haptic"
6
}, (err, data) => {
7
if (err) {
8
console.error(
"진동 실패:",
"code:", err.code,
"message:", err.message
);
9
} else {
10
console.log(
"진동 OK:",
data.result
);
11
}
12
});
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| vibrationCount | 필수 | 진동 횟수 | ||
| type | 필수 | 진동 타입 (haptic: 햅틱, short: 짧게, long: 길게) | ||
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
앱 설정으로 이동
웹에서 브릿지를 호출하면 OS의 앱 설정 화면이 즉시 열리기 때문에, 사용자가 메뉴를 직접 찾아갈 필요 없이 바로 필요한 권한을 수정할 수 있어 편리한 환경을 제공합니다.
OS의 앱 설정으로 이동
AppboxSDK.application.openAppSettings()
Javascript
1
// 앱 설정으로 이동
2
AppboxSDK.application.openAppSettings( (
err, data
) => {
3
if (err) {
4
console.error(
"앱 설정으로 이동 실패:",
"code:", err.code,
"message:", err.message
);
5
} else {
6
console.log(
"앱 설정으로 이동 OK:",
data.result
);
7
}
8
});
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
키보드 내리기
예를 들어 댓글 입력 후 전송 버튼이 보이지 않거나 다음 입력 요소가 가려질 경우, 키보드를 내려 화면을 다시 편하게 볼 수 있도록 도와줍니다. 이 기능은 사용자의 입력 흐름을 자연스럽게 이어주고, UI 사용성을 높여줍니다.
키보드가 화면을 가릴때 키보드 내리기
AppboxSDK.application.closeKeyboard()
Javascript
1
// 키보드 내리기
2
AppboxSDK.application.closeKeyboard( (
err, data
) => {
3
if (err) {
4
console.error(
"키보드 내리기 실패:",
"code:", err.code,
"message:", err.message
);
5
} else {
6
console.log(
"키보드 내리기 OK:",
data.result
);
7
}
8
});
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
핀치 줌
boolean 값 하나로 웹뷰의 확대/축소 허용 여부를 네이티브에 전달합니다.
브릿지로 변경한 값은 SDK 내부 저장소에 보관되며, 이후 웹뷰 생성/페이지 로드 시에도 계속 재적용됩니다.
SDK 기본값은 비활성화입니다.
ui.setZoomEnabled 가져오기
AppboxSDK.ui.setZoomEnabled(enabled)
Javascript
1
// ui.setZoomEnabled - 핀치 줌 활성화(비활성화는 첫 번째 인자에 false 전달)
2
AppboxSDK.ui.setZoomEnabled( { enabled : true }, (
err, data
) => {
3
if (err) {
4
console.error(
"setZoomEnabled 실패:",
"code:", err.code,
"message:", err.message
);
5
} else {
6
console.log(
"setZoomEnabled 결과:",
data.enabled
);
7
}
8
});
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| enabled | - | 핀치 점 허용 여부. (true/false) | 요청값 생략시 true(SDK 최초 상태는 false) | |
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.enabled | 적용된 줌 허용 여부. 예) true |
| err.code | 에러코드 |
| err.message | 에러 메시지 |
동작 설명
- 설정은 호출 즉시 현재 WebView에 반영되며 새로고침이 필요하지 않습니다.
- 마지막 설정값은 SDK 내부 저장소에 보관되며 앱 재실행, 화면 복귀, 페이지 이동 및 새 WebView 생성 시 다시 적용됩니다.
- SDK 최초 상태는 핀치 줌 비활성화입니다.
앱 평가
팝업 형태로 평가 화면을 표시해 사용자 피드백을 수집하고, 스토어 평점을 높일 수 있도록 유도할 수 있습니다. 적절한 타이밍에 활용하면 사용자 만족도와 서비스 신뢰도를 함께 높일 수 있습니다.
마켓의 앱 평가 점수 올리기
AppboxSDK.application.reviewRequest()
Javascript
1
// 앱 평가
2
AppboxSDK.application.reviewRequest( (
err, data
) => {
3
if (err) {
4
console.error(
"앱 평가 실패:",
"code:", err.code,
"message:", err.message
);
5
} else {
6
console.log(
"앱 평가 OK:",
data.result
);
7
}
8
});
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
앱의 평가 팝업은 매번 요청시 마다 띄워지지 않습니다.
App의 Review API는 사용자의 활동기록에 의한 호출 횟수 제한이 있으며 평가 기록 여부, 최소 조건 충족 여부, Apple 및 Google의 내부 정책에 의해 띄워집니다.
호출시 매번 띄워지지 않으며, 사용자가 불편을 느끼지 않는 경우에만 표시됩니다.
앱 종료
브릿지를 호출하면 실행 중인 앱을 안전하게 종료하며, 모든 프로세스를 정리해 완전한 종료 상태로 처리됩니다.
앱을 강제 종료
AppboxSDK.application.exit()
Javascript
1
// 앱 종료
2
AppboxSDK.application.exit( (
err, data
) => {
3
if (err) {
4
console.error(
"앱 종료 요청 실패:",
"code:", err.code,
"message:", err.message
);
5
} else {
6
console.log(
"앱 종료 요청 완료:",
data.result
);
7
}
8
});
호출 하면 바로 앱이 종료됩니다. "종료 하시겠습니까?" 등 Confirm 박스를 띄우고 종료(브릿지 호출)하는게 자연스럽습니다.