> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Inbox 마스터 데이터 레퍼런스

마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2020-03-12",
  "globalMessages": [
    {
      "name": "[string]글로벌 메시지 이름",
      "metadata": "[string]메타데이터",
      "readAcquireActions": [
        {
          "action": "[string]입수 액션에서 실행할 액션의 종류",
          "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
        }
      ],
      "expiresTimeSpan": {
        "days": "[int]일수",
        "hours": "[int]시간",
        "minutes": "[int]분"
      },
      "messageReceptionPeriodEventId": "[string?]메시지 수신 기간 이벤트 ID"
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2020-03-12 | | 마스터 데이터 포맷 버전 |
| globalMessages | [List&lt;GlobalMessage&gt;](#globalmessage) |  |  |  |  ~ 1000 items | 글로벌 메시지<br>글로벌 메시지는 게임 플레이어 전체에게 메시지를 전달하는 구조입니다.<br><br>글로벌 메시지에는 유효 기간을 설정할 수 있으며, 각 게임 플레이어는 글로벌 메시지를 수신하는 처리를 실행함으로써<br>유효 기간 내의 글로벌 메시지 중 아직 수신하지 않은 메시지를 자신의 메시지함에 복사합니다. |

## 모델

### GlobalMessage

글로벌 메시지<br>

글로벌 메시지는 게임 플레이어 전체에게 메시지를 전달하는 구조입니다.<br>

글로벌 메시지에는 유효 기간을 설정할 수 있으며, 각 게임 플레이어는 글로벌 메시지를 수신하는 처리를 실행함으로써<br>
유효 기간 내의 글로벌 메시지 중 아직 수신하지 않은 메시지를 자신의 메시지함에 복사합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| globalMessageId | string |  | ※ |  |  ~ 1024자 | 전체 사용자 대상 메시지 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 글로벌 메시지 이름<br>글로벌 메시지 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  | ✓ |  |  ~ 4096자 | 메타데이터<br>메시지의 제목, 본문, 표시 파라미터 등을 포함하는 JSON 문자열 등, 글로벌 메시지의 내용을 나타내는 임의의 데이터입니다. 사용자가 이 글로벌 메시지를 수신하면 메타데이터는 수신함 내의 개별 메시지로 복사됩니다. GS2는 이 값을 해석하지 않습니다. 최대 4096자입니다. |
| readAcquireActions | [List&lt;AcquireAction&gt;](#acquireaction) |  |  | [] | 0 ~ 100 items | 개봉 시 획득 액션<br>이 글로벌 메시지에서 복사된 메시지를 사용자가 개봉했을 때 실행되는 획득 액션 목록입니다. 이 액션들은 메타데이터와 함께 각 사용자의 개별 메시지로 복사됩니다. 글로벌 메시지당 최대 100개의 액션입니다. |
| expiresTimeSpan | [TimeSpan](#timespan) |  |  |  |  | 유효 기한까지의 기간<br>사용자가 이 글로벌 메시지를 수신(복사)한 시각부터, 복사된 메시지가 만료되어 수신함에서 자동 삭제되기까지의 기간입니다. 일, 시간, 분의 조합으로 지정합니다. 유효 기한에 도달하면 메시지는 읽음 상태와 관계없이 삭제되며, 아직 받지 않은 첨부 보상도 함께 삭제됩니다. |
| messageReceptionPeriodEventId | string |  |  |  |  ~ 1024자 | 메시지 수신 기간 이벤트 ID<br>이 글로벌 메시지를 수신(사용자의 수신함에 복사)할 수 있는 시간대를 정의하는 GS2-Schedule 이벤트의 GRN입니다. 이 기간 외에는 사용자가 글로벌 메시지 수신 작업을 실행하더라도 메시지가 전달되지 않습니다. 기간 한정 이벤트 공지나 시즌 캠페인 보상에 유용합니다. |

---

### TimeSpan

타임스팬<br>

일, 시간, 분의 조합으로 기간을 나타냅니다. 수신 시각을 기준으로 한 메시지의 유효 기간을 정의하는 데 사용됩니다. 예를 들어 7일, 0시간, 0분의 타임스팬은 사용자가 수신한 후 정확히 1주일 후에 메시지가 만료됨을 의미합니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| days | int |  |  | 0 | 0 ~ 365 | 일수<br>이 타임스팬의 일수입니다. 시간, 분과 조합하여 총 기간이 계산됩니다. 최대 365일입니다. |
| hours | int |  |  | 0 | 0 ~ 24 | 시간<br>이 타임스팬의 시간 수입니다. 일수, 분과 조합하여 총 기간이 계산됩니다. 최대 24시간입니다. |
| minutes | int |  |  | 0 | 0 ~ 60 | 분<br>이 타임스팬의 분수입니다. 일수, 시간과 조합하여 총 기간이 계산됩니다. 최대 60분입니다. |

---

### AcquireAction

획득 액션<br>

보상으로 메시지에 첨부되는 단일 획득 액션을 나타냅니다. 액션 타입(예: 인벤토리에 아이템 추가, 통화 증가)과 그 요청 파라미터로 구성됩니다. 메시지가 개봉되면 이 액션들이 트랜잭션으로 조립되어 실행되고, 사용자에게 보상이 지급됩니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형<br>enum {<br>}<br> |  | ✓ |  |  | 입수 액션에서 실행할 액션의 종류 |
| request | string |  | ✓ |  |  ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |

---