이벤트 호출 | Appbox 앱 설정 가이드

이벤트 호출

이벤트는 앱박스에서 사용자 행동과 상태 변화를 수집하고 활용하기 위한 기본 데이터 단위입니다.
이벤트는 사용자 여정, 알림 메시지 전환 이벤트, 인앱 메시지 노출 시점 등 다양한 곳에서 사용됩니다.
본 문서를 통해 클라이언트 앱 또는 서버에서 이벤트를 호출하여 앱박스 콘솔에 등록한 이벤트와 연동할 수 있으며, 이벤트와 함께 속성값 전달 방법까지 확인할 수 있습니다.

사전 확인

  • 이벤트 호출 전에 앱박스 콘솔에서 사용할 이벤트를 먼저 등록해야 합니다.
  • 요청에 포함하는 eventKey는 콘솔에 등록된 이벤트 키와 정확히 일치해야 합니다.
  • 속성값을 조건으로 사용할 예정이라면 콘솔에서 이벤트 조건에 사용할 속성키를 완전 일치하게 생성해야 합니다.

호출 방식

이벤트 호출은 서버 호출과 앱 내 웹페이지 JS 호출 두 가지 방식을 지원합니다.
하나의 이벤트는 한 채널에서만 발사하는 것을 권장하며, 동일 이벤트를 두 채널에서 동시에 보내면 중복 처리 위험이 있습니다.
채널 권장 상황 대표 예시
백엔드 호출 위변조 차단, DB 트랜잭션 정합성이 필요한 경우 결제 완료, 회원가입 완료 등
JS 호출 백엔드 부담 없이 즉시성이 중요한 UX 이벤트 페이지 조회, 상품 조회, 배너 클릭 등

서버 API

서버에서 이벤트 API를 호출할 때는 Basic 인증을 사용합니다.
아이디 자리에 인증키, 비밀번호 자리에 앱 프로젝트 ID(콘솔 › 앱 정보)를 넣습니다(별도 Secret 은 없습니다). 인증키는 푸시 API 와 같은 키입니다(콘솔 › 푸시 메시지 › API 설정).
인증키는 환경변수에 저장하고, 코드에 직접 하드코딩하지 않는 것을 권장합니다.
HTTP
1 Authorization: Basic {Base64(AUTH_KEY:APP_PROJECT_ID)}
2 Content-Type: application/json
cURL에서는 -u 옵션으로 인증키와 앱 프로젝트 ID를 간단히 전달할 수 있습니다.
Bash
1 -u $APPBOX_AUTH_KEY:$APPBOX_APP_PROJECT_ID
서버 이벤트 API Endpoint는 다음과 같습니다.
HTTP
1 POST https://api.appboxapp.com/api/v1/server/journey/event

Request 항목 정의

Request 항목 필수 여부 설명
events 필수 전송할 이벤트 목록입니다. 배열 형태로 전달합니다.
한 번의 요청에 최대 100건까지 포함할 수 있습니다.
events[].eventId 선택 이벤트 고유 ID입니다.
생략 시 서버가 자동 생성하지만, 재시도 중복 방지를 위해 UUID 등 고유값을 직접 생성하는 것을 권장합니다.
events[].userId 조건부 고객사 회원 ID입니다. deviceUserId 미전달 시 fallback 값으로 사용됩니다.
events[].deviceUserId 권장 실제 매칭 기준이 되는 디바이스 사용자 식별자입니다.
모바일 SDK에서 받은 값을 함께 전달하면 앱과 서버 이벤트를 동일 사용자로 안정적으로 묶을 수 있습니다.
deviceUserId를 생략하고 userId만 전달하면 여정 진입은 가능하지만,
모바일 SDK는 자체 식별자를 사용하므로 서버 이벤트와 디바이스가 자동으로 연결되지 않습니다.
이 경우 푸시, 인앱 발송이 의도한 디바이스에 도달하지 않읗 수 있습니다.
events[].eventKey 필수 앱박스 콘솔에 등록된 이벤트 키입니다.
events[].properties 선택 이벤트와 함께 전달할 속성값입니다. Key-Value 형식으로 전달합니다.
events[].ts 선택 이벤트 발생 시각입니다. 밀리초(ms) 단위 Unix timestamp를 사용합니다.
생략하거나 0이면 서버 수신 시각으로 대체됩니다.

Request Body 예시

JSON
1 {
2 "events" : [
3 {
4 "eventId" : "550e8400-e29b-41d4-a716-446655440000", // 생략 가능, 재시도 dedup 목적이면 직접 생성 권장
5 "userId" : "user_12345",
6 "deviceUserId" : "did_abcd1234", // 실제 매칭 기준
7 "eventKey" : "cart_added",
8 "properties": {
9 "price" : 10000,
10 "category" : "fashion"
11 },
12 "ts" : 1713520800000
13 }
14 ]
15 }

속성값 사용

properties 는 이벤트와 함께 추가 정보를 전달할 때 사용합니다.
전달한 속성값은 콘솔에서 조건 비교, 전환 측정, 노출 제어, 성과 분석 등에 사용할 수 있습니다.
  • 문자열 비교는 대소문자를 구분하며, 숫자 비교는 내부적으로 숫자 변환 후 수행됩니다.
  • 속성값이 필요 없는 경우 properties 는 빈 객체 {} 로 전달하거나 생략할 수 있습니다.

예시

JSON
1 {
2 "price" : 10000,
3 "category" : "fashion"
4 }

지원 데이터 타입

