S3 이벤트

개요

플레이어가 게임에서 하는 모든 의미 있는 행동은 타임스탬프가 찍힌 이벤트를 생성할 수 있습니다 — 플레이한 매치, 구매한 아이템, 달성한 마일스톤, 시작 및 종료된 세션 등. 스튜디오는 백엔드 게임 서버, 텔레메트리 파이프라인, 분석 내보내기를 통해 이 데이터를 수집하지만, 이 데이터는 실제로 활용할 수 있는 인게이지먼트 시스템에 도달하지 못한 채 클라우드 스토리지에 쌓이는 경우가 많습니다.

Cloud Events는 이 간격을 해소합니다. S3 수집 파이프라인을 통해 FirstLook이 자체 Amazon S3 버킷을 바라보도록 설정하고, CSV 파일에서 플레이어 이벤트 데이터를 자동으로 가져올 수 있습니다. 수집된 이벤트는 FirstLook SDK를 통해 수집된 데이터와 동일한 분석, 리텐션 차트, 플레이어 프로필로 유입되어 — 모든 플레이어의 여정을 하나의 통합된 뷰로 확인할 수 있습니다.

이벤트가 CSV 파일이 아닌 Databricks 레이크하우스에 있는 경우, Delta Sharing을 통해 이벤트 테이블을 직접 읽어오는 Databricks 이벤트를 참고하세요.

주요 기능

S3 버킷을 모니터링하여 반복 스케줄로 새 CSV 파일을 감지하므로, 파일을 업로드하고 그대로 두기만 하면 됩니다.
플랫폼 ID(Steam, Discord, Xbox, PlayStation 등)에서 통합 FirstLook 플레이어 프로필로 플레이어 ID를 확인합니다 — 처음 확인된 플랫폼 ID의 경우 새 플레이어 레코드를 자동으로 생성합니다.
이벤트를 각 플레이어의 시간 순 레코드에 추가하여 리텐션 지표, 이벤트 차트, 코호트 세그먼테이션, 캠페인 타겟팅을 지원합니다.
대시보드에서 처리 상태를 표시하여 어떤 파일이 성공했는지, 어떤 파일에 문제가 있었는지, 무엇이 잘못되었는지 항상 확인할 수 있습니다.

S3 버킷 설정

FirstLook이 버킷에서 읽기 작업을 수행하려면, 크로스 계정 읽기 액세스를 허용하는 IAM 역할을 생성해야 합니다. 이렇게 하면 자격 증명이 안전하게 유지됩니다 — FirstLook은 AWS STS를 통해 역할을 임시로 수임하며 장기 키를 저장하지 않습니다.

1. IAM 정책 생성

다음 권한으로 AWS 계정에 새 IAM 정책을 생성합니다. YOUR_BUCKET_NAME을 실제 버킷 이름으로 교체하고, 필요에 따라 프리픽스를 하위 디렉터리로 범위를 좁힐 수 있습니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

2. 트러스트 정책으로 IAM 역할 생성

IAM 역할을 생성하고 위의 정책을 연결합니다. 그런 다음 FirstLook의 AWS 계정이 역할을 수임할 수 있도록 트러스트 정책을 구성합니다.

트러스트 정책에는 confused deputy 공격을 방지하기 위한 External ID 조건이 반드시 포함되어야 합니다. 초기 구성 저장 후 대시보드의 S3 Configuration 페이지에서 고유한 External ID를 확인할 수 있습니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::409257555035:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID"
        }
      }
    }
  ]
}

YOUR_EXTERNAL_ID를 S3 Configuration 페이지에 표시된 값으로 교체합니다.

3. 대시보드에서 구성

게임 대시보드에서 Configuration > S3 Events > S3 Configuration으로 이동하여 다음을 입력합니다:

IAM Role ARN — 방금 생성한 역할의 ARN (예: arn:aws:iam::123456789012:role/FirstLookIngestion).
External ID — (읽기 전용) FirstLook이 생성한 고유 식별자. 이 값을 복사하여 위에 표시된 대로 IAM 역할의 트러스트 정책에 추가합니다.
Bucket — S3 버킷 이름.
Prefix — (선택 사항) FirstLook이 스캔하는 디렉터리를 제한하기 위한 경로 프리픽스 (예: events/).
AWS Region — 버킷이 위치한 리전 (예: us-east-1).
Enabled — 언제든지 수집을 켜거나 끌 수 있습니다.

저장 후 FirstLook은 몇 분마다 버킷에서 CSV 파일을 스캔하기 시작합니다.

CSV 파일 형식

FirstLook은 Counter 스키마 또는 Duration 스키마의 CSV 파일을 허용합니다. 각 파일에는 한 가지 유형의 이벤트가 포함되어야 하며 — 스키마는 컬럼 헤더를 기반으로 자동으로 감지됩니다.

구분자 및 인코딩

구분자: 쉼표(,), 탭, 세미콜론(;), 파이프(|)가 모두 지원됩니다. FirstLook은 파일의 헤더 행에서 구분자를 자동으로 감지합니다.
인코딩: UTF-8이 필요합니다. Excel 스타일의 BOM 마커는 자동으로 처리됩니다.
파일 크기: 파일당 최대 200 MB. 더 큰 내보내기는 작은 파일로 분할해야 합니다.

플레이어 ID 컬럼

