Analytics REST API
Send Analytics events from non-Unity games through the REST API.
읽는 시간 2분최근 업데이트: 7일 전
Unity를 사용하지 않는 개발자는 웹 엔드포인트 또는 REST API를 통해 API에 액세스할 수 있습니다. REST API를 사용하면 유연성이 향상되어 원하는 언어와 게임 개발 엔진을 사용해 워크플로를 자동화할 수 있습니다. Analytics는 다음 REST API를 제공합니다.
베스트 프랙티스
고유한 무작위 userID 생성
REST API에서 제공하는 다음 메서드로 고유한 무작위 userID를 생성할 수 있습니다.https://collect.analytics.unity3d.com/api/analytics/collect/v1/uuidCollect API 엔드포인트에 이벤트 제출
SDK를 통해 전송할 수 없는 이벤트(예: 게임 서버에서 발생한 이벤트 또는 Unity로 제작되지 않은 게임의 이벤트)가 있는 경우에는 Collect REST API가 이벤트를 기록하고 Unity에 바로 전송합니다.https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/{projectId}/environments/{environmentName}Content-Type: application/json이벤트 페이로드
모든 이벤트는 요청 본문 안에 JSON 문서 형태로 서버에 전송되어야 합니다. 이 문서는 이벤트 유형별로 다르게 적용됩니다. Collect 엔드포인트는 두 가지 포맷을 수용합니다.- 단일 이벤트 포맷
- 일괄 이벤트 포맷
1. 단일 이벤트 포맷
필요 없는 파라미터는 문서에 포함하지 않아도 됩니다. 빈 파라미터나 null 파라미터를 보내는 대신 해당 파라미터를 생략합니다. 타임스탬프가 31일 전보다 오래되었거나 향후 24시간보다 이후인 이벤트는 유효한 경계를 벗어나므로 거부됩니다.{ "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" ] }}
2. 일괄 이벤트 포맷
단일 POST로 여러 이벤트를 전송할 수 있습니다. 연결 풀링 시에는 이러한 접근 방식이 효율성 면에서 바람직합니다. POST 길이를 5MB 미만으로 유지해야 합니다. 그보다 길면 거부될 수 있습니다. 개별 이벤트의 포맷은 그대로 유지되지만, 이벤트는 개별 이벤트가 포함된 eventList 배열로 표시됩니다. 예를 들면 다음과 같습니다.참고: 일괄 이벤트 목록 내에 있는 이벤트는 발생한 순서대로 유지되어야 합니다.{ "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를 생성하는 기능을 제공합니다. 이 이벤트를 전송한 경우에도 해당 사용자에 대한 데이터 전송을 중지해야 합니다. 그러지 않으면 서비스에서 해당 사용자에 대한 데이터를 다시 수집합니다.{ "eventName": "ddnaForgetMe", "eventTimestamp": "2020-01-01 12:00:00", "eventUUID": "foo", "eventVersion": 1, "sessionID": "foo", "userID": "foo", "eventParams": { "clientVersion": "foo", "sdkMethod": "foo" }}
PIPL 동의 전송
중국의 새로운 데이터 개인정보 보호법인 PIPL(개인정보 보호법)이 2021년 11월 1일부로 시행되었습니다. 개인정보는 이름이나 주소와 같이 개인을 식별할 수 있는 데이터로, 전자적 방법 등으로 저장됩니다. 민감한 개인정보란 생체 정보, 성 정체성, 종교적 신념, 병력, 재무 정보와 더불어 14세 미만 미성년자의 모든 개인정보를 의미합니다. PIPL은 동의를 원칙으로 하는 법입니다. Unity의 Collect 엔드포인트는 HTTP 헤더를 사용하여 중국에 있는 사용자의 동의를 파악합니다. 해당하는 경우 Collect에 대한 모든 HTTP 요청에 다음 헤더가 사용됩니다.헤더 | 설명 |
|---|---|
| PIPL_CONSENT | 이 헤더가 있으면 플레이어가 데이터 수집에 동의했음을 나타냅니다. 요청 시 동의하지 않는 플레이어에게 이 헤더를 설정하면 안 됩니다. 헤더의 값은 중요하지 않습니다. |
| PIPL_EXPORT | 이 헤더가 있으면 플레이어가 자신의 데이터를 중국 밖으로 전송하여 처리하는 데 동의했음을 나타냅니다. 요청 시 동의하지 않는 플레이어에게 이 헤더를 설정하면 안 됩니다. 헤더의 값은 중요하지 않습니다. |
헤더 값 | 설명 |
|---|---|
| no_consent | PIPL_CONSENT 요청 헤더를 통해 이 요청에 대한 동의가 제공되지 않았음을 나타냅니다. |
| no_export | PIPL_EXPORT 요청 헤더를 통해 데이터를 익스포트하기 위한 이 요청에 대한 동의가 제공되지 않았음을 나타냅니다. |
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\" } }}"