주요 콘텐츠로 건너뛰기

일일 보상 웹훅

daily_reward.get 웹훅은 플레이어가 일일 보상 프로그램에서 받을 아이템을 결정합니다. 프로그램이 웹훅 기반으로 구성되어 있으면 Aghanim은 서버를 호출해 일차별로(그리고 추가 보상으로) 지급할 아이템을 묻고, 그 응답을 바탕으로 플레이어에게 보여줄 보상을 실시간으로 구성합니다.

이 웹훅은 두 종류의 프로그램에 사용됩니다:

  • 웹훅이 선택된 기본, 스케줄, 시즌 프로그램. 응답으로 아이템을 정하고, 주기는 Aghanim이 운영합니다.
  • 커스텀 프로그램. 응답으로 각 보상이 열리는 시점과 새 주기가 시작되는 시점까지 정합니다. 게임 허브에서 어떻게 보이는지는 일일 보상을 참조하세요.

이 웹훅은 다음과 같은 경우에 트리거됩니다:

  • 플레이어가 게임 허브에서 일일 보상 위젯을 열 때.
  • 플레이어가 일일 보상을 수령할 때.

서버가 응답하지 않거나, 2xx가 아닌 상태로 응답하거나, 타임아웃되거나, 유효하지 않은 본문을 반환하면 Aghanim은 프로그램의 정적 보상으로 대체합니다. 다만 프로그램에 웹훅을 선택하면 정적 보상이 지워지므로, 실제로는 프로그램에 보상이 표시되지 않고 수령도 실패합니다. 커스텀 프로그램에는 정적 보상이 아예 없습니다. 커스텀 프로그램의 오류를 참조하세요.

요구 사항

Aghanim의 daily_reward.get 웹훅을 사용하려면 웹훅 서버를 다음과 같이 구성해야 합니다:

  • POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
  • Aghanim이 생성하고 서명한 이벤트를 수신합니다.
  • 2xx 상태 코드와 보상 아이템을 설명하는 JSON 본문으로 응답합니다.
  • 빠르게 응답합니다. 응답이 느리면 허브 경험이 저하되고, 타임아웃이 발생하면 프로그램에 보상이 없는 상태가 됩니다.

구성

  1. daily_reward.get 웹훅 처리를 위한 함수를 개발합니다.
  2. 엔드포인트를 사용 가능하게 설정합니다.
  3. Aghanim 계정 내에서 Game → Webhooks → Add webhook에서 daily_reward.get 이벤트 유형을 선택하여 엔드포인트를 등록합니다.
  4. 일일 보상 프로그램 설정에서 웹훅을 선택하면 프로그램이 이 웹훅으로 아이템을 결정합니다. 커스텀 프로그램에는 웹훅이 필수입니다.
  5. 플레이어가 위젯을 열어 웹훅을 트리거할 수 있도록 게임 허브 페이지에 일일 보상 위젯을 배치합니다.

또는, Create Webhook API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

트리거 값

값설명
hub.interact플레이어가 게임 허브에서 일일 보상 위젯을 열 때.
hub.daily_reward_claim플레이어가 일일 보상을 수령할 때 — 지급할 아이템을 결정하기 위해. 커스텀 프로그램에서는 수령 전 사전 확인입니다. 커스텀 프로그램의 수령을 참조하세요.
testDashboard에서 "Send test event"를 사용할 때.

daily_reward.get이 다른 이벤트 유형과 어떻게 관련되는지에 대해서는 전체 이벤트 및 트리거 매트릭스를 참조하세요.

요청 스키마

아래는 예시입니다 daily_reward.get 웹훅 요청:

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "daily_reward.get",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "id": "dlrwd_eAeXgQGcaie",
    "key": "season-1",
    "is_anonymous": false
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.interact",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트의 유형, daily_reward.get 이럴 경우.
event_timenumberThe time the event was sent, in Unix epoch time. May differ across duplicate deliveries of the same event.
event_dataEventData이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring|null웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다. 일 수 있습니다 null 이벤트 유형에 따라 달라집니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|null이벤트가 전송된 원인이 된 트리거입니다.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextEventContext|null이벤트에 대한 컨텍스트 정보.

EventContext 스키마

Key유형설명
orderOrderContext|null해당되는 경우 이벤트와 관련된 주문 정보입니다.
playerPlayerContext|null플레이어 정보를 추가하려면 웹훅 설정에서 "플레이어 컨텍스트 추가"를 활성화하세요.

EventData 스키마

Key유형설명
player_idstring플레이어 인증을 위해 선택된 고유한 플레이어 ID.
idstringAghanim이 생성한 고유한 일일 보상 프로그램 ID.
keystring|null게임에서 정의한 일일 보상 프로그램의 키.
is_anonymousboolean현재 사용자가 인증되지 않음(익명)인지 여부를 나타냅니다.
progressDailyRewardProgress현재 주기에서의 플레이어 진행 상황. 커스텀 프로그램이면서 인증된 플레이어인 경우에만 전송됩니다.

