# Analytics REST API

> Send Analytics events from non-Unity games through the REST API.

Unity を使用しない開発者は、ウェブエンドポイントまたは REST API を介して API にアクセスできます。REST API はより柔軟性があり、好みの言語やゲーム開発エンジンを使用してワークフローを自動化することができます。

Analytics では以下の REST API が提供されています。

* [Analytics](https://services.docs.unity.com/analytics/v1)

## 推奨ガイド

### ランダムな一意の userID の生成

REST API は、ランダムな一意の userID を生成するための以下の方法を提供します。

`https://collect.analytics.unity3d.com/api/analytics/collect/v1/uuid`

[こちら](https://services.docs.unity.com/analytics/v1#/paths/~1api~1analytics~1collect~1v1~1uuid/get) の API ドキュメントを参照してください。

userID は、ユーザーに固有の ID です。Unity Gaming Services またはユーザーのライフサイクルの開始時に userID を生成する別のソリューションを使用している場合は、その userID を使用して Analytics REST API に送信します。ゲームに自分の userID がない場合は、それを作成するために Universally Unique Identifier (UUID) を生成することをお勧めします。戻り値をクライアントにローカルに格納し、その特定のクライアントからの将来のすべての Collect 呼び出しにそれを再利用する必要があります。使用しているものは **変更しないでください**。

ID がある場合は、ユーザーをこの値で識別できます。ただし、サードパーティに明白な userID を格納することを阻止するライセンス制限により、法的な制限がある可能性があります。この ID のハッシュを作成し、インテグレーションのためにそれを userID として使用することは、一般にこの問題の回避策です。これにより、userID を再度格納する必要がなくなります。

### Collect API エンドポイントへのイベントの送信

SDK を通じて送信できない (例えば、ゲームサーバーからの、または Unity 以外のゲーム用の) イベントがある場合、Collect REST API がイベントを記録して Unity に直接送信します。

`https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/{projectId}/environments/{environmentName}`

API ドキュメントは [こちら](https://services.docs.unity.com/analytics/v1#/paths/~1api~1analytics~1collect~1v1~1projects~1%5C%7BprojectId%5C%7D~1environments~1%5C%7BenvironmentName%5C%7D/post) にあります。

イベントを記録するには、Collect API に対して HTTP POST を行ってイベントを記録します。POST は UTF-8 エンコーディングする必要があります。HTTP リクエストヘッダーを `Content-Type: application/json` に設定し、以下の URL 形式のいずれかを使用します。

環境名を取得するには、プロジェクトの **Dashboard (ダッシュボード) > Projects (プロジェクト) > Project Settings (プロジェクト設定) > Environments (環境)** に移動します。

一連のカスタムイベントを環境ごとに設定できます。リクエスト本体には、後で説明するように、イベントタイプに対応する JSON ドキュメントを指定します。

ステータスコードが **204 No Content** の場合、イベントはサーバーで正常に受信されており、サーバーから返されるものはありません。

ステータスコードが 204 No Content 以外の場合は、リクエストを実施する際にエラーが発生しました。ステータスコードとメッセージによって、発生した問題がわかります。例: **400 Bad Request – "Custom Event Code not recognized**"。詳細は [こちら](https://services.docs.unity.com/analytics/v1/index.html#/paths/~1api~1analytics~1collect~1v1~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentName%7D/post) を参照してください。

イベントが Unity のサービスによって処理されたかどうかを確認するには、[イベントブラウザー](../events/event-browser) を参照して、イベントが自分のゲームからのものであることを確認します。

### イベントペイロード

すべてのイベントは、JSON ドキュメントとしてリクエストの本体でサーバーに送信する必要があります。ドキュメントは、イベントタイプごとに異なります。

エンドポイントが受け入れる 2 つの形式があります。

1. 単一イベント形式
2. 一括イベント形式

#### 1. 単一イベント形式

```cs
{
    "eventName": "specific event code - eg. gameStarted",
    "userID": "ABCD1-4321a879b185fcb9c6ca27abc5387e914",
    "unityInstallationID": "Optional-Installation-ID",
    "unityPlayerID": "Optional-Authenticated-Player-ID",
    "sessionID": "4879bf37-8566-46ce-9f3b-bd18d6ac614e",
    "eventUUID": "374cc674-9785-4772-8cca-d7cdf517a590",
    "eventTimestamp": "yyyy-mm-dd hh:mm:ss.SSS",
    "eventParams": {
        "platform": "WEB",
        "param1": "stringParam",
        "param2": true,
        "param3": 1234,
        "param4": [
            "a",
            "b",
            "c"
        ]
    }
}
```

必須でないパラメーターをドキュメントに組み込む必要はありません。空のパラメーターまたは null パラメーターを送信するのではなく、これらを省略します。**タイムスタンプが過去 31 日より前か今後 24 時間より先のイベントは、有効範囲外であるため拒否されます。**

#### 2. 一括イベント形式

複数のイベントを 1 つの POST で送信できます。このアプローチは、接続プーリングの効率性のために推奨されます。POST サイズは 5 MB 未満にしてください。それを超えると拒否されることがあります。

個別の各イベントの形式は同じですが、個々のイベントを保持する **eventList** 配列によって表されます。例:

```cs
{
  "eventList": [
    {
      "eventName": "clientDevice",
      "userID": "e44db226-5b29-11ec-819e-dca6325ca17a",
      "sessionID": "8ebb023e-6edc-11ec-a519-dca6325ca17a",
      "eventUUID": "02ff8461-8d1d-46bb-94f3-51c81e63b371",
      "eventVersion": 1,
      "eventTimestamp": "2022-01-06 03:29:17.030",
	  "eventParams": {
        "platform": "ANDROID",
        "userCountry": "US",
        "clientVersion": "2.0.3",
        "sdkMethod": "com.unity.services.analytics.Events.Startup"
      }
    },
    {
      "eventName": "gameStarted",
      "userID": "e44db226-5b29-11ec-819e-dca6325ca17a",
      "sessionID": "8ebb023e-6edc-11ec-a519-dca6325ca17a",
      "eventUUID": "a379af6c-4fac-4449-b6c7-925ee87b446e",
      "eventVersion": 1,
      "eventTimestamp": "2022-01-06 03:29:17.040",
      "eventParams": {
        "platform": "ANDROID",
        "userCountry": "US",
        "clientVersion": "2.0.3",
        "sdkMethod": "com.unity.services.analytics.Events.Startup",
        "userLocale": "en_US"
      }
    }
  ]
}
```

ノート: 一括イベントリストの内部のイベントは、発生した順に維持する必要があります。

### ddnaForgetMe イベントの送信

ddnaForgetMe イベントは、プレイヤーがデータのオプトアウトおよび削除をリクエストしていることを記録するために使用されます。UGS Analytics は、ペイロードの受信後 7 日以内のプレイヤーデータを削除します。

REST API を使用するが独自の UUID ジェネレーターがない場合は、Unity が UUID を生成する機能を提供します。

このイベントを送信した場合は、ユーザーのデータの送信も停止する必要があります。そうしないと、サービスがユーザーのデータを再度収集します。

```cs
{
     "eventName": "ddnaForgetMe",
     "eventTimestamp": "2020-01-01 12:00:00",
     "eventUUID": "foo",
     "eventVersion": 1,
     "sessionID": "foo",
     "userID": "foo",
     "eventParams": {
          "clientVersion": "foo",
          "sdkMethod": "foo"
     }
}
```

## PIPL についての同意の送信

中国の新しいデータプライバシー法 (個人情報保護法) は 2021 年 11 月 1 日に発効しました。個人情報とは、名前や住所など個人を特定できるデータです。電子的に、またはその他の方法で格納されます。機密とされる個人情報は、生体認証、性自認、宗教的信念、病歴、財政状態、および 14 歳未満のすべての個人情報です。

PIPL は、**オプトインに基づく規制** です。Collect エンドポイントでは、HTTP ヘッダーを使用して、中国にいるユーザーからの同意を識別します。

Collect へのすべての HTTP リクエストで、以下のヘッダーを適宜使用する必要があります。

| ヘッダー          | 説明                                                                                                         |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| PIPL\_CONSENT | このヘッダーの存在は、プレイヤーがデータ収集に同意したことを示します。  同意しないプレイヤーは、リクエストでこのヘッダーを設定してはなりません。ヘッダーの値は問題になりません。                  |
| PIPL\_EXPORT  | このヘッダーの存在は、データが処理のために中国国外に送信されることにプレイヤーが同意したことを示します。  同意しないプレイヤーは、リクエストでこのヘッダーを設定してはなりません。ヘッダーの値は問題になりません。 |

レスポンスヘッダー

PIPL 要件に該当する HTTP リクエストでは、レスポンスに PIPL\_STATUS ヘッダーを追加して、バックエンドによって実行されたアクションを確認することでテストを支援する必要があります。

| ヘッダー値       | 説明                                                        |
| ----------- | --------------------------------------------------------- |
| no\_consent | PIPL\_CONSENT リクエストヘッダーを介したこのリクエストへの同意がないことを示します。         |
| no\_export  | PIPL\_EXPORT リクエストヘッダーを介したこのデータエクスポートリクエストへの同意がないことを示します。 |

サンプルコード:

```cs
curl -v --location --request POST "https://collect.analytics.unity3d.com/collect/api/project/{id}/production" \
--header 'Content-Type: application/json' \
--header 'PIPL_CONSENT: true' \
--header 'PIPL_EXPORT: true' \
--data-raw "{
    \"userID\": \"some-id\",
    \"eventName\": \"gameStarted\",
    \"eventVersion\": 1,
    \"eventUUID\":\"some-uuid\",
    \"sessionID\": \"sessionID\",
    \"eventParams\": {
      \"platform\": \"ANDROID\",
      \"clientVersion\": \"testVersion\",
      \"sdkMethod\": \"UA1_SDKLESS\",
      \"userLocale\": \"aa_BB\"
      }
    }
}"
```