S3 Events

概要

プレイヤーがゲーム内で行うあらゆる意味のある操作は、タイムスタンプ付きのイベントとして記録されます — プレイしたマッチ、購入したアイテム、達成したマイルストーン、開始・終了したセッションなど。スタジオはこのデータをバックエンドのゲームサーバー、テレメトリパイプライン、アナリティクスエクスポートを通じて収集しますが、多くの場合、クラウドストレージに蓄積されるだけで、それを活用できるエンゲージメントシステムには届きません。

Cloud Eventsはそのギャップを埋めます。S3取り込みパイプラインを使うと、FirstLookに自社のAmazon S3バケットを指定し、CSVファイルからプレイヤーイベントデータを自動的にインポートできます。取り込まれたイベントは、FirstLook SDK で収集したデータと同じアナリティクス、リテンションチャート、プレイヤープロフィールに流れ込み、すべてのプレイヤーのジャーニーを一元的に把握できます。

イベントがCSVファイルではなくDatabricksレイクハウスにある場合は、Databricks Events を参照してください。こちらはDelta Sharingを通じてイベントテーブルを直接読み込みます。

機能概要

S3バケットを定期的に監視して新しいCSVファイルを検出するため、ファイルを配置するだけで完了します。
プラットフォームID（Steam、Discord、Xbox、PlayStation など）からFirstLookの統合プレイヤープロフィールへのプレイヤーID解決を自動的に行い、初めて確認されたプラットフォームIDに対しては新しいプレイヤーレコードを自動作成します。
各プレイヤーの時系列レコードにイベントを追記し、リテンション指標、イベントチャート、コホートセグメンテーション、キャンペーンターゲティングを強化します。
ダッシュボードで処理ステータスを表示するため、どのファイルが成功したか、問題があったか、何が起きたかを常に把握できます。

S3バケットのセットアップ

FirstLookがバケットを読み取れるようにするには、クロスアカウントの読み取りアクセスを付与するIAMロールを作成する必要があります。これにより認証情報のセキュリティが保たれます — FirstLookはAWS STSを使用して一時的にロールを引き受けるだけで、長期有効なキーは保存しません。

1. IAMポリシーの作成

以下の権限を持つIAMポリシーをAWSアカウントに作成します。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条件を含める必要があります。固有のExternal IDは、初期設定を保存した後にダッシュボードのS3 Configuration ページで確認できます。

{
  "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には必ず1つのプレイヤー識別子列を含める必要があります。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	イベントの値（例：キル数）。
（識別子）	String	上記の表からプレイヤー識別子列を1つ指定します。

任意列：

列	型	説明
`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`）。
（識別子）	String	上記の表からプレイヤー識別子列を1つ指定します。

例：

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 — 失敗したファイルについて、根本的な問題を修正した後に再処理をキューに入れるためのボタン。