콘텐츠로 이동

이벤트 속성 전송

개요

앱 이벤트 로그는 필수 속성, 사용자 정의 속성으로 구성됩니다.

필수 속성

앱 이벤트 로그를 전송할 때 반드시 포함 해야 하는 속성입니다.

필수 속성 네이밍 규칙

필수 속성명은 카멜 케이스(camelCase) 또는 소문자(lowercase)로 전송해야 합니다. user_id와 같이 스네이크 케이스(snake_case)로 전송하면 정상 처리되지 않고 rescue 테이블로 격리됩니다.

속성명 설명 자료형 예시
userId 계정 기준 유저 식별자 STRING 100001
deviceId 단말 기준 유저 식별자 STRING 100000
identifierProvider 유저 식별자 발급 시스템. hive 고정 STRING hive
appId Hive 콘솔 > 프로젝트 설정 > App ID에 등록된 App ID STRING com.com2us.game.ios
appIdGroup Hive 콘솔 > 프로젝트 설정 > 프로젝트에서 발급하는 Project ID. appId 전송 시 자동 생성 STRING com.com2us.game
eventTime 이벤트 발생 시각. RFC 3339 국제 표준 (타임존 포함) STRING 2026-07-20T14:01:01+09:00
eventName 이벤트를 분류하는 이벤트명 STRING asset_drop
Note

deviceId에는 로그인 요청에 사용하는 deviceKey와 같은 값을 넣습니다. 같은 값을 넣지 않으면 단말 기준으로 데이터가 연결되지 않아 퍼널 분석 등 단말 기준 분석이 어려울 수 있습니다. deviceKey를 만드는 방법은 deviceKey를 참고하세요.

appId / appIdGroup 전송 규칙

appIdGroup은 appId를 기준으로 자동 생성되므로 전송하지 않아도 됩니다.

  • appId를 아는 경우: 이벤트 속성에 appId를 넣어 전송하세요.
  • appId를 모르는 경우: 로그 전송 시 필수 값으로 입력되는 헤더의 appId 값이 이벤트 속성의 appId로 대체됩니다. 자세한 내용은 이벤트 로그 전송을 참고하세요.
필수 속성 전송 시 주의 사항

다음 조건 중 하나라도 해당하면 이벤트 로그가 rescue 테이블로 격리 됩니다.

  • appId 또는 appIdGroup 둘 다 없는 경우
  • 나머지 필수 속성(userId, identifierProvider, deviceId, eventTime,eventName) 중 하나라도 누락되거나 빈 값인 경우
  • 값을 알 수 없는 경우에도 빈 값으로 두지 말고, "0" 또는 "unknown"과 같은 임의의 값을 채워 전송하세요.

eventName 명명 규칙

eventName에 사용할 이벤트명은 아래 규칙을 따라 작성할 것을 권고합니다.

  • 권장 문자: 영문(a–z, A–Z, 대/소문자 구분), 숫자(0–9), 언더바(_)
  • 구분자: 단어 사이는 공백이 아닌 언더바(_)로 구분
  • 형태: 이벤트를 명확하게 설명하는 명사_동사 형태 권장
  • 예시: item_purchase, level_up, tutorial_complete, stage_start
Warning

위 규칙을 준수하지 않은 이벤트명은 분석에 활용하는 데 제한이 있을 수 있습니다.

eventTime 형식 규칙 (RFC 3339)

eventTime은 RFC 3339 형식을 따르며, 반드시 타임존 정보를 포함해야 합니다.

형식: 

YYYY-MM-DDTHH:MM:SS[.sss]+HH:MM 또는 YYYY-MM-DDTHH:MM:SSZ

허용 예시: 

2026-07-20T14:01:01+09:00       (KST, 한국 표준시)
2026-07-20T05:01:01Z            (UTC)
2026-07-20T14:01:01.123+09:00   (밀리초 포함)
2026-07-20T23:01:01-05:00       (미국 동부 시간)

허용되지 않는 예시: 

2026-07-20 14:01:01              (타임존 없음 → 격리)
2026-07-20                       (시간 없음 → 격리)
1719835261                       (Unix timestamp → 격리)
14:01:01                         (날짜 없음 → 격리)

eventTime

  • eventTime은 파이프라인에서 UTC로 변환 되어 테이블의 dateTime 컬럼에 저장됩니다. 원본 값은 attributes.eventAttributes.eventTime에 그대로 보존됩니다.
eventTime 전송 시 주의 사항

eventTime은 현재 시각 기준 과거 10년 ~ 미래 5년 범위 내의 값만 허용됩니다. 이 범위를 벗어나면 이벤트 로그가 rescue 테이블로 격리됩니다.

사용자 정의 속성

앱에서 전송하고 싶은 정보를 속성명과 속성값으로 구성하여 필수 속성과 함께 직접 전송합니다.

속성명 규칙

규칙 설명 예시
시작 문자 반드시 영문 소문자 또는 대문자 로 시작 level, Stage
대소문자 구분 사용자 정의 속성은 대소문자를 구분합니다 market != Market != MARket
허용 특수문자 특수 문자는 언더스코어(_)만 허용 item_name

사용할 수 없는 속성명 (예약어)

사용자 정의 속성 전송 시 주의 사항

아래 예약어를 속성명으로 사용하면 rescue 테이블로 격리 됩니다. 대소문자와 관계없이 동일하게 적용됩니다.

예약어 비고
attributes 대소문자 무관 (예: Attributes, ATTRIBUTES)
eventAttributes 대소문자 무관
hiveAttributes 대소문자 무관

속성값 규칙

속성값 형태 주의 사항

속성값은 숫자형 과 문자형 2가지만 전송 가능합니다. JSON 객체 , JSON 배열 , JSON 형태의 문자열 형태로 전송 시 rescue 테이블로 격리 됩니다.

자료형 설명 예시
숫자형 정수 또는 소수. 따옴표 없이 전송 "level": 10, "exp": 1.5
문자형 반드시 큰따옴표("")로 감싸서 전송 "character_name": "AA"

속성값이 JSON 객체 , JSON 배열 , JSON 형태의 문자열 형태인 경우 rescue 테이블로 격리 됩니다. 

// JSON 객체 (허용되지 않음)
"info": {"key": "value"}

// JSON 배열 (허용되지 않음)
"items": [1, 2, 3]

// JSON 형태의 문자열 (허용되지 않음)
"data": "{\"key\": \"value\"}"

동일 속성명 중복 전송

동일한 속성명을 2개 이상 전송하면 속성값은 랜덤하게 선택되어 1개만 저장 됩니다.

주의사항 & Tips

  • 필수 속성명은 카멜 케이스 또는 소문자로 전송해야 하며, 스네이크 케이스(user_id)로 보내면 rescue 테이블로 격리됩니다.
  • appId 또는 appIdGroup 중 하나는 반드시 포함해야 하며, 둘 다 없으면 격리됩니다.
  • eventTime은 RFC 3339 형식(타임존 포함)만 허용되며, 현재 시각 기준 과거 10년 ~ 미래 5년을 벗어나면 격리됩니다.
  • 사용자 정의 속성명으로 attributes, eventAttributes, hiveAttributes는 사용할 수 없습니다(대소문자 무관).
  • 속성값은 숫자형·문자형만 허용되며, JSON 객체·배열·JSON 형태의 문자열은 격리됩니다.
  • 격리된 로그를 확인하고 재전송하는 방법은 데이터 격리를 참고하세요.

더 알아보기