인앱 메시지, 푸시 마케팅 SDK 연동 | Appbox
메시지•인앱•푸시 마케팅
푸시 허용 등록
이를 통해 사용자 설정에 따라 푸시 메시지가 정상적으로 발송되거나 차단될 수 있도록 제어할 수 있어, 개인정보 동의 상태나 알림 설정 변화에 따른 정확한 메시지 발송이 가능합니다.
푸시 알림 허용 여부를 갱신
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| agree | 필수 | 푸시수신 동의 여부 (Y 또는 N). 이용자가 직접 고른 값을 넣으세요. | - | |
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
| err.code | 에러코드 ( -7000 : 권한 없음, -8000 : 서버 오류) |
| err.message | 에러 메시지 |
푸시를 수신하려면 사용자가 푸시 권한을 승인 하여야 합니다.
허용하지 않은 경우 위의 표기와 같이 err.code = -7000 시스템 권한 없음으로 리턴됩니다.
이런 경우 "앱 설정으로 이동 AppboxSDK.application.openAppSettings(); " 을 이용하여 사용자가 푸시 허용을 설정할 수 있도록 자동 이동 시킬 수 있습니다.
푸시 허용 여부
이를 통해 앱의 푸시 설정 페이지 등에서 푸시 수신여부 추기값을 ON 또는 OFF로 설정할 수 있습니다.
푸시 알림 허용 여부를 확인
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | Y : 허용, N : 거부 |
| err.code | 에러코드 (-8000 : 서버 오류) |
| err.message | 에러 메시지 |
data.result 값이 Y인 경우는 필히 푸시를 수신할 수 있는 경우입니다.
단, N으로 리턴 되는 경우는 OS 설정 에서 해당앱의 푸시를 거부하거나, 사용자가 앱에서 푸시를 거부 한 경우입니다.
사용자가 앱에서 푸시를 받겠다고 설정하여도 OS설정에서 푸시 거부가 되어 있는 상태라면, N으로 리턴됩니다.
푸시 토큰 요청
웹과 네이티브 간 연동을 통해 사용자 기기에서 토큰을 수신할 수 있는 기능으로, 앱 실행 시 또는 토큰이 필요한 시점에 호출하여 최신 토큰을 확보할 수 있습니다.
푸시 토큰 요청
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 사용자 디바이스 푸시 토큰 |
로컬 푸시 발송
네트워크가 연결되어 있지 않아도 알림을 바로 보여줄 수 있어, 예약 알림, 미션 완료 안내, 앱 내 이벤트 반응 등 즉각적인 피드백이 필요한 상황에 효과적으로 활용할 수 있습니다.
주요 내용을 로컬푸시로 알림
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| title | - | 제목 | ||
| message | 필수 | 메시지 내용 | ||
| targetUrl | - | 이동 URL | ||
| overlap | - | true: groupID가 동일하면 최종건 하나만 노출, false: 항상 쌓임 | false | |
| groupID | - | overlap의 항목과 함께 사용되는 그룹아이디 (0부터 9까지 숫자만 입력) | 0 | |
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
| err.code | 에러코드 ( -7000 : 권한 없음 ) |
| err.message | 에러 메시지 |
푸시를 수신하려면 사용자가 푸시 권한을 승인 하여야 합니다.
허용하지 않은 경우 위의 표기와 같이 err.code = -7000 시스템 권한 없음으로 리턴됩니다.
이런 경우 "앱 설정으로 이동 AppboxSDK.application.openAppSettings(); " 을 이용하여 사용자가 푸시 허용을 설정할 수 있도록 자동 이동 시킬 수 있습니다.
세그먼트 등록
콘솔에서 메시지를 발송할 때 세그먼트를 활용하면 전체 사용자에게 동일한 메시지를 보내는 대신, 관심사, 행동, 기록, 속성 등에 따라 대상자를 구분하여 더욱 관련성 높은 메시지를 전달할 수 있습니다.
segment를 이용하면 사용자의 관심사/행동/특성별로 그룹을 나누어 관련성 높은 메시지를 보내고, 관심사 등의 특성별로 고객 패턴 통계를 모니터링 할 수 있습니다.
개인화 세그먼트
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| segment | 필수 | segment 값에는 콘솔에서 정의한 json 파라미터가 key, value 형태로 들어가야 합니다. | ||
segment 의 값은 {key: value} 형태로 value는 string형 입니다. 여러항목이 들어가야 할때는 {key1: value, key2: value, key3:value...} 형태로 들어갑니다.
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
| err.code | 에러코드 (-8000 : 서버 오류) |
| err.message | 에러 메시지 |
메시지 구독 등록
메시지 구독 등록
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| topicScheme | 필수 | 구독 키값(단일 string 또는 string 배열) | ||
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result.succeeded | 구독 성공한 topic 키값 배열 |
| data.result.failed | 구독 실패한 topic 키값 배열 |
앱박스 콘솔 › 사용자 관리 › 구독 그룹에 먼저 등록한 값만 구독됩니다. 등록하지 않은 값은 구독되지 않고 data.result.failed 에 담겨 돌아옵니다.
메시지 구독 해지
메시지 구독 해지
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| topicScheme | 필수 | 구독 키값(단일 string 또는 string 배열) | ||
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result.succeeded | 구독 성공한 topic 키값 배열 |
| data.result.failed | 구독 실패한 topic 키값 배열 |
메시지 구독 갱신
메시지 구독 갱신
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| subscribe | 선택 | 구독할 토픽 키값 배열(string 배열, 최대 20개) | ||
| unsubscribe | 선택 | 해지할 토픽 키값 배열(string 배열, 최대 20개) | ||
* subscribe와 unsubscribe 중 최소 1개는 필수입니다. 같은 토픽 키값을 두 항목에 동시에 지정하면 요청 전체가 거부됩니다.
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result.subscribe.succeeded | 구독 성공한 topic 키값 배열 |
| data.result.subscribe.failed | 구독 실패한 topic 키값 배열 |
| data.result.unsubscribe.succeeded | 해지 성공한 topic 키값 배열 |
| data.result.unsubscribe.failed | 해지 실패한 topic 키값 배열 |
전환 이벤트 기록
이 기능은 메시지에 반응한 사용자가 최종 목표(참여, 가입, 구매 등)를 얼마나 달성했는지를 측정하는 데 활용되며, 캠페인 효과 분석과 퍼널 개선에 중요한 지표로 사용됩니다.
이벤트(푸시, 인앱 메시지)에 대한 전환 기록
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| conversionCode | 필수 | 콘솔에서 푸시 또는 인앱메시지를 발송시 생성되는 전환 코드를 입력하세요. | ||
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result | 성공 여부 (true | false) |
| err.code | 에러코드 (-8000 : 서버 오류) |
| err.message | 에러 메시지 |
전환 기록은 앱박스 콘솔로 전달되어 캠페인별 전환 성과를 집계하고 통계로 확인 할 수 있습니다.
푸시 수신 리스트
브릿지를 통해 웹페이지에서 네이티브에 저장된 푸시 수신 이력을 조회할 수 있습니다.
받은 푸시 메시지를 리스트로 가져오기
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 | |
|---|---|---|---|---|
| fromDate | - | 시작일(yyyyMMdd) | ||
| toDate | - | 종료일(yyyyMMdd) | ||
Response 항목 정의
| Response 결과값 | |
|---|---|
| data.result[].title | 제목 |
| data.result[].body | 메시지 내용 |
| data.result[].param | 파라미터 (URL 또는 파라미터 등) |
| data.result[].imageUrl | 푸시에 이미지가 포함되었을때 이미지 URL |
| data.result[].createdAt | 수신 일시(yyyy-MM-dd HH:mm, 기기 시간대) |
| err.code | 에러코드 (-3000 : toDate 만 줌, -3001 : 시작이 끝보다 늦음(iOS), -5000 : push 모듈 없음(Android), -8000, -9999 : 형식 오류, 조회 실패) |
data.result 는 최신순 배열입니다. 값이 없는 칸은 빈 문자열로 옵니다.
휴대폰 번호 등록
예제 코드
Request 항목 정의
| 항목 | 필수여부 | 설명 |
|---|---|---|
| phoneNumber | 필수 | 숫자, 공백, 하이픈, 괄호, 맨 앞 + 하나만. SDK 가 국제 형식으로 바꿔 보냅니다: 010... → +8210..., 82... → +82..., + 로 시작하면 그대로(기본 국가 한국). 국가번호 포함 8~15자리 |
| consent | - | 광고성 수신 동의. true 또는 "Y" 면 동의, 그 밖은 비동의. 빼면 보내지 않습니다 |
Response 항목 정의
| 결과값 | 설명 |
|---|---|
| data.result | 저장 성공이면 true |
| err.code | VALIDATION(번호 형식, 자릿수 오류, SDK 가 바로 거절), -8000(저장 실패), 앱 밖이면 NOT_APPBOX |
| err.message | 오류 메시지 |
- 콜백을 빼면 Promise 를 돌려줍니다("공통 규칙 › 결과 받는 법").
- Android SDK 1.3.35, iOS SDK 1.2.29 이상에서 동작합니다.
인앱 메시지
코드 없이 자동으로 보입니다
| 캠페인의 노출 조건 | 언제 뜨나 |
|---|---|
| 바로 노출 | 앱을 열거나 다시 앱으로 돌아왔을 때. 화면을 켜 둔 채로 있으면 1분 안에 한 번 더 확인 |
| URL 일치 | 지금 보는 웹 페이지 주소가 캠페인 조건과 맞을 때. 같은 페이지에서는 한 번만 |
| 푸시를 눌렀을 때 | 인앱을 연결한 푸시를 눌러 앱이 열렸을 때 |
| 브릿지 | 고객 코드가 inapp.trigger(이름) 를 불렀을 때(아래) |
- 노출 빈도(매번, 한 번만, 하루 한 번, N번)와 "오늘 하루 보지 않기"는 SDK 가 처리합니다.
- 이미 인앱이 떠 있으면 다음 인앱은 기다렸다가 먼저 것이 닫힌 뒤 뜹니다(겹쳐 뜨지 않음).
- 그달 인앱 사용량(MAU)을 넘으면 인앱이 보이지 않습니다. 계속 보이려면 인앱 크레딧을 충전하세요.
내 코드에서 특정 순간에 띄우기: inapp.trigger
- 이름이 같은 캠페인이 여럿이면 우선순위가 가장 높은 1건만 뜹니다.
- 결과를 돌려주지 않습니다. 맞는 캠페인이 없거나, 빈도와 "오늘 하루 보지 않기"로 걸러지면 아무 일도 일어나지 않습니다.
- 페이지를 연 직후 캠페인 목록을 받기 전에 부르면 맞는 캠페인을 못 찾을 수 있습니다. SDK 준비가 끝난 뒤 부르세요.
회원 연결과 서버 발송
전체 흐름
- 1. 회원이 로그인하면 웹 페이지에서 회원 ID 를 앱박스에 알립니다(setSegment). 콘솔의 회원 ID 조건 발송과 기기 찾기에 쓰입니다.
- 2. 같은 때 웹 페이지에서 기기 정보(getDeviceInfo)를 받아 고객사 서버에 저장합니다.
- 3. 고객사 서버는 저장한 푸시 토큰으로 앱박스 서버 API(/api/v1/push/individual)를 부릅니다.
회원 ID 알리기: setSegment
- 키 이름은 정확히 memberId 입니다(대소문자 그대로). 콘솔의 회원 ID 조건 발송과 기기 찾기가 이 키로 찾습니다.
- segment 는 { 키: 값 } 객체여야 합니다. 아니면 VALIDATION 으로 reject 됩니다.
- 값은 모두 문자열로 바뀌어 저장됩니다. null 이나 undefined 는 빈 문자열이 됩니다.
- 키에 공백, 점(.), $ 를 넣을 수 없고, 값이 JSON 객체나 배열 모양 문자열이면 서버가 받지 않습니다.
- 같은 호출에 다른 세그먼트(예: grade)를 함께 넣어도 됩니다. 콘솔 › 사용자 관리 › 세그먼트에 등록한 변수여야 메시지 개인화에 쓸 수 있습니다.
기기 정보 받기: getDeviceInfo
| 필드 | 뜻 |
|---|---|
| deviceUserId | 앱박스가 기기마다 만든 식별값 |
| pushToken | 푸시 토큰. 서버 API 의 data[].token 에 넣는 값 |
| message | 늘 빈 문자열 |
- 실패해도 오류가 오지 않습니다. 앱 밖이거나 아직 토큰이 없으면 값이 빈 문자열 "" 입니다. 빈 값을 서버로 보내지 않도록 위처럼 꼭 확인하세요.
- 결과에 ack 가 없습니다. 다른 함수와 다르니 info.ack 로 판정하지 마세요.
- OS 는 getDeviceInfo 에 없습니다. AppboxSDK.env().bridge("android", "ios")로 정해 서버 API 의 os_type(AOS, IOS)으로 저장하세요.
고객사 서버에 저장하기 (권장)
| 상황 | 권장 |
|---|---|
| 한 회원이 기기를 여러 대 씀 | 회원 하나에 기기 여러 행. deviceUserId 를 기준으로 덮어쓰기 |
| 토큰이 바뀜 | 로그인할 때마다, 그리고 앱을 열 때마다 다시 보내 최신 값으로 덮어쓰기 |
| 로그아웃 | 고객사 서버에서 그 기기 행을 지우거나 끊음 표시 |
| 기기를 다른 회원이 이어서 씀 | 새 회원 로그인 때 같은 deviceUserId 행을 새 회원으로 옮김 |
서버에서 보내기: 개별 푸시 API
- 미리 준비할 것 두 가지: 콘솔 › 메시지 발송 › 푸시 메시지 › API 설정에서 인증키 생성과 서버 공인 IP 등록. 하나라도 빠지면 HTTP 401 입니다. 등록할 IP 는 호출하는 서버에서 확인한 공인 IPv4 입니다.
- 인증키는 고객사 서버에만 두세요. 웹 페이지나 앱에 넣으면 안 됩니다.
- os_type 을 함께 보내세요. 빼면 앱박스가 토큰으로 기기를 찾는데, 등록되지 않은 토큰이 하나라도 있으면 요청 전체가 거절(본문 code 422)됩니다.
- 성공과 실패는 HTTP 상태가 아니라 본문의 success, code 로 구분합니다.
- 같은 요청을 다시 보내면 다시 발송되고 다시 차감됩니다. 응답을 못 받았다면 콘솔 › 성과 분석 › 푸시 발송 이력에서 나갔는지 먼저 확인하세요.
- 자세한 항목과 오류는 앱 설정 가이드 "서버 API" 문서를 보세요.