타입 예시
문자열 "fashion", "summer_dress"
숫자 10000, 3
참/거짓 (boolean) true, false
시간 1713520800000, "2025-04-19T14:23:56+09:00"

예제

1. 서버 호출 - 이벤트만 발송

이벤트 발생 사실만 전달하고, 별도의 조건용 속성값이 필요하지 않은 경우의 예시입니다.
Node.js
1 import { randomUUID } from "node:crypto";
2
3 const AUTH_KEY = process.env.APPBOX_AUTH_KEY;
4 const APP_PROJECT_ID = process.env.APPBOX_APP_PROJECT_ID;
5 const auth = "Basic " + Buffer.from(`${AUTH_KEY}:${APP_PROJECT_ID}`).toString("base64");
6
7 const res = await fetch("https://api.appboxapp.com/api/v1/server/journey/event", {
8 method : "POST",
9 headers : {
10 Authorization : auth,
11 "Content-Type" : "application/json",
12 },
13 body : JSON.stringify({
14 events : [{
15 eventId : randomUUID(),
16 userId : "<customer-user-id>",
17 deviceUserId : "<device-user-id>",
18 eventKey : "cart_added",
19 properties : {},
20 ts : Date.now(),
21 }],
22 }),
23 });
24
25 if (!res.ok) {
26 console.error("이벤트 호출 실패:", res.status, await res.text());
27 }

2. 서버 호출 - 속성값과 함께 발송

조건 비교에 사용할 속성값을 함께 보내는 예시입니다.
cURL
1 curl -X POST "https://api.appboxapp.com/api/v1/server/journey/event" \
2 -u "$APPBOX_AUTH_KEY:$APPBOX_APP_PROJECT_ID" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "events" : [{
6 "eventId" : "'"$(uuidgen)"'",
7 "userId" : "<customer-user-id>",
8 "deviceUserId" : "<device-user-id>",
9 "eventKey" : "purchase_complete",
10 "properties" : {
11 "price" : 10000,
12 "category" : "fashion"
13 },
14 "ts" : '$(date +%s%3N)'
15 }]
16 }'

3. 앱 내 웹페이지 JS 호출

JS 호출은 앱박스 클라우드 빌드 앱의 WebView 내부에서만 동작합니다. 일반 브라우저, PWA, 임의 WebView에서는 자동 차단됩니다.
HTML
1 <script src= "https://console.appboxapp.com/import/appbox.v3.js" ></script>
Javascript
1 window.AppboxSDK.journey.track ("cart_added", {
2 price : 10000,
3 category : "fashion",
4 }).then((res) => {
5 if (!res.ok) {
6 console.error( "[appbox.journey] track failed:", res.error);
7 }
8 });

4. ts 값 생성 예시

Code
1 // JavaScript / Node.js
2 const ts = Date.now();
3
4 // Kotlin
5 val ts = System.currentTimeMillis()
6
7 // Swift
8 let ts = Int64(Date().timeIntervalSince1970 * 1000)

응답 및 주의사항

서버 API 응답 형식

서버 API 응답은 공통적으로 { success, message, code, data? } 구조를 사용합니다.
JSON
1 {
2 "success" : true,
3 "message" : "success",
4 "code" : 200,
5 "data" : {
6 "accepted" : 1,
7 "rejected" : 0,
8 "unknownKeys" : []
9 }
10 }
  • accepted 는 큐 적재에 성공한 이벤트 수입니다.
  • rejected 는 검증 실패로 버려진 이벤트 수입니다.
  • unknownKeys 는 콘솔에 등록되지 않은 이벤트 키 목록입니다.

에러 응답

400 payload 에러는 HTTP status가 아니라 응답 body의 code: 400 으로 내려올 수 있습니다.
401과 429는 실제 HTTP status code로 반환됩니다.
JSON
1 { "success": false, "message" : "events is empty", "code" : 400 }
2 { "success": false, "message" : "...", "code": 401 }
3 { "success": false, "message" : "Too many requests", "code" : 429, "data" : null }

Rate Limit

  • 서버 이벤트 API는 앱(API Key) 단위로 초당 50건, 순간 최대 200건까지 허용됩니다.
  • 앱 내 웹페이지 JS 호출은 IP 단위로 초당 20건, 순간 최대 50건까지 허용됩니다.
  • 초과 시 429 응답을 반환합니다.

구현 시 주의사항

  • eventKey 는 콘솔에 등록된 값과 정확히 일치해야 합니다.
  • deviceUserId 가 실제 매칭 기준입니다. 모바일 앱과 백엔드 이벤트를 연결하려면 로그인 시점에 받은 deviceUserId 를 서버에 저장한 뒤 함께 전달하는 것을 권장합니다.
  • eventId 는 생략할 수 있지만, 재시도 중복 방지를 위해 UUID를 직접 생성하는 것이 안전합니다.
  • ts 는 밀리초(ms) 단위를 사용하며, 생략하거나 0이면 서버 수신 시각으로 대체됩니다.
  • 숫자 비교가 필요한 속성값은 number 타입으로, 문자열 조건 비교가 필요한 값은 코드값 형태로 일관성 있게 관리하는 것을 권장합니다.
  • JS 호출은 현재 SDK 버전 기준 window.AppboxSDK.journey.track API를 사용합니다.
  • JS 호출은 앱박스 클라우드 빌드 앱의 WebView 내부에서만 동작하며, 일반 브라우저, PWA, 임의 WebView에서는 자동 차단됩니다.
www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.