이 문서에서는 채널톡 SDK (이하 SDK)의 이벤트에 대해 설명합니다.
Event는 무엇인가요?
이벤트(Event)는 웹사이트나 애플리케이션 내에서 발생하는 유저의 행동을 뜻하며, 비즈니스와 관련된 모든 이벤트를 정의할 수 있습니다.
이벤트 값 알아보기
SDK에서는 아래 이벤트를 기본적으로 제공합니다.
PageView
: 고객이 특정 페이지를 조회했을 때의 이벤트UserChatOpen
: 고객이 유저챗을 새로 열었을 때의 이벤트MarketingView
: 고객이 마케팅 메시지를 조회했을 때의 이벤트MarketingClick
: 고객이 마케팅 메시지 안에 포함된 url 링크를 눌렀을 때 발생하는 이벤트MarketingGoal
: 마케팅 메시지에서 목표로 설정한 이벤트 값이 발생했을 때의 이벤트
프로퍼티는 무엇인가요?
프로퍼티(Property)는 이벤트를 설명해주는 하위 정보들입니다. 프로퍼티 데이터를 바탕으로 이벤트를 좀 더 자세하게 파악할 수 있고, 적합한 의사결정을 내리는 데 도움을 얻을 수 있습니다.
var properties = {
"userId": "1234",
"hasPurchaseA": true,
"lastVisitedAt": "2100-10-11"
}
let properties: [String: Any] = [
"userId": "1234",
"hasPurchaseA": true,
"lastVisitedAt": "2100-10-11"
]
NSDictionary *properties = @{
@"userId": @"1234",
@"hasPurchaseA": @YES,
@"lastVisitedAt": @"2100-10-11"
};
Map<String, Object> properties = new HashMap<>();
properties.put("userId", "1234");
properties.put("hasPurchaseA", true);
properties.put("lastVisitedAt", "2100-10-11");

프로퍼티 제한
배열 또는 객체 값을 포함한 이벤트 프로퍼티의 최대 크기는 4KB입니다.
지원 프로퍼티 타입
문자열(String)
- 인식가능한 영숫자값(alphanumeric)이며 예시로는 이와 같습니다.
name = “Get Up”
,type = "EP”
- 최대 길이: 속성당 512 바이트로 제한됩니다.
- 문자 인코딩에 따라 각 문자당 요구되는 바이트 수가 달라질 수 있습니다.
- 다른 정의된 데이터 유형과 일치하지 않는 속성 값은 모두 문자열로 처리됩니다.
숫자(Numeric)
- 숫자 값(정수 또는 소수)을 나타냅니다. 예시로는 아래와 같습니다.
revenue = 15.00
,quantity = 5
.
불리언(Boolean)
true/false
를 명시적으로 사용하여 나타냅니다. 예시로는 아래와 같습니다.Favorite = true
,Bookmarked = false
.
- 현재 불리언이 아닌 값은 불리언으로 변환할 수 없습니다.
날짜 / 날짜시간(Date / DateTime)
- 날짜(Date): 시간 정보가 없는 달력 날짜(YYYY-MM-DD)를 나타냅니다. 허용되는 형식은 다음과 같습니다.
- ISO Date 문자열(예: "2025-06-17")
- 날짜시간(DateTime): 날짜, 시간 및 시간대를 포함하는 특정 시점을 나타냅니다. 값은 비교를 위해 UTC로 정규화됩니다. 허용되는 형식은 다음과 같습니다.
- ISO 8604 문자열(예: "2025-06-17T14:30:00Z")
- 밀리초 단위의 유닉스 타임스탬프
리스트(배열, Array)
- 문자열 또는 숫자 값을 포함하는 JSON 배열. 예시:
- Favorite Genres =
["Folk", "Alternative"]
- Favorite Numbers =
[1, 5, 10.0]
- Favorite Genres =
- 문자열과 숫자 유형만 지원됩니다.
객체 리스트(List of Objects)
- 동일한 키-값 구조를 가진 한 단계 중첩된 JSON 객체의 배열. 예시:
- Cart =
[{"Brand":"Puma","Category":"Jacket","Price":30}, {"Brand":"Adidas","Category":"Hats","Price":15}]
- Cart =
- 각 리스트의 처음 5개 객체만 지원됩니다.
- 채널톡에선 중첩된(nested) 객체는 최대 한 단계까지 인식합니다.
각 SDK의 사용 예시는 아래와 같습니다.
번역
기본적으로 제공되는 이벤트 5개와, 커머스 연동을 통해 받아온 이벤트들은 번역을 제공하고 있습니다. 아래는 커머스 연동 이벤트가 명세되어 있는 페이지입니다.