모든 CSV에는 플레이어 식별자 컬럼이 정확히 하나 포함되어야 합니다. FirstLook은 이를 사용하여 각 행을 통합 플레이어 프로필로 연결합니다. 이전에 확인된 적 없는 플랫폼 ID의 경우 FirstLook이 자동으로 새 플레이어 레코드를 생성하고 연결합니다.

지원되는 식별자 컬럼:

컬럼	설명
`player_id`	FirstLook 내부 플레이어 ID
`steam_id`	Steam ID
`discord_id`	Discord 사용자 ID
`xbox_id`	Xbox ID
`psn_id`	PlayStation Network ID
`epic_id`	Epic Games ID
`roblox_id`	Roblox 사용자 ID
`ea_id`	EA ID
`email`	플레이어 이메일 주소
`pragma_social_id`	Pragma 소셜 ID (UUID)
`pragma_player_id`	Pragma 플레이어 ID (UUID)
`apple_id`	Apple ID
`google_id`	Google ID
`twitch_id`	Twitch ID
`tiktok_id`	TikTok ID
`kick_id`	Kick ID
`ioi_id`	IOI ID
`chzzk_id`	CHZZK ID

Counter 스키마

각 행이 수치 값을 가진 개별 이벤트를 나타낼 때 Counter 스키마를 사용합니다 — 매치의 킬 수, 구매한 아이템, 획득한 재화 등.

필수 컬럼:

컬럼	타입	설명
`session_id`	UUID	플레이 세션의 이벤트를 그룹화합니다.
`timestamp`	ISO 8601 datetime	이벤트가 발생한 시각 (예: `2026-01-15T14:30:00Z`).
`counter_name`	String	점으로 구분된 이벤트 이름 (예: `match.kills`). 파라미터를 기록하려면 `#<parameter>`를 추가합니다 (예: `level.started#forest_3`).
`counter_value`	Integer	이벤트 값 (예: 킬 수).
(identifier)	String	위 표의 플레이어 ID 컬럼 중 하나.

선택 컬럼:

컬럼	타입	설명
`build_version`	String	이벤트를 생성한 게임 빌드 버전.

예시:

steam_id,session_id,timestamp,counter_name,counter_value,build_version
76561198012345678,a1b2c3d4-e5f6-7890-abcd-ef1234567890,2026-01-15T14:30:00Z,match.kills,7,1.2.0
76561198012345678,a1b2c3d4-e5f6-7890-abcd-ef1234567890,2026-01-15T14:30:00Z,match.deaths,3,1.2.0
76561198087654321,b2c3d4e5-f6a7-8901-bcde-f12345678901,2026-01-15T15:00:00Z,store.purchase,1,1.2.0
76561198087654321,b2c3d4e5-f6a7-8901-bcde-f12345678901,2026-01-15T15:05:00Z,level.started#forest_3,1,1.2.0

Duration 스키마

각 행이 시간 기반 활동을 나타낼 때 Duration 스키마를 사용합니다 — 매치 길이, 메뉴 체류 시간, 로딩 화면 지속 시간 등.

필수 컬럼:

컬럼	타입	설명
`session_id`	UUID	플레이 세션의 이벤트를 그룹화합니다.
`start_time`	ISO 8601 datetime	활동이 시작된 시각.
`end_time`	ISO 8601 datetime	활동이 종료된 시각.
`duration_name`	String	점으로 구분된 이벤트 이름 (예: `match.round`).
(identifier)	String	위 표의 플레이어 ID 컬럼 중 하나.

예시:

steam_id,session_id,start_time,end_time,duration_name
76561198012345678,a1b2c3d4-e5f6-7890-abcd-ef1234567890,2026-01-15T14:00:00Z,2026-01-15T14:25:00Z,match.round
76561198012345678,a1b2c3d4-e5f6-7890-abcd-ef1234567890,2026-01-15T14:26:00Z,2026-01-15T14:28:00Z,menu.loadout
76561198087654321,b2c3d4e5-f6a7-8901-bcde-f12345678901,2026-01-15T15:00:00Z,2026-01-15T15:45:00Z,match.round

ID 확인

FirstLook이 이전에 확인된 적 없는 플랫폼 ID를 발견한 경우 — 예를 들어 기존 플레이어와 일치하지 않는 steam_id — 자동으로 새 플레이어 레코드를 생성하고 ID를 연결합니다. 즉, 플레이어가 FirstLook 온보딩 플로우를 통해 가입하기 전이라도 즉시 이벤트 가져오기를 시작할 수 있습니다.

이 ID 확인은 지원되는 모든 플랫폼에서 작동하므로, 게임 서버나 텔레메트리 시스템이 이미 추적하는 식별자를 사용하여 데이터를 가져올 수 있습니다.

수집 모니터링

대시보드에서 Configuration > S3 Events > Monitor로 이동하면 FirstLook이 버킷에서 발견한 모든 파일의 상태를 확인할 수 있습니다.

각 파일에는 다음이 표시됩니다:

Status — Pending, Processing, Completed, Failed, 또는 No Longer Found (S3에서 파일이 삭제된 경우).
Rows Processed / Duplicates Skipped / Rows Failed — 성공적으로 수집된 행 수와 문제가 있었던 행 수.
Error — 문제가 발생한 경우 어떤 문제가 있었는지에 대한 사람이 읽을 수 있는 설명.
Reprocess — 실패한 파일의 경우, 근본적인 문제를 해결한 후 파일을 다시 시도하기 위한 버튼.