일일 보상

일일 보상 프로그램은 플레이어를 게임 허브로 다시 불러옵니다. 프로그램은 여러 보상 일차로 이루어진 주기입니다. 플레이어가 허브에서 일차별 보상을 수령하면 Aghanim이 item.add 웹훅으로 게임에 아이템을 전달합니다.

프로그램은 Aghanim 계정에서 관리하거나 Create Daily Reward 및 Update Daily Reward API 방법으로 관리합니다.

프로그램 유형

프로그램 유형은 basic, schedule, seasonal, custom 네 가지입니다.

basic, schedule, seasonal 프로그램에서는 Aghanim이 주기를 운영하고 각 보상이 열리는 시점을 정합니다. 보상은 프로그램 설정에서 가져오며, 프로그램에 웹훅을 선택한 경우에는 daily_reward.get 웹훅에서 가져옵니다.

custom 프로그램에서는 게임 서버가 주기를 운영합니다. 커스텀 프로그램을 참조하세요.

여러 프로그램이 동시에 활성화되어 있으면 허브는 그중 하나만 표시하며, 유형별로 다음 우선순위에 따라 선택합니다: seasonal, custom, schedule, basic.

닫힌 슬롯의 플레이스홀더

모든 프로그램 유형에는 hidden_image_url 설정이 있습니다. 아직 열리지 않은 보상 슬롯에 허브가 표시하는 이미지입니다. 프로그램 설정에서 지정하거나 API에 rewards.hidden_image_url을 전달하세요. 설정하지 않으면 허브는 기본 플레이스홀더를 사용합니다.

커스텀 프로그램

커스텀 프로그램에서는 게임 서버가 daily_reward.get 웹훅을 통해 주기 전체를 제어합니다. 일차별 아이템, 다음 보상이 열리는 시점, 새 주기의 시작을 모두 서버가 정합니다. Aghanim은 플레이어의 수령 기록을 저장하고, 아이템을 전달하고, 허브에 프로그램을 렌더링합니다. 보상 시점이 달력이 아니라 게임 로직에 따라 달라질 때 사용하세요.

플레이어에게는 현재 보상과 최종 보상만 보입니다. 나머지 슬롯은 플레이어가 해당 일차에 도달할 때까지 닫혀 있습니다.

커스텀 프로그램 설정

커스텀 응답을 반환하는 daily_reward.get 웹훅을 구현하고, Aghanim 계정에서 daily_reward.get 이벤트 유형으로 등록합니다.
커스텀 유형의 일일 보상 프로그램을 만들고 웹훅을 선택합니다. 웹훅은 필수입니다. API를 사용하는 경우 type: "custom"과 webhook_id를 전달합니다.
게임 허브 페이지에 일일 보상 위젯을 배치합니다.

게임당 커스텀 프로그램은 하나만 만들 수 있습니다. 커스텀 프로그램은 정적 보상과 mode를 사용하지 않으며, 보상은 항상 서버에서 옵니다.

플레이어가 허브에서 보는 화면

수령한 일차에는 플레이어가 받은 아이템이 표시됩니다.
현재 일차의 아이템은 해당 일차가 열린 후에만 표시됩니다.
최종 보상은 항상 표시됩니다.
현재 일차와 최종 일차는 서버가 열리는 시각을 보냈다면 닫혀 있는 동안 카운트다운을 표시합니다.
나머지 일차는 모두 닫힌 상태로 hidden_image_url 플레이스홀더를 표시합니다.
주기 전체를 수령하면 플레이어에게 모든 보상을 받았다는 표시와 함께 새 주기까지의 카운트다운이 보입니다.

익명 플레이어는 보상을 수령할 수 없습니다. 익명 플레이어에게는 최종 보상과, 현재 일차가 아직 열리지 않았다면 그 카운트다운이 보이고, 나머지 슬롯은 모두 닫혀 있습니다.

주기의 작동 방식

플레이어가 위젯을 열거나 보상을 수령할 때마다 Aghanim은 현재 주기에서의 플레이어 진행 상황, 즉 주기 번호와 지금까지 수령한 일차를 담아 웹훅을 호출합니다. 서버는 현재 상태로 응답합니다. 현재 상태는 주기 번호, 그리고 열리는 시각이 포함된 현재 일차와 최종 일차입니다. Aghanim은 이 응답으로 허브 화면을 구성하고, 모든 수령 요청을 새로 받은 응답과 대조해 확인합니다. Aghanim이 수령 기록을 저장하므로 서버는 전달받은 진행 상황만으로 상태를 계산할 수 있습니다.

플레이어가 최종 일차를 수령하면 곧바로 다음 주기 번호와 그 주기의 1일차로 응답하세요. 새 주기는 그 1일차가 열리면 시작됩니다. 정확한 규칙은 웹훅 레퍼런스에 있습니다.