DailyRewardProgress 스키마

Key유형설명
cycle_numbernumberAghanim이 부여하는 현재 주기 번호. 1부터 시작합니다.
claimsDailyRewardClaim[]현재 주기에서 플레이어가 수령한 일차. 주기 내 첫 수령 전까지는 비어 있습니다.

DailyRewardClaim 스키마

Key유형설명
day_numbernumber수령한 일차.
claimed_atnumber일차를 수령한 시각(Unix epoch 시간, 초 단위).

다음은 플레이어가 세 번째 주기의 1일차와 2일차를 수령한 커스텀 프로그램의 event_data 예시입니다:

{
  "id": "dlrwd_eAeXgQGcaie",
  "key": "daily",
  "player_id": "2D2R-OP3C",
  "is_anonymous": false,
  "progress": {
    "cycle_number": 3,
    "claims": [
      { "day_number": 1, "claimed_at": 1791100000 },
      { "day_number": 2, "claimed_at": 1791200000 }
    ]
  }
}

아직 아무것도 수령하지 않은 플레이어의 경우 progress는 { "cycle_number": 1, "claims": [] }입니다.

익명 플레이어에게는 진행 상황이 없습니다. 요청에는 is_anonymous: true가 포함되고 progress 블록은 없습니다. 커스텀 프로그램이라면 신규 플레이어와 마찬가지로 cycle_number를 1로 설정하고, available_at이 포함된 현재 일차(보통 1일차)와 최종 일차로 응답하세요. 익명 플레이어는 보상을 수령할 수 없습니다. 허브는 익명 플레이어에게 최종 보상을 보여주고 나머지 슬롯은 닫아 두며, 현재 일차가 아직 열리지 않았다면 카운트다운을 표시합니다.

응답 스키마

JSON 페이로드와 함께 200 OK를 반환합니다. 페이로드 형태는 프로그램 유형에 따라 다릅니다:

기본, 스케줄, 시즌 프로그램의 응답

응답은 프로그램의 보상을 완전히 대체합니다. 주기의 모든 일차와, 추가 보상이 있다면 추가 보상도 나열하세요. 예를 들어 7일 프로그램에 대해 1~3일차를 반환하면 프로그램은 3일이 됩니다. extra_reward_items를 생략하면 프로그램에 추가 보상이 없습니다.

Key유형설명필수 여부
daysDailyRewardDay[]보상 일차별로 지급되는 아이템. 최소 1일이 있어야 하며, 오름차순으로 1부터 빠짐없이 연속된 번호를 매겨야 합니다.예
extra_reward_itemsDailyRewardItem[]추가 보상으로 지급되는 아이템.아니오

어떤 일차의 SKU가 카탈로그와 하나도 일치하지 않으면 해당 일차는 프로그램에서 빠집니다. 이 유형의 프로그램이 커스텀 프로그램용인 cycle_number가 포함된 응답을 받으면 Aghanim은 응답을 무시하고 호출을 실패로 처리하므로 프로그램에 보상이 표시되지 않습니다.

DailyRewardDay 스키마

Key유형설명필수 여부
day_numbernumber아이템이 속한 보상 일차(≥ 1).예
itemsDailyRewardItem[]해당 일차에 지급되는 아이템(1~10개).예

응답 예시

{
  "days": [
    {
      "day_number": 1,
      "items": [
        { "sku": "sword-001", "quantity": 1 },
        { "sku": "coins-pack", "quantity": 500 }
      ]
    },
    {
      "day_number": 2,
      "items": [
        { "sku": "shield-001" }
      ]
    }
  ],
  "extra_reward_items": [
    { "sku": "gem-pack", "quantity": 10 }
  ]
}

커스텀 프로그램의 응답

플레이어 주기의 현재 상태, 즉 주기 번호, 현재 일차, 최종 일차를 반환합니다. Aghanim은 cycle_number로 커스텀 응답을 식별하므로, 이 필드가 없는 커스텀 응답은 유효하지 않습니다.

Key유형설명필수 여부
cycle_numbernumber현재 주기를 이어가려면 progress.cycle_number, 새 주기를 시작하려면 progress.cycle_number + 1. 커스텀 프로그램의 주기를 참조하세요.예
daysCustomDailyRewardDay[]day_number 오름차순으로 중복 없이 1개 또는 2개의 일차. 현재 일차가 먼저 오고 최종 일차가 뒤에 옵니다. 현재 일차가 최종 일차라면 그 일차만 보냅니다.예

extra_reward_items는 허용되지 않습니다. 커스텀 프로그램에는 추가 보상이 없습니다.

CustomDailyRewardDay 스키마

