주요 콘텐츠로 건너뛰기

스토어 Get 웹훅

store.get 웹훅은 게임 허브 스토어의 플레이어가 이용 가능한 아이템 목록을 불러옵니다. 이는 게임 로직에 따라 스토어 콘텐츠를 표시하는 데 유용합니다.

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

  • 플레이어가 게임 허브에 로그인합니다.
  • 플레이어가 스토어를 엽니다.
  • 플레이어가 구매를 완료합니다.
스토어 Get 웹훅
스토어 Get 웹훅

요구 사항

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

  • POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
  • Aghanim이 생성하고 서명한 이벤트를 수신합니다.
  • 성공적으로 처리된 경우에는 2xx 상태 코드로 응답하며, 거부 또는 오류의 경우에는 4xx 또는 5xx를 응답합니다.

구성

  1. store.get 웹훅 처리를 위한 함수를 개발합니다.
  2. 엔드포인트를 사용 가능하게 설정하세요.
  3. Aghanim 계정 내에서 엔드포인트를 등록합니다 → 게임 → 웹훅 → 새 웹훅에서 store.get 이벤트 유형을 선택합니다.

대안으로, 웹후크 생성 API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

요청 스키마

아래는 예시입니다 store.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": "store.get",
  "event_data": {
    "player_id": "2D2R-OP3C"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.login",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트의 유형, store.get 이럴 경우.
event_timenumber유닉스 에포크 시간으로 된 이벤트 날짜.
event_dataEventData이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextEventContext|null이벤트에 대한 컨텍스트 정보.

EventContext 스키마

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

EventData 스키마

Key유형설명
player_idstring플레이어 인증을 위해 선택된 고유한 플레이어 ID.
is_anonymousboolean현재 사용자의 행동이 익명인지 여부

응답 스키마

응답이 성공적이면 서버는 2xx 범위의 상태 코드와 함께 다음 JSON 페이로드를 반환해야 합니다:

Key유형설명필수 여부
items`[Item\BundleItem]`스토어에서 플레이어가 이용 가능한 아이템 배열.
rolling_offersRollingOffer[]플레이어에게 제공되는 순환 혜택 배열아니오

아이템 스키마

Key유형설명필수 여부
skustring게임과 Aghanim 양쪽에서 맞춰진 아이템 SKU.예
start_atnumber아이템이 플레이어에게 제공되는 유닉스 타임스탬프입니다.아니오
end_atnumber아이템이 만료되어 플레이어가 더 이상 사용할 수 없게 되는 유닉스 타임스탬프입니다.아니요
max_purchasesnumber해당 품목에 허용되는 최대 구매 수입니다.아니오

BundleItem 스키마

Key유형설명필수 여부
skustring동적 번들 항목에 대한 고유 SKU 식별자예
pricenumber센트 단위로 표시한 USD 가격예
namestring번들 아이템 이름예
nested_itemsNestedItem[]번들에 포함된 아이템 배열.예
descriptionstring번들 아이템 설명아니오
image_urlstring번들 항목의 이미지 URL아니오
image_url_featuredstring번들 항목이 추천 항목으로 표시될 때의 이미지 URL입니다. 항목이 추천되었을 때만 적용됩니다.아니오
featured_card_background_image_urlstring번들 항목 카드의 추천 항목으로 표시될 때의 배경 이미지 URL입니다. 항목이 추천되었을 때만 적용됩니다.아니요
category_slugsstring[]번들 항목의 배치를 결정하기 위한 카테고리 슬러그 배열아니요
start_atnumber플레이어가 아이템을 사용할 수 있게 될 때의 Unix 타임스탬프.아니요
end_atnumber플레이어가 더 이상 아이템을 사용할 수 없게 되는 Unix 타임스탬프.아니요
max_purchasesnumber항목에 허용되는 최대 구매 수입니다. 한도가 도달하면 항목이 상점에서 사라집니다아니요
price_template_idstring각국의 가격 책정을 위해 사용할 가격 템플릿의 ID입니다.아니요
custom_badgestring번들의 맞춤 배지 텍스트아니요
bonus_itemsWebhookItemBonus[]번들에 포함된 보너스 아이템 배열아니요
bonus_badgestring보너스 아이템에 대한 배지 텍스트아니요
bonus_percentnumber첫 중첩 항목에 적용되는 보너스 백분율아니요
bonus_fixednumber첫 번재 중첩된 항목에 적용되는 고정 보너스 값입니다. 설정되면, bonus_percent는 무시됩니다.아니요
metadataobject항목에 대한 추가 정보를 저장하기 위한 키-값 쌍으로 구성된 메타데이터 객체입니다.아니요
view_optionItemViewOption항목의 상점 외관을 제어합니다. 허용되는 값: default, in_title

아니요
card_typeStoreCardType아이템을 상점에 표시하기 위해 사용되는 카드 유형: default, featured
아니요
free_claimsFreeClaims항목을 구입하는 대신 무료로 청구할 수 있도록 설정합니다.
아니요

NestedItem 스키마

Key유형설명필수 여부
skustring게임과 Aghanim 측 모두에서 일치하는 아이템 SKU.예
quantitynumber스택이 가능한 아이템의 경우, 중첩된 아이템의 개수아니요
is_featuredboolean번들 목록에 항목이 표시되는지 정의합니다.아니요
metadataobject항목에 대한 추가 정보를 저장하기 위한 키-값 쌍으로 구성된 메타데이터 객체입니다.아니요

WebhookItemBonus 스키마

Key유형설명필수 여부
sku문자열게임과 Aghanim 양쪽에서 맞춰진 아이템 SKU.예
quantitynumber스택이 가능한 아이템의 경우, 보너스 아이템의 개수아니요

FreeClaims 스키마

Key유형설명필수 여부
enabledboolean아이템이 구매 대신 무료로 청구될 수 있는지를 나타냅니다.
예
max_claimsnumber지정된 기간 내에 아이템을 청구할 수 있는 최대 횟수입니다.
예
periodPeriodmax_claims를 재설정하는 데 사용되는 기간 창입니다. 생략된 경우, 최대 청구 횟수에 도달한 후 제한이 재설정되지 않습니다.
아니요
exceeded_claims_behaviorExceededClaimsBehavior최대 청구 횟수에 도달한 후의 동작을 정의합니다. 허용되는 값: hide – 상점에서 아이템을 제거합니다; disable_with_timer – 다음 재설정까지 카운트다운과 함께 비활성화된 상태로 표시를 유지합니다. 기간이 생략되면 카운트다운이 표시되지 않고 항목이 비활성화된 상태로 유지됩니다.
아니요

기간 스키마

Key유형설명필수 여부
unitPeriodType청구 한도에 사용된 기간의 유형. 가능한 값: month, week, day, hour.
예
durationnumber기간의 길이, 단위로 지정된 단위로 측정됩니다 (예: 기간: 2, 단위: 일은 이틀 간격을 나타냅니다).
예

롤링오퍼 스키마

Key형식설명필수 여부
keystring항목이 구매되었거나 청구되었는지 여부를 결정하는 고유한 제공 키입니다.예
placement_keystringGame Hub에서 롤링 오퍼가 표시될 블록의 키입니다.예
namestring롤링 오퍼의 제목입니다.예
description문자열패키지 제공에 대한 설명입니다.예
rolling_itemsRollingItem[]롤링 오퍼에 포함된 항목 목록입니다.예
background_image_url문자열배경 이미지의 URL.아니요
background_sizestring배경 이미지의 크기. 가능한 값: contain, repeat, cover.아니요
expire_atnumber유닉스 타임스탬프로 표시되는 제안의 만료 시간. 제안 블록의 타이머는 이 순간까지 카운트다운하며, 도달하면 제안은 숨겨집니다.아니요

롤링아이템 스키마

Key형식설명필수 여부
skustring동적 번들 항목에 대한 고유 SKU 식별자.예
quantitynumber스택이 가능한 아이템의 경우, 중첩된 아이템의 개수.아니요
is_free_itemboolean아이템이 구매되는 대신 무료로 청구될 수 있는지를 나타냅니다.아니요

성공적인 응답 예시

{
  "items": [
    {
      "sku": "crystals"
    },
    {
      "sku": "shield",
      "start_at": 1630000000,
      "end_at": 1635000000
    },
    {
      "sku": "fly_bundle",
      "price": 2000,
      "name": "Fly Bundle",
      "description": "Fly Bundle Description",
      "image_url": "https://example.com/fly-bundle.png",
      "image_url_featured": "https://example.com/fly-bundle-featured.png",
      "featured_card_background_image_url": "https://example.com/fly-bundle-featured-background.png",
      "nested_items": [
        {
          "sku": "nested_item_sku_1"
        },
        {
          "sku": "nested_item_sku_2",
          "quantity": 200
        }
      ],
      "category_slugs": [
        "category_slug_1"
      ]
    },
    {
        "sku": "free-fly-bundle-with-timer",
        "name": "Fly Bundle",
        "description": "Bundle with fly and sword",
        "background_image_url": "https://example.com/background.jpg",
        "category_slugs": ["first"],
        "nested_items": [
            {"sku": "diamond-002", "quantity": 2},
            {"sku": "sword-thb"},
        ],
        "free_claims": {
            "enabled": True,
            "max_claims": 1,
            "period": {"unit": "day", "duration": 1},
            "exceeded_claims_behavior": "disable_with_timer",
        }
    }
  ], 
  "rolling_offers": [
    {
      "key": "rolling_offer_1",
      "placement_key": "place1",
      "name": "Dynamic Special Offer",
      "description": "Limited time offer",
      "rolling_items": [
        {
          "sku": "coins",
          "quantity": 256,
          "is_free_item": false
        },
        {
          "sku": "gold",
          "quantity": 999,
          "is_free_item": true
        }
      ],
      "background_image_url": "https://static-platform.aghanim.com/image.webp",
      "background_size": "cover",
      "expire_at": 1762964336
    }
}

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

On this page