# 지원되는 UGS 이벤트

> Learn about the events emitted by Unity Gaming Services that you can use to trigger Cloud Code scripts or modules.

Unity Gaming Services는 플레이어 활동과 게임 상태에 대한 정보를 제공할 수 있는 이벤트를 발생시킵니다. 이러한 이벤트를 사용하면 해당 이벤트 유형으로 트리거 구성을 생성하여 Cloud Code 스크립트나 모듈을 트리거할 수 있습니다.

이벤트가 트리거 구성에 어떻게 매칭되는지 확인하려면 [트리거 구조](../tutorials/define-triggers/trigger-structure)를 참고하십시오.

> **Note:**
>
> **참고:** 이 페이지는 UGS에서 발생시키는 이벤트를 다룹니다. Scheduler 서비스도 Cloud Code 스크립트나 모듈을 트리거하는 데 사용할 수 있는 이벤트를 발생시킵니다. 일정 구성을 생성하는 방법에 대한 가이드라인은 [이벤트 예약](../tutorials/schedule-events/rest-api)을 참고하십시오.

Unity Gaming Services에서 발생시키는 이벤트 목록은 아래 표를 참고하시기 바랍니다.

| 서비스            | 이벤트 이름                    | 발생하는 시점                                                                                    |
| -------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
| Authentication | [가입](#signed-up)          | 플레이어가 Authentication 서비스에 가입하면 발생합니다. 생성된 플레이어는 로그인되기 때문에 [로그인](#signed-in) 이벤트도 함께 발생합니다. |
| Authentication | [로그인](#signed-in)         | 플레이어가 Authentication 서비스에 로그인하거나 토큰을 새로 고칠 때 발생합니다.                                        |
| Leaderboards   | [초기화](#reset)             | 리더보드를 초기화하면 발생합니다.                                                                         |
| Leaderboards   | [점수 제출](#score-submitted) | 플레이어가 리더보드에 점수를 제출하면 발생합니다.                                                                |
| Cloud Save     | [키 저장](#key-saved)        | Cloud Save 키가 플레이어 또는 엔티티를 저장하면 발생합니다.                                                     |
| Moderation     | [플레이어 액션](#player-action) | 플레이어 액션은 중재됩니다.                                                                            |

## Authentication##authentication

[Authentication 서비스](/authentication.md)에서 제공하는 이벤트를 사용하면 신규 플레이어의 참여를 유도하고, 로그인 보너스를 제공하고, 복귀 플레이어에게 보상을 제공할 수 있습니다.

Unity Runtime에서 플레이어를 인증하는 경우 이벤트가 발생한 후 플레이어 인증 플로가 완료됩니다.

### 가입##signed-up

Authentication 서비스에서 플레이어가 생성되면 가입 이벤트가 발생합니다. 생성된 플레이어는 로그인되기 때문에 [로그인](#signed-in) 이벤트도 함께 발생합니다.

이벤트 유형: `com.unity.services.player-auth.signed-up.v1`

이벤트 페이로드는 아래 표를 참고하십시오.

| 필드           | 설명                                                       | 유형  |
| ------------ | -------------------------------------------------------- | --- |
| `playerId`   | 여러 디바이스와 외부 제공업체에서 기존 및 신규 플레이어를 식별하는 데 사용되는 영숫자 문자열입니다. | 문자열 |
| `providerId` | 로그인에 사용된 제공자입니다.                                         | 문자열 |
| `createdAt`  | 플레이어 계정이 생성된 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다.              | 문자열 |

이벤트에서 `playerId`로 [플레이어 가져오기 엔드포인트](https://services.docs.unity.com/player-auth/v1/#tag/Player-authentication/operation/getplayer)를 호출하여 전체 플레이어 정보를 가져올 수 있습니다.

[사용 사례 샘플: 새로 가입한 플레이어를 기본 구성 값으로 초기화](../tutorials/use-cases/initialize-new-players)에서 이 이벤트를 사용하는 방법의 예시를 확인할 수 있습니다.

### 로그인##signed-in

로그인 이벤트는 플레이어가 Authentication 서비스에 로그인하거나 토큰을 새로 고칠 때 발생합니다.

이벤트 유형: `com.unity.services.player-auth.signed-in.v1`

이벤트 페이로드는 아래 표를 참고하십시오.

| 필드                | 설명                                                       | 유형  |
| ----------------- | -------------------------------------------------------- | --- |
| `playerId`        | 여러 디바이스와 외부 제공업체에서 기존 및 신규 플레이어를 식별하는 데 사용되는 영숫자 문자열입니다. | 문자열 |
| `providerId`      | 로그인에 사용된 제공자입니다.                                         | 문자열 |
| `createdAt`       | 플레이어 계정이 생성된 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다.              | 문자열 |
| `lastLoginAt`     | 플레이어가 마지막으로 로그인한 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다.          | 문자열 |
| `previousLoginAt` | 플레이어가 이전에 로그인한 날짜를 나타내는 RFC3339 포맷의 타임스탬프입니다.            | 문자열 |

이벤트에서 `playerId`로 [플레이어 가져오기 엔드포인트](https://services.docs.unity.com/player-auth/v1/#tag/Player-authentication/operation/getplayer)를 호출하여 전체 플레이어 정보를 가져올 수 있습니다.

## Leaderboards##leaderboards

[Leaderboards 서비스](/leaderboards.md)에서 제공하는 이벤트를 사용하면 플레이어의 참여를 유도할 수 있습니다.

### 초기화##reset

초기화 이벤트는 리더보드가 초기화되면 발생합니다.

이벤트 유형: `com.unity.services.leaderboards.reset.v1`

이벤트 페이로드는 아래 표를 참고하십시오.

| 필드                     | 설명             | 유형  |
| ---------------------- | -------------- | --- |
| `leaderboardId`        | 리더보드 ID입니다.    | 문자열 |
| `leaderboardVersionId` | 리더보드 버전 ID입니다. | 문자열 |

이 이벤트를 사용하여 리더보드의 상위 플레이어에게 보상을 제공하거나 플레이어를 다른 티어로 승격 또는 강등시킬 수 있습니다.

[사용 사례 샘플: 시즌 종료 시 상위 플레이어에게 게임 내 재화로 보상 제공](../tutorials/use-cases/reward-top-players)에서 이 이벤트를 사용하는 방법의 예시를 확인할 수 있습니다.

### 점수 제출##score-submitted

Leaderboards 서비스는 플레이어가 리더보드에 점수를 제출하면 점수 제출 이벤트를 발생시킵니다.

이벤트 유형: `com.unity.services.leaderboards.score-submitted.v1`

이벤트 페이로드는 아래 표를 참고하십시오.

| 필드              | 설명                                     | 유형     |
| --------------- | -------------------------------------- | ------ |
| `leaderboardId` | 점수가 제출된 리더보드 ID입니다.                    | 문자열    |
| `updatedTime`   | 점수가 제출된 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다. | 문자열    |
| `playerId`      | 플레이어 ID입니다.                            | 문자열    |
| `playerName`    | 플레이어 이름입니다.                            | 문자열    |
| `rank`          | 플레이어의 순위입니다.                           | 정수     |
| `score`         | 제출된 점수입니다.                             | double |
| `tier`          | 플레이어의 티어입니다. 티어가 없는 리더보드의 빈 문자열입니다.    | 문자열    |
| `bucketId`      | 버킷 ID입니다. 버킷이 없는 리더보드의 빈 문자열입니다.       | 문자열    |

이 이벤트를 사용하여 플레이어의 참여를 유도할 수 있습니다. 예를 들어 리더보드에서 다른 플레이어를 뛰어넘은 플레이어를 확인하거나 특정 순위에 도달한 플레이어에게 보상을 지급할 수 있습니다.

[사용 사례 샘플: 순위가 떨어진 플레이어에게 푸시 메시지 전송](../tutorials/use-cases/higher-score-message)에서 이 이벤트를 사용하는 방법의 예시를 확인할 수 있습니다.

## Cloud Save##cloud-save

[Cloud Save](/cloud-save.md) 서비스는 플레이어 관련 항목이 업데이트되면 플레이어에게 알림을 보내 플레이어의 참여를 유도할 수 있는 이벤트를 제공합니다.

### 키 저장##key-saved

키 저장 이벤트는 Cloud Save에 있는 플레이어 또는 엔티티의 항목이 저장되면 발생합니다.

이벤트 유형: `com.unity.services.cloud-save.key-saved.v1`

이벤트 페이로드는 아래 표를 참고하십시오.

| 필드              | 설명                                                                     | 유형     |
| --------------- | ---------------------------------------------------------------------- | ------ |
| `id`            | 이벤트와 연관된 플레이어 또는 엔티티의 ID입니다. `idType`과 상응합니다.                          | 문자열    |
| `idType`        | 항목 세트 ID 유형(`custom` 또는 `player`)입니다.                                  | 문자열    |
| `key`           | Cloud Save 항목의 키입니다.                                                   | 문자열    |
| `valueIncluded` | Cloud Save 항목의 값이 이벤트에 포함되는지 여부입니다. 크기가 128b 미만인 값만 반환됩니다.             | bool   |
| `value`         | Cloud Save 항목의 값입니다. 크기가 128b 미만인 값만 반환됩니다.                            | object |
| `writeLock`     | Cloud Save 항목의 쓰기 잠금입니다.                                               | 문자열    |
| `accessClass`   | 항목의 액세스 클래스입니다. `default`, `public`, `private`, `protected`가 될 수 있습니다. | 문자열    |
| `modifiedDate`  | 항목이 수정된 날짜를 나타내는 RFC3339 포맷의 타임스탬프입니다.                                 | 문자열    |

이 이벤트를 사용하면 플레이어의 항목이 업데이트될 때 플레이어에게 알림을 보내 참여를 유도할 수 있습니다.

## Moderation##moderation

[Moderation 서비스](/safe-text/overview.md)는 플레이어 동작 관리에 도움이 되는 이벤트를 제공합니다. Moderation 서비스를 통해 플레이어 액션이 중재될 때 실행되도록 Cloud Code에서 커스텀 액션을 정의할 수 있습니다. 예를 들어 Cloud Code에서 커스텀 액션을 정의하여 이벤트가 발생할 때 특정 게임 모드에서 플레이어를 차단할 수 있습니다.

> **Note:**
>
> **참고:** 중재 유형 Cloud Code 스크립트는 워크플로에서 [커스텀 액션을 관리](/safe-text/custom-actions.md)하며, 시작하는 데 도움이 되는 템플릿을 제공합니다. 기본적으로 게임 클라이언트에서는 이러한 스크립트를 실행할 수 없습니다. 자세한 내용은 [스크립트 유형](/cloud-code/scripts/how-to-guides/script-types.md)을 참고하십시오.

### 플레이어 액션##player-action

플레이어 액션 이벤트는 플레이어 액션이 중재될 때 발생합니다.

이벤트 유형: `com.unity.services.moderation.player-action-event.v1`

이벤트 페이로드는 아래 표를 참고하십시오.

| 필드                  | 설명                                                                                     | 유형          |
| ------------------- | -------------------------------------------------------------------------------------- | ----------- |
| `playerActionId`    | 이벤트와 관련된 플레이어 액션의 UUID입니다.                                                             | 문자열         |
| `incidentId`        | 플레이어 액션이 적용된 중재 인시던트의 UUID입니다.                                                         | 문자열         |
| `eventType`         | 액션과 연결된 이벤트 유형입니다. 플레이어 액션이 적용되는 경우 값은 `apply`이며, 취소되는 경우 `revoke`입니다.                 | 문자열         |
| `actionName`        | 적용되는 플레이어 액션 유형에 대한 ID입니다.                                                             | 문자열         |
| `actionDisplayName` | 적용되는 플레이어 액션 유형의 표시 이름입니다.                                                             | 문자열         |
| `actionReason`      | 플레이어 액션이 적용되거나 취소되는 이유입니다.                                                             | 문자열         |
| `actionComment`     | 액션이 적용되거나 취소되는 이유에 대해 중재자가 제공하는 설명입니다.                                                 | 문자열         |
| `moderatorName`     | 이 플레이어 액션을 담당하는 중재자입니다.                                                                | 문자열         |
| `playerUasId`       | 영향받은 플레이어의 uas ID입니다.                                                                  | 문자열         |
| `playerName`        | 영향받은 플레이어의 사용자 이름입니다. 플레이어 이름이 검색되지 않으면 이 값은 `playerUasId`와 동일한 값으로 채워집니다.             | 문자열         |
| `oneTimeAction`     | 이 플레이어 액션이 일회성 액션인지 여부를 정의합니다.                                                         | bool        |
| `createdAt`         | 플레이어 액션이 생성된 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다.                                            | 문자열         |
| `expiresAt`         | 플레이어 액션이 만료될 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다. 플레이어 액션이 영구적이거나 일회성 액션인 경우 null이 될 수 있습니다. | 문자열 또는 null |
| `deactivatedAt`     | 플레이어 액션이 취소된 시점을 나타내는 RFC3339 포맷의 타임스탬프입니다. 플레이어 액션이 취소되지 않은 경우 null이 될 수 있습니다.        | 문자열 또는 null |
| `externalIds`       | 플레이어의 외부 ID 맵입니다. 키는 제공자 ID이며 값은 외부 ID입니다.                                             | object      |