스토어 Get 웹훅

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

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

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

요구 사항

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

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

구성

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

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

요청 스키마

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

HTTP
cURL

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",
    "is_anonymous": false,
    "placement_keys": null,
    "category_slugs": null,
    "current_page_path": "/store",
    "locale": "en"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.store.open",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}
            

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "store.get",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "is_anonymous": false,
        "placement_keys": null,
        "category_slugs": null,
        "current_page_path": "/store",
        "locale": "en"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "hub.store.open",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

이벤트 스키마

Key	유형	설명
`event_id`	`string`	Aghanim에 의해 생성된 고유 이벤트 ID.
`game_id`	`string`	Aghanim 시스템에서의 귀하의 게임 ID.
`event_type`	`string`	이벤트의 유형, `store.get` 이럴 경우.
`event_time`	`number`	유닉스 에포크 시간으로 된 이벤트 날짜.
`event_data`	`EventData`	이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
`idempotency_key`	`string`	웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다.
`request_id`	`string\|null`	이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
`sandbox`	`boolean`	이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
`trigger`	`string\|null`	The trigger that caused the event to be sent.
`transaction_id`	`string`	Aghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
`context`	`EventContext\|null`	이벤트에 대한 컨텍스트 정보.

EventContext 스키마

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

EventData 스키마

Key	유형	설명
`player_id`	`string`	플레이어 인증을 위해 선택된 고유한 플레이어 ID.
`is_anonymous`	`boolean`	현재 사용자가 인증되지 않음(익명)인지 여부를 나타냅니다.
`placement_keys`	`string[]\	null`
`category_slugs`	`string[]\	null`
`current_page_path`	`string\	null`
`locale`	`string`	현재 플레이어의 로케일 코드(ISO 639-1)입니다. 가능한 로케일의 전체 목록은 Locales에서 확인하세요.

트리거 값

값	설명
`hub.store.open`	상점이 열릴 때.
`hub.login`	플레이어가 Game Hub를 열 때, 프리페치가 활성화된 경우.
`hub.purchase`	플레이어가 상점에서 구매 버튼을 클릭할 때, 아이템이 여전히 플레이어에게 사용 가능한지 확인합니다.
`order.captured`	결제 처리가 시작되기 직전, 아이템이 여전히 플레이어에게 사용 가능한지 확인합니다.
`test`	Dashboard에서 "Send test event"를 사용할 때.

응답 스키마

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

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

아이템 스키마

Key	유형	설명	필수 여부
`sku`	`string`	항목에 대한 고유 SKU 식별자. 항목이 동적이면(Aghanim 대시보드에 동일한 SKU의 항목이 없는 경우) 가격과 이름을 설정해야 합니다.	예
`price`	`number`	센트 단위로 표시한 USD 가격.	아니요
`name`	`string`	항목의 이름입니다	아니오
`is_stackable`	`boolean`	항목이 스택 가능한지 여부	아니요
`quantity`	`number`	항목의 수량	아니요
`description`	`string`	항목의 설명입니다	아니오
`image_url`	`string`	항목의 이미지 URL	아니오
`background_image_url`	`string`	항목의 배경 이미지 URL	아니요
`background_image_color`	`string`	항목의 배경색	아니요
`image_url_featured`	`string`	추천 항목으로 표시될 때의 항목 이미지 URL입니다. 항목이 추천되었을 때만 적용됩니다.	아니요
`card_background_image_url`	`string`	항목 카드의 배경 이미지 URL	아니요
`category_slugs`	`string[]`	항목의 배치를 결정하기 위한 카테고리 슬러그 배열	아니요
`start_at`	`number`	아이템이 플레이어에게 제공되는 유닉스 타임스탬프입니다.	아니요
`end_at`	`number`	아이템이 만료되어 플레이어가 더 이상 사용할 수 없게 되는 유닉스 타임스탬프입니다.	아니요
`max_purchases`	`number`	해당 품목에 허용되는 최대 구매 수입니다. 한도가 도달하면 항목이 상점에서 사라집니다	아니요
`current_purchases`	`number`	현재 구매 수	아니요
`price_template_id`	`string`	각국의 가격 책정을 위해 사용할 가격 템플릿의 ID입니다.	아니요
`custom_badge`	`string`	항목의 커스텀 배지 텍스트	아니요
`bonus_items`	`WebhookItemBonus[]\	Item[]`	항목에 포함된 보너스 아이템 배열
`bonus_badge`	`문자열`	보너스 아이템에 대한 배지 텍스트	아니요
`bonus_percent`	`number`	첫 중첩 항목에 적용되는 보너스 백분율	아니요
`bonus_fixed`	`number`	첫 번재 중첩된 항목에 적용되는 고정 보너스 값입니다. 설정되면, bonus_percent는 무시됩니다.	아니요
`metadata`	`object`	항목에 대한 추가 정보를 저장하기 위한 키-값 쌍으로 구성된 메타데이터 객체입니다.	아니요
`view_option`	`ItemViewOption`	항목의 상점 외관을 제어합니다. 허용되는 값: `default`, `in_title`	아니요
`card_type`	`StoreCardType`	아이템을 상점에 표시하기 위해 사용되는 카드 유형: `default`, `featured`	아니요
`free_claims`	`FreeClaims`	항목을 구입하는 대신 무료로 청구할 수 있도록 설정합니다.	아니요
`show_disabled_by_max_purchases`	`boolean`	최대 구매 한도에 도달했을 때 항목을 비활성화된 것으로 표시할지 여부입니다.	아니요