Key유형설명필수 여부
day_numbernumber주기 내 보상의 위치(≥ 1). 달력과 연동되지 않으며, 각 보상이 열리는 시점은 서버가 정합니다. 최종 일차의 번호가 주기 길이이며, 최대 365일입니다.예
available_atnumber일차가 열리는 시각(Unix epoch 시간, 초 단위). 이 시각이 지나면 해당 일차가 열리고 플레이어가 수령할 수 있습니다. 과거 시각이어도 괜찮습니다. 최종 일차에서는 최종 슬롯의 카운트다운에만 사용됩니다.현재 일차에 필수
itemsDailyRewardItem[]해당 일차에 지급되는 아이템(1~10개).예

이 규칙 중 하나라도 어긴 응답은 유효성 검사에 실패하며 오류로 처리됩니다. 커스텀 프로그램의 오류를 참조하세요.

응답 예시

이 예시의 요청은 1일차와 2일차를 수령한 상태에서 1791300000에 도착했습니다. 3일차는 1시간 후에 열리고, 최종 일차인 7일차는 그로부터 4일 후에 열립니다.

{
  "cycle_number": 3,
  "days": [
    {
      "day_number": 3,
      "available_at": 1791303600,
      "items": [{ "sku": "coins", "quantity": 500 }]
    },
    {
      "day_number": 7,
      "available_at": 1791649200,
      "items": [
        { "sku": "coins", "quantity": 5000 },
        { "sku": "boost" }
      ]
    }
  ]
}

DailyRewardItem 스키마

Key유형설명필수 여부
skustring보상으로 지급되는 아이템의 SKU. 카탈로그의 SKU와 일치해야 합니다.예
quantitynumber|null아이템 수량. 생략하면 아이템의 기본 수량이 사용됩니다.아니오
metadataobject|null고객사 측의 추가 로직을 지원하기 위한 아이템의 커스텀 키-값 쌍.아니오
노트

게임의 Aghanim 카탈로그에 있는 아이템과 일치하지 않는 SKU는 별도의 알림 없이 무시됩니다.

커스텀 프로그램의 주기

커스텀 프로그램에 대한 모든 요청에는 progress.cycle_number가 포함됩니다. 주기를 이어가려면 같은 번호로, 새 주기를 시작하려면 그 번호에 1을 더한 값으로 응답하세요.

플레이어가 최종 일차를 수령하면 곧바로 다음 주기로 응답하세요. cycle_number + 1과 available_at이 포함된 그 주기의 1일차를 보내면 됩니다. 그 시각까지 플레이어에게는 완료된 주기와 카운트다운이 보입니다. 1일차가 열리면 Aghanim이 새 주기를 시작하고, 이후 요청에는 새 cycle_number와 빈 claims가 담깁니다. 주기를 중간에 초기화할 때도 같은 방식으로 응답하세요.

새 주기는 다음 조건을 모두 충족할 때만 시작됩니다:

  • 응답의 cycle_number가 progress.cycle_number보다 1 큽니다.
  • 플레이어가 현재 주기에서 하나 이상의 일차를 수령했습니다.
  • 새 주기 1일차의 available_at이 지났습니다.

전환 후에는 요청에 새 번호가 담기므로, 같은 번호로 다시 응답하면 주기가 그대로 이어집니다.

7일 주기 예시에서 요청과 응답으로 전체 주기를 단계별로 살펴볼 수 있습니다.

커스텀 프로그램의 수령

플레이어가 일차를 수령하면 Aghanim은 hub.daily_reward_claim 트리거로 웹훅을 호출합니다. 이는 사전 확인입니다. 평소처럼 현재 상태로 응답하고, 서버 측에서는 수령을 기록하지 마세요. 요청에는 플레이어가 어느 일차를 수령하는지 포함되지 않습니다.

플레이어는 이 새 응답에서 해당 일차가 현재 일차이고 available_at이 지난 경우에만 보상을 받습니다. 그러면 Aghanim이 수령을 기록하고 item.add 웹훅으로 아이템을 전달하며, 이때 context.daily_reward.day_number에 수령한 일차가 담깁니다. 이 수령 기록은 이후 요청의 progress.claims에도 나타납니다.

수령을 거부하려면 미래 시각의 available_at을 반환하거나 다른 일차를 현재 일차로 반환하세요.

커스텀 프로그램의 오류

서버가 오류로 응답하거나, 유효하지 않은 본문을 반환하거나, 10초 이내에 응답하지 않으면 수령은 실패하고 플레이어는 아무것도 받지 못합니다. 커스텀 프로그램은 정적 보상으로 대체되지 않습니다. 플레이어가 위젯을 열 때 이런 일이 발생하면 허브는 보상 일차를 표시할 수 없습니다.

도움이 필요하신가요? 통합 팀 integration@aghanim.com으로 문의하세요.

도움이 필요하세요?
통합팀에 문의하십시오 integration@aghanim.com

On this page