ゲームデータをイベントログとして送信する：イベントログ送信 第3回

実際のゲーム内の行動をデータとして収集する

「テストログで収集構造と指標を検証する：イベントログ送信 第2回」では、テストログを送信してイベントの収集構造と指標の構成を検証しました。今回は、検証したイベント構造を実際のゲームに適用し、ユーザーの行動が発生した時点で実際のデータを送信する方法を解説します。

テストログでイベント名とプロパティ、データ型と値の形式を確認していても、実際のゲームではユーザーの行動が発生するタイミングに合わせてログ送信コードを実行する必要があります。コンテンツのクリア、通貨の獲得、アイテムの使用といった行動が確定する位置にコードを適用し、その時点の実際のゲームデータをイベントプロパティに紐づけます。

イベントの送信が早すぎると、完了していない行動が集計される可能性があります。遅すぎると、画面遷移やアプリの終了によってログが欠落する可能性があります。そのため、イベントの意味に基づいて送信タイミングを決め、実際の行動が完了した直後にログを送信します。

Hive Analyticsのイベントログ送信

Hive Analyticsのイベントログは、ゲームクライアントまたはサーバーから送信できます。クライアント送信はUnity、Unreal Engine、C++、Android、iOSの開発環境に対応しており、サーバーからはFluentdまたはHTTP方式でイベントログを送信できます。

イベントログは、正常な収集と処理に必要な必須プロパティと、イベントの詳細情報を表すカスタムプロパティで構成されます。

必須プロパティには、ユーザーとデバイス、アプリとプロジェクト（ゲーム）、イベント名と発生時刻を識別するための次の値が含まれます。

必須プロパティの送信ルール
必須プロパティが次のルールを満たさない場合、イベントは正常に収集されず、隔離テーブルであるt_raw_event_log_rescueに保存されます。

• 必須プロパティが欠落している、または空の値で送信された場合
• Hiveコンソールに登録されていないappIdを送信した場合
• 必須プロパティ名をuser_idのようにスネークケースで送信した場合
• eventTimeがタイムゾーンを含むRFC 3339形式ではない場合
• eventTimeが現在時刻を基準に過去10年から未来5年までの許容範囲を外れている場合

必須プロパティ名はキャメルケースまたは小文字で送信する必要があります。隔離されたログは、t_raw_event_log_rescueで元データと隔離理由を確認し、誤った値を修正して再送信します。

カスタムプロパティは、キャラクターレベル、コンテンツの種類、スコアやプレイ時間など、イベントの詳細情報を分析するために自由に構成できます。クライアントとサーバーのどちらも、分析に必要なカスタムプロパティに実際のゲームの値を紐づけて直接送信します。

contents_successでコンテンツクリアイベントを送信する

contents_successイベントを実際のゲームに適用する手順です。ユーザーがゲームコンテンツをクリアした時点でイベントを送信し、コンテンツの種類やユーザーの状態、プレイ結果を実際のゲームデータに紐づけます。

イベントの送信タイミングを確認する

contents_successは、ゲームコンテンツが完了した時点で発生するイベントです。コンテンツへの入場時やプレイ開始時ではなく、サーバーの応答やゲームロジックによって完了結果が確定した直後にイベントを送信します。

リトライや画面遷移の過程で同じ完了処理が複数回実行される可能性がある場合は、1つの行動に対してイベントが重複送信されないように処理します。

カスタムプロパティを紐づける

contents_successに事前定義されたプロパティを確認し、各プロパティにイベントが発生した時点の実際のゲームデータを紐づけます。

プロパティ名とデータ型、値の単位は、テストログで検証した基準と同じに保ちます。特にplayTimeSecのような時間に関するプロパティは、秒またはミリ秒など使用する単位を統一することで、複数のゲーム（プロジェクト）のデータを同じ基準で分析できます。

必須プロパティを構成する

イベントログには、userId、deviceId、identifierProvider、appId、appIdGroup、eventTime、eventNameの必須プロパティが含まれている必要があります。

Hive SDK v4を使ってクライアントから送信すると、必須プロパティのうちeventName以外の値は自動で収集されます。market、hive_country、language、os、app_versionなど、ユーザーのアプリと実行環境を表すプロパティもあわせて収集されるため、必須プロパティはeventNameだけを自分で構成します。

Hive Axylを使ってクライアントから送信すると、identifierProviderはサーバー側でhiveに固定されて収集され、appIdはSDKの初期化時に指定した値がログ送信リクエストのヘッダーで自動的に渡されます。それ以外の必須プロパティは自分で構成して送信します。

サーバーから送信する場合は、FluentdとHTTPのどちらの方式でも必須プロパティを自分で構成します。詳しい送信方法は、Hive Developersサイトのイベント送信で確認できます。

イベント送信コードを適用する

Data > Eventでcontents_successを選択し、Source Generationタブに移動します。クライアントまたはサーバーの開発方式とゲームの開発環境を選択し、生成されたソースを確認します。

開発者は、生成されたソースのサンプル値を実際のゲーム変数に置き換え、コンテンツのクリアが確定する位置にコードを適用します。イベント名にはcontents_successを入力し、カスタムプロパティにはコンテンツをクリアした時点のcharacterLv、modeTypeId、modeTypeName、score、playTimeSecの値を渡します。

クライアントから送信する場合は、使用するSDKに合わせて直接送信する必要がある必須プロパティを構成し、自動で収集される必須プロパティはコードに別途入力しません。たとえばHive SDK v4でクライアントから送信する場合、Unity環境では必須プロパティのうちeventNameとカスタムプロパティをJSONObjectで構成し、Analytics.sendAnalyticsLog(logData)を呼び出してイベントを送信します。

JSONObject logData = new JSONObject();
// 必須プロパティ（eventNameのみ直接送信し、残りはSDKが自動収集）
logData.AddField("eventName", "contents_success");
// カスタムプロパティ
logData.AddField("characterLv", 15);
logData.AddField("modeTypeId", 1);
logData.AddField("modeTypeName", "Tutorial_1");
logData.AddField("score", 12);
logData.AddField("playTimeSec", 120);
Analytics.sendAnalyticsLog(logData);

イベントの保存

正常に収集されたイベントはt_raw_event_logに保存されます。必須プロパティの欠落やeventTimeの形式エラーなど、収集基準を満たさなかったイベントはt_raw_event_log_rescueに隔離されます。

正常データと隔離データの保存構造、隔離理由の確認方法は、「イベントログの保存構造と取り込み失敗データを確認する：イベントログ送信 第4回」で詳しく解説します。

Hive Analyticsを始める

ゲームで発生した行動を一貫したイベントログとして収集するには、必須プロパティとカスタムプロパティを区別し、実際の行動が確定するタイミングで検証済みの値とデータ型を送信する必要があります。

Hive Analyticsは、クライアントとサーバーの環境に合った方式でイベントを送信し、収集したデータを分析に活用できるゲーム特化型の分析ソリューションです。今すぐHive Analyticsで、分析したいゲーム内行動のイベント構造を実際のゲームデータと紐づけてみましょう。