BundleItem 스키마

Key	유형	설명	필수 여부
`sku`	`string`	번들 항목에 대한 고유 SKU 식별자. 항목이 동적이면(Aghanim 대시보드에 동일한 SKU의 항목이 없는 경우) 가격과 이름을 설정해야 합니다.	예
`price`	`number`	센트 단위로 표시한 USD 가격	아니요
`name`	`문자열`	번들 아이템 이름	아니요
`nested_items`	`NestedItem[]\	Item[]`	번들에 포함된 아이템 배열.
`description`	`string`	번들 아이템 설명	아니요
`image_url`	`string`	번들 항목의 이미지 URL	아니요
`background_image_url`	`string`	번들 항목의 배경 이미지 URL	아니요
`background_image_color`	`문자열`	번들 항목의 배경색	아니요
`image_url_featured`	`string`	번들 항목이 추천 항목으로 표시될 때의 이미지 URL입니다. 항목이 추천되었을 때만 적용됩니다.	아니요
`category_slugs`	`string[]`	번들 항목의 배치를 결정하기 위한 카테고리 슬러그 배열	아니요
`start_at`	`number`	플레이어가 아이템을 사용할 수 있게 될 때의 Unix 타임스탬프.	아니요
`end_at`	`number`	플레이어가 더 이상 아이템을 사용할 수 없게 되는 Unix 타임스탬프.	아니요
`max_purchases`	`number`	항목에 허용되는 최대 구매 수입니다. 한도에 도달하면 해당 항목은 스토어에서 사라집니다	아니요
`price_template_id`	`string`	각국의 가격 책정을 위해 사용할 가격 템플릿의 ID입니다.	아니요
`custom_badge`	`string`	번들의 맞춤 배지 텍스트	아니요
`bonus_items`	`WebhookItemBonus[]\	Item[] `	번들에 포함된 보너스 아이템 배열
`bonus_badge`	`string`	보너스 아이템에 대한 배지 텍스트	아니요
`bonus_percent`	`number`	nested_items에서 첫 번째로 중첩 가능한 항목에 적용되는 보너스 퍼센트	아니요
`bonus_fixed`	`number`	nested_items에서 첫 번째로 중첩 가능한 항목에 적용되는 고정 보너스 값입니다. 설정된 경우 bonus_percent는 무시됩니다.	아니요
`metadata`	`object`	항목에 대한 추가 정보를 저장하기 위한 키-값 쌍으로 구성된 메타데이터 객체입니다.	아니요
`view_option`	`ItemViewOption`	항목의 스토어 표시 방식을 제어합니다. 허용되는 값: `default`, `in_title`	아니요
`card_type`	`StoreCardType`	스토어에 표시하는 데 사용되는 항목 카드의 유형: `default`, `featured`	아니요
`free_claims`	`FreeClaims`	항목을 구매하는 대신 무료로 수령할 수 있도록 하는 설정입니다.	아니요
`show_disabled_by_max_purchases`	`boolean`	최대 구매 한도에 도달했을 때 항목을 비활성화된 것으로 표시할지 여부입니다.	아니요

NestedItem 스키마

Key	유형	설명	필수 여부
`sku`	`string`	게임과 Aghanim 양쪽에서 맞춰진 아이템 SKU.	예
`quantity`	`number`	스택이 가능한 아이템의 경우, 중첩된 아이템의 개수	아니요
`is_featured`	`boolean`	번들 목록에 항목이 표시되는지 정의합니다.	아니요
`metadata`	`object`	항목에 대한 추가 정보를 저장하기 위한 키-값 쌍으로 구성된 메타데이터 객체입니다.	아니요

WebhookItemBonus 스키마

Key	유형	설명	필수 여부
`sku`	`string`	게임과 Aghanim 측 모두에서 일치하는 아이템 SKU.	예
`quantity`	`number`	스택이 가능한 아이템의 경우, 보너스 아이템의 개수	아니요

FreeClaims 스키마

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

기간 스키마

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

롤링오퍼 스키마

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

롤링아이템 스키마

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

성공적인 응답 예시

{
  "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",
      "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
    }
}

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