예시: 7일 주기

이 예시에서는 한 플레이어가 7일 주기를 진행하는 과정을 따라갑니다. 게임은 간단한 규칙을 사용합니다. 각 보상은 이전 수령 후 24시간 뒤에 열리고, 새 주기는 최종 수령 후 24시간 뒤에 열립니다. 응답에서 available_at으로 표현할 수 있다면 규칙은 무엇이든 괜찮습니다. 모든 시각은 UTC 기준입니다.

1. 첫 방문

10월 1일 10:00. 플레이어가 위젯을 처음 열었으므로 요청에 수령 기록이 없습니다:

"progress": { "cycle_number": 1, "claims": [] }

서버는 1일차를 바로 엽니다. 최종 일차에 대해서는 플레이어가 매일 수령할 경우 7일차가 열릴 수 있는 가장 이른 시각을 보냅니다:

{
  "cycle_number": 1,
  "days": [
    { "day_number": 1, "available_at": 1790848800, "items": [{ "sku": "coins", "quantity": 100 }] },
    { "day_number": 7, "available_at": 1791367200, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

플레이어에게는 코인 100개가 담긴 열린 1일차, 닫힌 2~6일차, 카운트다운이 표시된 7일차 보상이 보입니다.

2. 1일차 수령

10월 1일 10:01. 플레이어가 1일차를 수령합니다. Aghanim은 먼저 hub.daily_reward_claim 트리거와 동일한 진행 상황으로 웹훅을 호출합니다. 서버는 1단계와 같은 응답을 반환하고 아무것도 기록하지 않습니다. 1일차가 현재 일차이고 열려 있으므로 Aghanim은 수령을 기록하고 context.daily_reward.day_number를 1로 설정한 item.add를 보냅니다.

허브가 프로그램을 새로 고치면 요청에 해당 수령 기록이 포함됩니다:

"progress": {
  "cycle_number": 1,
  "claims": [{ "day_number": 1, "claimed_at": 1790848860 }]
}

2일차는 수령 24시간 후에 열립니다:

{
  "cycle_number": 1,
  "days": [
    { "day_number": 2, "available_at": 1790935260, "items": [{ "sku": "coins", "quantity": 200 }] },
    { "day_number": 7, "available_at": 1791367260, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

플레이어에게는 1일차의 코인 100개와 2일차의 24시간 카운트다운이 보입니다. 2일차 아이템은 열리기 전까지 숨겨져 있습니다.

3. 2일차 열림

10월 2일 18:30. 플레이어가 다시 방문합니다. 서버는 2단계와 같은 응답을 반환하지만 이제 available_at이 과거 시각이므로 2일차가 열려 있습니다. 플레이어는 코인 200개를 확인하고 수령합니다.

4. 최종 일차

플레이어가 3일차부터 6일차까지 수령하며, 마지막 수령은 10월 6일 09:00입니다. 7일차는 24시간 후에 열립니다. 이제 현재 일차가 최종 일차이므로 days에는 요소가 하나뿐입니다:

{
  "cycle_number": 1,
  "days": [
    { "day_number": 7, "available_at": 1791363600, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

5. 주기 완료

10월 7일 20:00. 플레이어가 7일차를 수령하고, 다음 요청에는 일곱 개의 수령 기록이 모두 담깁니다. 서버는 곧바로 다음 주기로 응답합니다:

{
  "cycle_number": 2,
  "days": [
    { "day_number": 1, "available_at": 1791489600, "items": [{ "sku": "coins", "quantity": 100 }] },
    { "day_number": 7, "available_at": 1792008000, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

주기 2의 1일차는 24시간 후에야 열리므로 Aghanim은 허브에 주기 1을 계속 표시합니다. 플레이어에게는 일곱 개의 보상을 모두 받았다는 표시와 새 주기까지의 카운트다운이 보입니다.

6. 새 주기

10월 8일 21:00. 요청에는 여전히 주기 1과 일곱 개의 수령 기록이 담겨 있고, 서버는 5단계와 같은 응답을 반환합니다. 이번에는 1일차가 이미 열려 있으므로 Aghanim이 주기 2를 시작합니다. 플레이어에게는 코인 100개가 담긴 열린 1일차, 닫힌 2~6일차, 최종 보상이 보입니다. 새 주기에서 첫 수령이 있기 전까지 요청에는 { "cycle_number": 2, "claims": [] }가 담깁니다.

플레이어가 하루를 놓친 경우처럼 주기를 중간에 초기화하려면 같은 방식으로 cycle_number + 1과 그 주기의 1일차로 응답하세요. 어느 단계에서든 수령을 거부하려면 미래 시각의 available_at을 반환하세요. 커스텀 프로그램의 수령을 참조하세요.

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]