이벤트 호출
이벤트는 앱박스에서 사용자 행동과 상태 변화를 수집하고 활용하기 위한 기본 데이터 단위입니다.
이벤트는 사용자 여정, 알림 메시지 전환 이벤트, 인앱 메시지 노출 시점 등 다양한 곳에서 사용됩니다.
본 문서를 통해 클라이언트 앱 또는 서버에서 이벤트를 호출하여 앱박스 콘솔에 등록한 이벤트와 연동할 수 있으며, 이벤트와 함께 속성값 전달 방법까지 확인할 수 있습니다.
사전 확인
- 이벤트 호출 전에 앱박스 콘솔에서 사용할 이벤트를 먼저 등록해야 합니다.
- 요청에 포함하는 eventKey는 콘솔에 등록된 이벤트 키와 정확히 일치해야 합니다.
- 속성값을 조건으로 사용할 예정이라면 콘솔에서 이벤트 조건에 사용할 속성키를 완전 일치하게 생성해야 합니다.
호출 방식
하나의 이벤트는 한 채널에서만 발사하는 것을 권장하며, 동일 이벤트를 두 채널에서 동시에 보내면 중복 처리 위험이 있습니다.
| 채널 | 권장 상황 | 대표 예시 |
|---|---|---|
| 백엔드 호출 | 위변조 차단, DB 트랜잭션 정합성이 필요한 경우 | 결제 완료, 회원가입 완료 등 |
| JS 호출 | 백엔드 부담 없이 즉시성이 중요한 UX 이벤트 | 페이지 조회, 상품 조회, 배너 클릭 등 |
서버 API
아이디 자리에 인증키, 비밀번호 자리에 앱 프로젝트 ID(콘솔 › 앱 정보)를 넣습니다(별도 Secret 은 없습니다). 인증키는 푸시 API 와 같은 키입니다(콘솔 › 푸시 메시지 › API 설정).
인증키는 환경변수에 저장하고, 코드에 직접 하드코딩하지 않는 것을 권장합니다.
HTTP
1
Authorization: Basic {Base64(AUTH_KEY:APP_PROJECT_ID)}
2
Content-Type: application/json
-u 옵션으로 인증키와 앱 프로젝트 ID를 간단히 전달할 수 있습니다.
Bash
1
-u $APPBOX_AUTH_KEY:$APPBOX_APP_PROJECT_ID
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 는 빈 객체
{}로 전달하거나 생략할 수 있습니다.
예시
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 호출
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 응답 형식
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 는 콘솔에 등록되지 않은 이벤트 키 목록입니다.
에러 응답
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에서는 자동 차단됩니다.