이벤트 이해하기

이 문서에서는 채널톡 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]
문자열과 숫자 유형만 지원됩니다.

객체 리스트(List of Objects)

동일한 키-값 구조를 가진 한 단계 중첩된 JSON 객체의 배열. 예시:
- Cart = [{"Brand":"Puma","Category":"Jacket","Price":30}, {"Brand":"Adidas","Category":"Hats","Price":15}]
각 리스트의 처음 5개 객체만 지원됩니다.
채널톡에선 중첩된(nested) 객체는 최대 한 단계까지 인식합니다.

각 SDK의 사용 예시는 아래와 같습니다.

번역

기본적으로 제공되는 이벤트 5개와, 커머스 연동을 통해 받아온 이벤트들은 번역을 제공하고 있습니다. 아래는 커머스 연동 이벤트가 명세되어 있는 페이지입니다.