Unity Analytics Raw Data Export
概要
Unity Analytics Raw Data Export の使用で、Raw イベントデータすべてにアクセスすることができます。これにより、カスタムクエリの作成やデータの可視化など、データを思い通りに利用できます。
Raw Data Export にアクセスするには 2 つの方法があります。
- Unity Analytics Dashboard へのアクセス
- REST API を使用するアクセス
Raw Data Export は 2016 年 6 月以降のデータを扱えます。
Analytics Dashboard の使い方
Unity Analytics ダッシュボードを使用すると、コードを書かずに 生イベントデータにアクセスしたりエクスポートすることができます。Unity Analytics ダッシュボード (analytics.cloud.unity3d.com) で、プロジェクトを選択し、 Analytics > Raw Data Export の順に選んでください。
次に、画面の Export セクションで以下を行います。
- エクスポートしたい Event のデータセット (例えば appRunning, appStart, custom, deviceInfo, transaction, userInfo) を指定します。
- Start Date (開始日) を指定するか、または、ドロップダウンから Previous Job Id を選択して、以前のジョブから継続的にデータをエクスポートします。
- End Date (終了日) を指定します。
- デフォルトのファイル形式は JSON です。Export as JSON のドロップダウンメニューをクリックして、適当なファイル形式を指定します。
Raw Data Export により、自動的にジョブを作成し、Activity 表に表示します。
ジョブが終了したら、表の Download 列からファイルを選び、データをダウンロードできます。
REST (Representational State Transfer) API
Unity Analytics に送られるすべてのデータは Unity のデータストアに保存されます。そのため、Raw Data Export API を利用すると、Raw イベントデータを受信、保存してファイルにダウンロードできます。
要件
すべてのリクエストは Unity Project ID (UPID) と API Key を使った HTTP Basic 認証を必要とします。
制限
- リクエスト期間 (
startDateからendDateまで) は 31 日です。 - 制限は変更されることがあります。
- Unity Analytics はリクエストされた Raw データファイルを 14 日間保持します (14 日経過した後は、新しくリクエストしなおす必要があります)。
ユーザーのワークフロー
Raw データをエクスポートするには、Create Raw Data Export API を呼び出します。これにより、データを処理する非同期ジョブが起動します。処理にかかる時間は、エクスポートするデータ量によります。
現在の状態や結果を得るには、Get Raw Data Export API を使います。いったんエクスポートが終了してから、API の返答で結果を取得できます。結果には、ファイルのリストと関連するダウンロード URL が含まれています。それらの URL を順にたどり、エクスポートしたデータをダウンロードすることができます。
注意
- リクエスト/応答の日付と時間はすべて、UTC (協定世界時、日本時間は UTC + 9:00) タイムゾーンです。
- API リクエスト/応答には JSON 形式 (このドキュメントの読み取り用形式) が使われます。データファイル書式は設定可能です。
- データは .gzip 圧縮ファイルでエクスポートされます。
- API の ベース URL は https://analytics.cloud.unity3d.comです。
Raw Data Export の作成
Raw Data Export はプロジェクトとデータセット (イベントタイプ) 単位で特定されます。リクエストの期間は 31 日間に限られます。
Raw Data Export を作成するには以下の HTTP メソッドを使用します。
POST api/v2/projects/{UNITY_PROJECT_ID}/rawdataexports
引数は、リクエストのペイロードに表示されます。それらは Content-Type application/json をもつ JSON 形式です。
| リクエスト引数 | 必須/オプショナル | タイプ | 説明 |
|---|---|---|---|
| startDate | continueFrom を指定しない場合は必須 | string | エクスポートの開始日 (この日を含む)。日にちは YYYY-MM-DD 形式 (ISO–8601) で表示。 |
| endDate | 必須 | string | エクスポートの終了日 (この日は含まれない)。日付は YYYY-MM-DD 形式 (ISO 8601) で表示。今日を検索する場合は、endDate に明日の日付を入力します。 |
| format | 必須 | string | 出力データ形式: json (改行区切りの json) か tsv |
| dataset | 必須 | string | 次のイベントタイプのうちの 1 つ: appStart、appRunning、deviceInfo、custom、transaction |
| continueFrom | オプショナル | string | 継続的にデータをエクスポートするための Raw Data Export ID。これは、以前のエクスポートを終了した時点から継続するために使用されます。詳しくは Continuing を参照してください。startDate を指定する代わりに、continueFrom で前の Raw Data Export ID を指定することもあります。continueFrom と startDate 両方を指定するのは出来ません。 |
コマンドラインで URL を使ったリクエストのテンプレート
curl --user {UNITY_PROJECT_ID}:{API_KEY} --request POST --header "Content-Type: application/json" --data {REQUEST_JSON}
https://analytics.cloud.unity3d.com/api/v2/projects/{UNITY_PROJECT_ID}/rawdataexports
サンプル値
UNITY_PROJECT_ID = aa43ae0a-a7a7-4016-ae96-e253bb126aa8
API_KEY = 166291ff148b2878375a8e54aebb1549
REQUEST_JSON = { "startDate": "2016-05-15" , "endDate": "2016-05-16", "format": "tsv", "dataset": "appStart" }
サンプル値を使った実際のリクエスト
curl --user aa43ae0a-a7a7-4016-ae96-e253bb126aa8:166291ff148b2878375a8e54aebb1549 --request POST --header "Content-Type: application/json" --data '{ "startDate": "2016-05-15" , "endDate": "2016-05-16", "format": "tsv", "dataset": "appStart" }' https://analytics.cloud.unity3d.com/api/v2/projects/aa43ae0a-a7a7-4016-ae96-e253bb126aa8/rawdataexports
応答は、JSON 形式の一般的な Raw Data Export 応答属性を使用します。
Raw Data Export 応答属性
| 応答属性 | タイプ | 説明 |
|---|---|---|
| id | string | Raw Data Export ID |
| upid | string | Unity Project ID |
| createdAt | string | 作成時間 (ISO 8601 形式) |
| status | string | エクスポートの現在の状態。可能な値は running, completed, failed。 |
| duration | long | データをエクスポートするのにかかった時間 (単位はミリ秒) |
| request | json | リクエスト引数 |
| result | json | エクスポートしたデータを説明する属性を含みます。result はエクスポートが問題なく終了したあとにのみ取得できます。結果を表す属性は以下をご覧ください。 |
| result.size | long | エクスポートデータの合計サイズ (バイト) |
| result.eventCount | long | エクスポートしたイベントの合計数 |
| result.intraDay | boolean | リクエストが現在の日付を含んでいるとき、その日のすべてのデータが含まれていない場合があります。最後の日付までデータが完全な場合、この属性は true です。 |
| result.fileList | json | エクスポートしたデータを含むファイルのリスト。データが何もないときは、ファイルリストは空です。 |
| result.fileList.name | string | ファイル名 |
| result.fileList.url | string | ファイルのダウンロード URL。ファイルは gzip 形式に圧縮されます。 |
| result.fileList.size | long | ファイルのサイズ (バイト) |
| result.fileList.date | string | ファイルはこの特定の日付のイベントを含みます。この日付はイベントの提出時間に基づいています。同じ日に複数のファイルがある場合があります。日付の形式は ISO 8601 です。 |
応答の例
{
"id":"8228d1e9-31b3-4a5e-aabe-55d9c8afa052",
"upid":"beff3f49-b9ed-41a4-91ea-677e9b85e71e",
"createdAt":"2016-05-10T10:10:10.100+0000",
"status":"running",
"duration" : 0,
"request":{
"startDate":"2016-05-01",
"endDate":"2016-05-02",
"format":"json",
"dataset":"appRunning"
}
}
以前の Raw Data Export からの継続
定期的に Raw Data Export を行うとき、確実に前の Raw Data Export から継続したい場合は、startDate の代わりに continueFrom 引数を渡す必要があります。以前の Raw Data Export ID は GET API 経由で取得したり、Dashboard 経由でアクセスすることができます。
Raw Data Export の取得
Raw Data Export や継続中のエクスポート状態を取得するには、以下の HTTP メソッドを使用します。
GET api/v2/projects/{UNITY_PROJECT_ID}/rawdataexports/{raw_data_export_id}
必要な引数はすべて URL パスに含まれています。
リクエストの例
curl --user {UNITY_PROJECT_ID}:${API_KEY} https://analytics.cloud.unity3d.com/api/v2/projects/{UNITY_PROJECT_ID}/rawdataexports/${ID}
応答は、JSON 形式の Raw Data Export です。Create Raw Data Export の応答と同様です。
応答の例
{
"id":"6601f70e-6a0b-48ed-909f-26711af82b49",
"status":"completed",
"createdAt":"2016-05-21T04:41:54.000+0000",
"duration":8631714000,
"request":{
"startDate":"2016-02-11T00:00:00.000+0000",
"endDate":"2016-03-11T00:00:00.000+0000",
"format":"tsv",
"dataset":"custom"
},
"result":{
"size":78355,
"eventCount":17473,
"fileList":[
{
"name":"headers.gz",
"url":"https://uca-export.s3.amazonaws.com/staging/devTest/custom/appid%3DUNITY_PROJECT_ID/jid%3D6601f70e-6a0b-48ed-909f-26711af82b49/headers.gz?AWSAccessKeyId=AKIAJUXGNF66F4XPWSWA&Expires=1463872651&Signature=PnzIeeI%2FNxSOlKkLVpLcfK%2FxVpU%3D",
"size":105
},
{
"name":"part-4b0cf376-3478-4bc8-845e-f73aff5c0be4.gz",
"url":"https://uca-export.s3.amazonaws.com/staging/devTest/custom/appid%3DUNITY_PROJECT_ID/jid%3D6601f70e-6a0b-48ed-909f-26711af82b49/part-4b0cf376-3478-4bc8-845e-f73aff5c0be4.gz?AWSAccessKeyId=AKIAJUXGNF66F4XPWSWA&Expires=1463872651&Signature=xZk3%2BzQNTQ6yjK2Mh%2FaH338ABn8%3D",
"size":78250,
"date":"2016-02-13T00:00:00.000+0000"
}
],
"intraDay":false
}
}
すべての Raw Data Exports のリスト
指定したプロジェクトのすべての Raw Data Exports のリストを取得するにはこの HTTP メソッドを使用します。
GET api/v2/projects/{UNITY_PROJECT_ID}/rawdataexports
必要な引数はすべて URL パスに含まれています。
リクエストの例
curl --user {UNITY_PROJECT_ID}:${API_KEY} https://analytics.cloud.unity3d.com/api/v2/projects/${UNITY_PROJECT_ID}/rawdataexports/
応答は、JSON 形式の Raw Data Exports のリストです。エクスポートリストの各要素の定義に関しては、Raw Data Export Response Attributes (応答属性) をご覧ください。
応答の例
[
{
"id":"6601f70e-6a0b-48ed-909f-26711af82b49",
"status":"completed",
"createdAt":"2016-05-21T04:41:54.000+0000",
"duration":8631714000,
"request":{
"startDate":"2016-02-11T00:00:00.000+0000",
"endDate":"2016-03-11T00:00:00.000+0000",
"format":"tsv",
"dataset":"custom"
},
"result":{
"size":78355,
"eventCount":17473,
"fileList":[
{
"name":"headers.gz",
"url":"https://uca-export.s3.amazonaws.com/staging/devTest/custom/appid%3DUNITY_PROJECT_ID/jid%3D6601f70e-6a0b-48ed-909f-26711af82b49/headers.gz?AWSAccessKeyId=AKIAJUXGNF66F4XPWSWA&Expires=1463872651&Signature=PnzIeeI%2FNxSOlKkLVpLcfK%2FxVpU%3D",
"size":105
},
{
"name":"part-4b0cf376-3478-4bc8-845e-f73aff5c0be4.gz",
"url":"https://uca-export.s3.amazonaws.com/staging/devTest/custom/appid%3DUNITY_PROJECT_ID/jid%3D6601f70e-6a0b-48ed-909f-26711af82b49/part-4b0cf376-3478-4bc8-845e-f73aff5c0be4.gz?AWSAccessKeyId=AKIAJUXGNF66F4XPWSWA&Expires=1463872651&Signature=xZk3%2BzQNTQ6yjK2Mh%2FaH338ABn8%3D",
"size":78250,
"date":"2016-02-13T00:00:00.000+0000"
}
],
"intraDay":false
}
},
{
"id":"6601f70e-6a0b-48ed-909f-26711af82b48",
"status":"completed",
"createdAt":"2016-05-21T04:41:54.000+0000",
"duration":8631714000,
"request":{
"startDate":"2016-02-11T00:00:00.000+0000",
"endDate":"2016-03-11T00:00:00.000+0000",
"format":"tsv",
"dataset":"custom"
},
"result":{
"size":78355,
"eventCount":17473,
"fileList":[
{
"name":"headers.gz",
"url":"https://uca-export.s3.amazonaws.com/staging/devTest/custom/appid%3DUNITY_PROJECT_ID/jid%3D6601f70e-6a0b-48ed-909f-26711af82b48/headers.gz?AWSAccessKeyId=AKIAJUXGNF66F4XPWSWA&Expires=1463872651&Signature=PnzIeeI%2FNxSOlKkLVpLcfK%2FxVpU%3D",
"size":105
},
{
"name":"part-4b0cf376-3478-4bc8-845e-f73aff5c0be4.gz",
"url":"https://uca-export.s3.amazonaws.com/staging/devTest/custom/appid%3DUNITY_PROJECT_ID/jid%3D6601f70e-6a0b-48ed-909f-26711af82b48/part-4b0cf376-3478-4bc8-845e-f73aff5c0be4.gz?AWSAccessKeyId=AKIAJUXGNF66F4XPWSWA&Expires=1463872651&Signature=xZk3%2BzQNTQ6yjK2Mh%2FaH338ABn8%3D",
"size":78250,
"date":"2016-02-13T00:00:00.000+0000"
}
],
"intraDay":false
}
}
]
TSV 形式
TSV 形式のエクスポートを選択する場合、ヘッダーは headers.gz の別のファイルで提供されます。データファイルはヘッダーを含んでいません。
ヘッダーファイルの例
ts appid type userid sessionid platform sdk_ver debug_device user_agent submit_time name custom_params
データセット
6 つのデータタイプ (イベントタイプ) はそれぞれ異なります。それらのスキーマの定義は、以下を参照してください。
注意
-
tsはイベントがデバイスで発生した timestamp (タイムスタンプ) です。デバイスで作成されたタイムスタンプは、デバイスの時間とイベントを受け取った時間の遅延により、ずれている場合があります。 -
submit_timeは Unity Analytics がイベントを受け取った timestamp (タイムスタンプ) です。 - record のフィールドにデータがない場合は、値はそのフィールドのデフォルトのデータ型に設定されます (数の場合は
0、文字列の場合は""、bool の場合はfalse)。IAP のTransactionEvent.receiptフィールドなどの入れ子式フィールドは、JSON 形式のエクスポートでは、この方法の例外です。入れ子式フィールドの JSON 形式のエクスポートでは、データのないフィールドはすべて、そのレコードの JSON オブジェクトに含まれません。
AppStart イベント
{
"namespace":"com.unity.analytics.commons.schema",
"name":"AppStartEvent",
"type":"record",
"fields":[
{"name": "ts", "type": "long", "default": 0},
{"name": "appid", "type": "string", "default": ""},
{"name": "type", "type": "string", "default": ""},
{"name": "userid", "type": "string", "default": ""},
{"name": "sessionid", "type": "string", "default": ""},
{"name": "platform", "type": "string", "default": ""},
{"name": "sdk_ver", "type": "string", "default": ""},
{"name": "debug_device", "type": "boolean", "default": false},
{"name": "user_agent", "type": "string", "default": ""},
{"name": "submit_time", "type": "long", "default": 0}
]
}
AppRunning イベント
{
"namespace":"com.unity.analytics.commons.schema",
"name":"AppRunningEvent",
"type":"record",
"fields":[
{"name": "ts", "type": "long", "default": 0},
{"name": "appid", "type": "string", "default": ""},
{"name": "type", "type": "string", "default": ""},
{"name": "userid", "type": "string", "default": ""},
{"name": "sessionid", "type": "string", "default": ""},
{"name": "remote_ip", "type": "string", "default": ""},
{"name": "platform", "type": "string", "default": ""},
{"name": "sdk_ver", "type": "string", "default": ""},
{"name": "debug_device", "type": "boolean", "default": false},
{"name": "user_agent", "type": "string", "default": ""},
{"name": "submit_time", "type": "long", "default": 0},
{"name": "duration", "type": "int", "default": 0}
]
}
Custom イベント
{
"namespace":"com.unity.analytics.commons.schema",
"name":"CustomEvent",
"type":"record",
"fields":[
{"name": "ts", "type": "long", "default": 0},
{"name": "appid", "type": "string", "default": ""},
{"name": "type", "type": "string", "default": ""},
{"name": "userid", "type": "string", "default": ""},
{"name": "sessionid", "type": "string", "default": ""},
{"name": "platform", "type": "string", "default": ""},
{"name": "sdk_ver", "type": "string", "default": ""},
{"name": "debug_device", "type": "boolean", "default": false},
{"name": "user_agent", "type": "string", "default": ""},
{"name": "submit_time", "type": "long", "default": 0},
{"name": "name", "type": "string", "default": ""},
{
"name":"custom_params",
"type":["null",{
"type":"map",
"values": ["string","null"],
"default": ""
}],
"default": null
}
]
}
DeviceInfo イベント
{
"namespace":"com.unity.analytics.commons.schema",
"name":"DeviceInfoEvent",
"type":"record",
"fields":[
{"name": "ts", "type": "long", "default": 0},
{"name": "appid", "type": "string", "default": ""},
{"name": "type", "type": "string", "default": ""},
{"name": "userid", "type": "string", "default": ""},
{"name": "sessionid", "type": "string", "default": ""},
{"name": "platform", "type": "string", "default": ""},
{"name": "sdk_ver", "type": "string", "default": ""},
{"name": "debug_device", "type": "boolean", "default": false},
{"name": "user_agent", "type": "string", "default": ""},
{"name": "submit_time", "type": "long", "default": 0},
{"name": "debug_build", "type": "boolean", "default": false},
{"name": "rooted_jailbroken", "type": "boolean", "default": false},
{"name": "processor_type", "type": "string", "default": ""},
{"name": "system_memory_size", "type": "string", "default": ""},
{"name": "make", "type": "string", "default": ""},
{"name": "app_ver", "type": "string", "default": ""},
{"name": "license_type", "type": "string", "default": ""},
{"name": "app_install_mode", "type": "string", "default": ""},
{"name": "model", "type": "string", "default": ""},
{"name": "engine_ver", "type": "string", "default": ""},
{"name": "os_ver", "type": "string", "default": ""},
{"name": "app_name", "type": "string", "default": ""},
{"name": "timezone", "type": "string", "default": ""},
{"name": "ads_tracking", "type": "boolean", "default": false}
]
}
Transaction イベント
{
"namespace":"com.unity.analytics.commons.schema",
"name":"TransactionEvent",
"type":"record",
"fields":[
{"name": "ts", "type": "long", "default": 0},
{"name": "appid", "type": "string", "default": ""},
{"name": "type", "type": "string", "default": ""},
{"name": "userid", "type": "string", "default": ""},
{"name": "sessionid", "type": "string", "default": ""},
{"name": "platform", "type": "string", "default": ""},
{"name": "sdk_ver", "type": "string", "default": ""},
{"name": "debug_device", "type": "boolean", "default": false},
{"name": "user_agent", "type": "string", "default": ""},
{"name": "submit_time", "type": "long", "default": 0}, {
"name":"receipt",
"type":["null",{
"type":"record",
"name": "receiptRecord",
"fields":[
{"name": "data", "type": "string", "default": ""},
{"name": "signature", "type": "string", "default": ""}
]
}],
"default": null
},
{"name": "currency", "type": "string", "default": "USD"},
{"name": "amount", "type": "float", "default": 0},
{"name": "transactionid", "type": "long", "default": 0},
{"name": "productid", "type": "string", "default": ""}
]
}
辞書
| データフィールド | 定義 | Event データセット |
|---|---|---|
| ts | イベントがデバイスで発生したタイムスタンプ (単位はミリ秒) です。デバイスで作成されたタイムスタンプは、デバイスの時間とイベントを受け取る時間の遅延により、ずれている場合があります。 | すべて |
| appid | Unity Analytics Dashboardで各アプリケーションに割り当てられる ID | すべて |
| type | クエリされるイベント種類 (例えば Custom, DeviceInfo, Transaction など) | すべて |
| userid | Unity Analytics が発行するユーザー ID | すべて |
| sessionid | Unity Analytics が生成するセッション ID。ゲームがアクティブでなくなってから 30分以上経過すると、新しいセッション ID が生成されます。 | すべて |
| remote_ip | セッションをプレイする IP アドレス。このフィールドは削除され、使用できません。 | 使用不可 |
| platform | セッションが行われるプラットフォーム | すべて |
| sdk_ver | イベントに使用される Unity Analytics SDK のバージョン。 sdk_ver が “u” で始まるときは、 Analytics ツール作成のエンジンから来ています。そうでない場合は、Unity 5.2 よりも古い版のAnalytics プラグインから来ています。 | すべて |
| debug_device | イベントが開発用ビルドから送信されているかどうかを示すbool値。Unity Editor から送られたイベントに対し true を返します。 | すべて |
| user_agent | User-Agent リクエストヘッダーフィールド | すべて |
| submit_time | Unity Analytics がイベントを受け取った時点のタイムスタンプ (単位はミリ秒) | すべて |
| duration | セッションが実行される時間 (秒)。SDK によって計算されます。 | AppRunning |
| name | Custom イベントの名前 (例えば “LevelComplete” など) | Custom |
| custom_params | Custom イベントのパラメーターと関連する値のリスト | Custom |
| receipt | プラットフォームのアプリストア (App Store や Google Play など) から返されたデータを含みます。 | Transaction |
| currency | ISO 4217 コードに基づく、支払いのための通貨コード (USD, EUR, CAD など) | Transaction |
| amount | 10 進数での合計使用料金 | Transaction |
| transactionid | SDK によって設定されるトランザクション固有のID。各トランザクションに固有の ID が割り当てられます。ストアのトランザクション ID と混乱しないように注意。 | Transaction |
| productid | アプリ内課金のストア固有のプロダクト ID (例えば com.mygame.100coins) | Transaction |
| debug_build | イベントが開発用ビルドから送信されているかどうかを示すbool値。Unity Editor から送られたイベントに対し true を返します。 | DeviceInfo |
| rooted_jailbroken | Root / Jailbreak 化されたデバイスが通常のデバイスの場合は true を返します。通常のデバイスには送信されません。 | DeviceInfo |
| processor_type | デバイスプロセッサーの種類 | DeviceInfo |
| system_memory_size | デバイスシステムメモリ | DeviceInfo |
| make | デバイスの製造者 (例えば “OSXEditor”) | DeviceInfo |
| app_ver | アプリケーションのバージョン (例えば “1.0”) | DeviceInfo |
| deviceid | 固有のデバイス識別子。このフィールドは削除され、使用できません。 | 使用不可 |
| license_type | ライセンスの種類 (例えば “advanced_pro”) | DeviceInfo |
| app_install_mode | アプリケーションが何を経由してインストールされたか。アプリストア (“store”)、アドホック (“adhoc”)、開発者用インストール (“dev_release”)、シミュレーター (“simulator”)、エンタープライズ (“enterprise”)。 | DeviceInfo |
| model | デバイスモデル (例えば “MacBookPro11,3”) | DeviceInfo |
| engine_ver | Unity エンジンバージョン (例えば “5.5.0a3”) | DeviceInfo |
| os_ver | OS バージョン (例えば “Mac OS X 10.11.5”) | DeviceInfo |
| app_name | バンドル識別子か、パッケージ名 (例えば “com.Company.ProductName”) | DeviceInfo |
| timezone | ISO コード (例えば “GMT–7”) | DeviceInfo |
| ads_tracking | ユーザーのアドトラッキングが制限されているかを示すbool値 | DeviceInfo |
| adsid | 広告 ID。iOS では、Unity Ads が有効の時に取得されます。Android では、常に取得されます。このフィールドは削除されており、使用できません。 | 使用不可 |