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

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

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




## 마스터 데이터 포맷


**JSON**
```json
{
  "version": "2023-07-11",
  "bonusModels": [
    {
      "name": "[string]로그인 보너스 모델명",
      "metadata": "[string?]메타데이터",
      "mode": "[문자열 열거형]모드",
      "periodEventId": "[string?]기간 이벤트 GRN",
      "resetHour": "[int]리셋 시간(UTC)",
      "repeat": "[문자열 열거형]반복",
      "rewards": [
        {
          "acquireActions": [
            {
              "action": "[string]입수 액션에서 실행할 액션의 종류",
              "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
            }
          ]
        }
      ],
      "missedReceiveRelief": "[문자열 열거형]미수령 구제 기능",
      "missedReceiveReliefVerifyActions": [
        {
          "action": "[string]검증 액션에서 실행할 액션의 종류",
          "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
        }
      ],
      "missedReceiveReliefConsumeActions": [
        {
          "action": "[string]소비 액션에서 실행할 액션의 종류",
          "request": "[string]액션 실행 시 사용되는 요청의 JSON 문자열"
        }
      ]
    }
  ]
}
```


|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2023-07-11 | | 마스터 데이터 포맷 버전 |
| bonusModels | [List&lt;BonusModel&gt;](#bonusmodel) |  |  |  |  ~ 100 items | 로그인 보너스 모델<br>로그인 보너스 모델에는 로그인 보너스의 배포 스케줄을 설정합니다.<br>배포 스케줄에는 《스케줄 모드》와 《스트리밍 모드》가 있습니다.<br><br>스케줄 모드에서는 GS2-Schedule의 이벤트 지정이 필수이며, 해당 이벤트의 시작일로부터 경과한 일수에 따라 보너스를 배포합니다.<br>도중에 놓친 날짜가 발생한 경우, 그 날의 보너스는 배포되지 않습니다.<br><br>스트리밍 모드에서는 매일 보너스에 설정된 보상을 처음부터 순서대로 배포합니다.<br>스트리밍 모드에서는 반복 설정이 가능합니다. 이 경우 스트림의 끝에 도달하면 다시 처음부터 배포를 시작합니다.<br><br>스케줄 모드·스트리밍 모드 모두 미수령 구제 기능이 있습니다.<br>일정한 비용을 지불함으로써 놓친 보너스를 수령할 수 있습니다.<br>단, GS2-Schedule의 이벤트가 연결되어 있는 경우, 이벤트 시작일로부터 경과한 일수보다 앞선 보너스는 받을 수 없습니다.<br>미수령 구제 기능은 스트리밍 모드이면서 반복이 활성화된 경우에는 사용할 수 없습니다.<br><br>스케줄 모드·스트리밍 모드 모두, 설정 가능한 보너스의 최대 일수는 100일입니다. |

## 모델

### BonusModel

로그인 보너스 모델<br>

로그인 보너스 모델에는 로그인 보너스의 배포 스케줄을 설정합니다.<br>
배포 스케줄에는 《스케줄 모드》와 《스트리밍 모드》가 있습니다.<br>

스케줄 모드에서는 GS2-Schedule의 이벤트 지정이 필수이며, 해당 이벤트의 시작일로부터 경과한 일수에 따라 보너스를 배포합니다.<br>
도중에 놓친 날짜가 발생한 경우, 그 날의 보너스는 배포되지 않습니다.<br>

스트리밍 모드에서는 매일 보너스에 설정된 보상을 처음부터 순서대로 배포합니다.<br>
스트리밍 모드에서는 반복 설정이 가능합니다. 이 경우 스트림의 끝에 도달하면 다시 처음부터 배포를 시작합니다.<br>

스케줄 모드·스트리밍 모드 모두 미수령 구제 기능이 있습니다.<br>
일정한 비용을 지불함으로써 놓친 보너스를 수령할 수 있습니다.<br>
단, GS2-Schedule의 이벤트가 연결되어 있는 경우, 이벤트 시작일로부터 경과한 일수보다 앞선 보너스는 받을 수 없습니다.<br>
미수령 구제 기능은 스트리밍 모드이면서 반복이 활성화된 경우에는 사용할 수 없습니다.<br>

스케줄 모드·스트리밍 모드 모두, 설정 가능한 보너스의 최대 일수는 100일입니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| bonusModelId | string |  | ※ |  |  ~ 1024자 | 로그인 보너스 모델 GRN<br>※ 서버가 자동으로 설정 |
| name | string |  | ✓ |  |  ~ 128자 | 로그인 보너스 모델명<br>로그인 보너스 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string |  |  |  |  ~ 2048자 | 메타데이터<br>메타데이터에는 임의의 값을 설정할 수 있습니다.<br>이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| mode | 문자열 열거형<br>enum {<br>"schedule",<br>"streaming"<br>}<br> |  | ✓ |  |  | 모드<br>로그인 보너스의 배포 스케줄 종류를 지정합니다.<br>"schedule" 모드에서는 GS2-Schedule의 이벤트 시작일로부터 경과한 일수를 기준으로 보상이 배포됩니다.<br>"streaming" 모드에서는 달력 날짜와 관계없이 매일 처음부터 순서대로 보상이 배포됩니다.schedule: 스케줄 모드 / streaming: 스트리밍 모드 /  |
| periodEventId | string |  |  |  |  ~ 1024자 | 기간 이벤트 GRN<br>로그인 보너스를 활성화할 기간을 나타내는 GS2-Schedule의 이벤트 GRN입니다.<br>스케줄 모드에서는 필수이며, 보상 배포의 경과 일수를 계산하는 기준이 되는 시작일을 결정합니다.<br>스트리밍 모드에서는 생략 가능하지만, 지정한 경우 이벤트 시작일로부터 경과한 일수보다 앞선 보너스는 받을 수 없게 됩니다. |
| resetHour | int | {periodEventId} == "" | ✓※ |  | 0 ~ 23 | 리셋 시간(UTC)<br>수령 플래그가 리셋되는 시각(0~23, UTC)입니다.<br>로그인 보너스에서 날짜가 바뀌는 시점을 결정합니다.<br>periodEventId가 지정되지 않은 경우에만 필요합니다. 이벤트가 설정되어 있는 경우, 리셋 시점은 이벤트의 스케줄을 따릅니다.<br>※ periodEventId이(가) "" 이면 필수 |
| repeat | 문자열 열거형<br>enum {<br>"enabled",<br>"disabled"<br>}<br> | {mode} == "streaming" | ✓※ |  |  | 반복<br>모든 보상을 배포한 후, 처음부터 다시 배포할지 여부입니다.<br>스트리밍 모드에서만 유효합니다. 활성화하면 마지막 보상을 배포한 후 첫 번째 보상으로 돌아가 반복됩니다.<br>주의: 반복이 활성화된 경우, 미수령 구제 기능은 사용할 수 없습니다.enabled: 활성화 / disabled: 비활성화 / <br>※ mode이(가) "streaming" 이면 필수 |
| rewards | [List&lt;Reward&gt;](#reward) |  |  |  | 0 ~ 100 items | 보상 목록<br>날짜별 보상의 순서가 지정된 목록입니다. 각 항목은 하루치 로그인 보너스에 대응하며, 인덱스 0부터 순서대로 배포됩니다.<br>스케줄 모드에서는 인덱스가 이벤트 시작일로부터 경과한 일수에 대응합니다.<br>스트리밍 모드에서는 인덱스가 로그인 일수에 대응합니다. 최대 100개 항목까지 설정할 수 있습니다. |
| missedReceiveRelief | 문자열 열거형<br>enum {<br>"enabled",<br>"disabled"<br>}<br> |  |  | "disabled" |  | 미수령 구제 기능<br>놓친 보너스의 구제 기능을 활성화할지 여부입니다. 활성화하면 사용자는 지정된 비용(소비 액션)을 지불함으로써 받지 못한 보너스를 소급하여 수령할 수 있습니다.<br>필요에 따라 구제를 허용하기 전에 조건을 확인하는 검증 액션도 설정할 수 있습니다.<br>스트리밍 모드이면서 반복이 활성화된 경우에는 사용할 수 없습니다. 기본값은 "disabled"입니다.enabled: 활성화 / disabled: 비활성화 /  |
| missedReceiveReliefVerifyActions | [List&lt;VerifyAction&gt;](#verifyaction) | {missedReceiveRelief} == "enabled" |  | [] | 0 ~ 10 items | 미수령 구제 검증 액션 목록<br>미수령 구제를 허용하기 전에 실행되는 검증 액션의 목록입니다.<br>구제 처리 전에 사용자의 자격 등 전제 조건을 확인합니다. 최대 10개까지 설정할 수 있습니다.<br>missedReceiveRelief가 활성화된 경우에만 적용됩니다.<br>※ missedReceiveRelief이(가) "enabled" 이면 활성화 |
| missedReceiveReliefConsumeActions | [List&lt;ConsumeAction&gt;](#consumeaction) | {missedReceiveRelief} == "enabled" |  | [] | 0 ~ 10 items | 미수령 구제 소비 액션 목록<br>놓친 보너스를 구제하기 위해 사용자가 지불해야 하는 비용을 정의하는 소비 액션의 목록입니다.<br>예를 들어 게임 내 화폐나 아이템을 구제 비용으로 소비하도록 설정할 수 있습니다. 최대 10개까지 설정할 수 있습니다.<br>missedReceiveRelief가 활성화된 경우에만 적용됩니다.<br>※ missedReceiveRelief이(가) "enabled" 이면 활성화 |

---

### Reward

보상<br>

로그인 보너스의 하루치 보상 설정을 나타냅니다.<br>
각 Reward에는 사용자가 수신할 항목(아이템, 화폐, 경험치 등)을 정의하는 입수 액션 목록이 포함됩니다.<br>
BonusModel의 rewards 배열은 하루당 하나의 Reward를 보유하며, 순서대로 배포됩니다.<br>
보상 값은 버프 시스템(BonusModelBuff)을 통해 실행 시점에 변경할 수 있으며, 입수 액션에 배율을 적용할 수 있습니다.

|  | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| acquireActions | [List&lt;AcquireAction&gt;](#acquireaction) |  | ✓ |  | 1 ~ 10 items | 입수 액션 목록<br>이 날짜의 보상으로 사용자에게 부여되는 리소스를 정의하는 입수 액션 목록.<br>각 액션은 입수 액션(아이템 추가, 화폐 부여 등)과 그 요청 파라미터를 지정합니다.<br>보상당 최소 1개, 최대 10개의 액션을 설정할 수 있습니다. |

---

### ConsumeAction

소비 액션<br>

소비 액션의 구조를 통해 사용자로부터 리소스를 소비하는 액션을 정의합니다.<br>
미수령 보너스 구제에서 사용자가 지불해야 하는 비용(화폐 차감, 아이템 소비 등)을 지정하는 데 사용됩니다.<br>
action 필드는 소비 액션의 종류를 지정하고, request 필드에는 그에 대응하는 요청 매개변수가 포함됩니다.

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

---

### VerifyAction

검증 액션<br>

작업을 실행하기 전에 조건을 검증하는 액션을 정의합니다.<br>
미수령 보너스 구제에서 구제를 허용하기 전에 전제 조건(사용자 자격, 리소스 이용 가능 여부 등)을 확인하는 데 사용됩니다.<br>
action 필드는 검증 액션의 종류를 지정하고, request 필드에는 그에 대응하는 요청 매개변수가 포함됩니다.

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

---

### AcquireAction

획득 액션<br>

획득 액션의 구조를 통해 사용자에게 리소스를 부여하는 액션을 정의합니다.<br>
보상 내에서 사용되며, 사용자가 받는 것(인벤토리에 아이템 추가, 화폐 부여, 경험치 부여 등)을 지정합니다.<br>
action 필드는 획득 액션의 종류를 지정하고, request 필드에는 그에 대응하는 요청 매개변수가 포함됩니다.

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

---