跳至主要内容

商店数据获取 Webhook

store.get Webhook 用于获取当前应向特定玩家显示的 游戏枢纽 商店商品列表。 该功能特别适合根据游戏逻辑动态显示商店内容。

此 Webhook 在以下情况下触发：

  • 玩家登录游戏枢纽时触发。
  • 玩家点击打开商店界面时触发。
  • 玩家完成商品购买后触发。
Get store webhook
Get store webhook

要求

如需接入阿哈利姆的 store.get Webhook，请按照以下要求配置您的 Webhook 服务器：

  • HTTPS 端点，可接收 POST Webhook 请求。
  • 监听由阿哈利姆生成并 签名 的事件。
  • 使用 2xx 状态码表示成功处理，使用 4xx 或 5xx 状态码表示拒绝或错误。

配置步骤

  1. 为 store.get Webhook 处理开发一个函数。
  2. 部署您的端点使其可访问。
  3. 进入您的Aghanim账户后，依次导航至 游戏 → Webhook → 新建 Webhook，然后在事件类型列表中选择store.get事件。

或者，您也可以使用 Create Webhook API 方法在阿哈利姆中注册您的端点。

Request Schema

下面是一个 store.get Webhook 请求示例：

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

事件 Schema

键名类型描述
event_idstring阿哈利姆生成的唯一事件标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
event_typestring事件的类型， store.get 在此情境下。
event_timenumber以 Unix 时间戳表示的事件发生日期。
event_dataEventData包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_keystring即使出现重试情况，也能确保 Webhook 操作只执行一次。
request_idstring|null如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
sandboxboolean标识事件是否来自沙盒测试环境的指示器。
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstring阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
contextEventContext|null事件的相关上下文信息。

EventContext Schema

键名类型描述
orderOrderContext|null与事件相关的订单信息（如果适用）。
playerPlayerContext|null（可选）玩家信息。如需启用，请在webhook设置中选择“添加玩家上下文”。

EventData Schema

键名类型描述
player_idstring用于玩家身份验证的唯一 玩家 ID。
is_anonymousboolean指示当前用户是否未通过身份验证（匿名）。
placement_keys`string[]\null`
category_slugs`string[]\null`
current_page_path`string\null`
区域设置string当前玩家的区域设置代码（ISO 639-1）。 在 Locales 中查找可能的区域设置完整列表。

触发器值

值描述
hub.store.open当商店打开时。
hub.login当玩家打开 Game Hub 时，如果已启用预取。
hub.purchase当玩家点击商店中的购买按钮，以验证该物品是否仍然对玩家可用。
order.captured在付款处理开始之前，以验证该物品是否仍然对玩家可用。
test在 Dashboard 中使用 "Send test event" 时。

Response Schema

当您的服务器成功处理请求时，应返回 2xx 系列状态码以及符合以下格式的 JSON 数据：

键名类型描述是否必需
items`[Item\BundleItem]`应向该玩家展示的所有商品列表，包括单独商品和礼包。
rolling_offersRollingOffer[]玩家可选择的滚动优惠数组否

Item Schema

键名类型描述是否必需
skustring商品的唯一 SKU 标识符。 如果商品是动态的（Aghanim 仪表板中没有 SKU 相同的商品），则必须设置价格和名称。是
pricenumber价格（美分）。否
namestring商品名称否
is_stackableboolean商品是否可堆叠否
quantitynumber商品的数量否
descriptionstring商品描述否
image_urlstring商品图片的 URL否
background_image_urlstring商品背景图片的 URL否
background_image_colorstring商品的背景颜色否
image_url_featuredstring商品作为推荐商品展示时的图片 URL。 仅在商品被推荐时适用。否
card_background_image_urlstring商品卡片的背景图片 URL否
category_slugsstring[]用于确定该商品在商店中分类和展示位置的标识符数组。否
start_atnumber商品对玩家可见并可购买的起始时间（Unix 时间戳）。否
end_atnumber商品对玩家不再可见或可购买的结束时间（Unix 时间戳）。否
max_purchases数字限制玩家能够购买该商品的最大次数。 一旦达到限制，该商品将从商店中消失否
current_purchasesnumber当前购买次数否
price_template_idstring将用于不同国家定价的价格模板的 ID。否
custom_badgestring商品的专属标识徽章文本否
bonus_items`WebhookItemBonus[]\Item[]`商品中包含的奖励商品数组
bonus_badgestring关于奖励物品的徽章文本否
bonus_percentnumber在nested_items中首次可堆叠项应用的奖励百分比否
bonus_fixed数字应用于嵌套项目中第一个可堆叠项目的固定奖励值。 如果设置，bonus_percent 将被忽略。否
metadataobject自定义的键值对数据对象，用于存储与商品相关的额外信息。否
view_optionItemViewOption控制商品在商店中的显示方式。 允许的值：default, in_title

否
card_typeStoreCardType用于在商店中显示的商品卡片类型：default, featured
否
free_claimsFreeClaims将物品设置为可以免费领取而不是购买。
否
show_disabled_by_max_purchasesboolean当达到最大购买限制时，是否将商品显示为不可用
否

BundleItem Schema

键名类型描述是否必需
skustring礼包商品的唯一 SKU 标识符。 如果商品是动态的（Aghanim 仪表板中没有 SKU 相同的商品），则必须设置价格和名称。是
price数字价格（美分）。否
namestring礼包在商店中显示的名称。否
nested_items`NestedItem[]\Item[]`礼包内包含的所有单独商品组成的数组。
描述string礼包的详细描述文本。否
image_urlstring礼包图片的 URL。否
background_image_urlstring礼包图片的 URL。否
background_image_colorstring礼包的背景颜色否
image_url_featuredstring礼包作为推荐商品展示时的图片 URL。 仅在商品被推荐时适用。否
category_slugsstring[]用于确定该礼包在商店中分类和展示位置的标识符数组。否
start_at数字商品对玩家可见并可购买的起始时间（Unix 时间戳）。否
end_atnumber商品对玩家不再可见或可购买的结束时间（Unix 时间戳）。否
max_purchases数字限制玩家能够购买该商品的最大次数。 达到限制后，该商品将从商店中消失否
price_template_idstring将用于不同国家定价的价格模板的 ID。否
custom_badgestring礼包的自定义徽章文字否
bonus_items`WebhookItemBonus[]\Item[] `礼包内包含的所有赠品构成的数组。
bonus_badgestring关于奖励商品的徽章文本否
bonus_percentnumber应用于 nested_items 中第一个可叠加商品的奖励百分比否
bonus_fixed数字应用于 nested_items 中第一个可叠加商品的固定奖励值。 如果设置，将忽略 bonus_percent。否
metadataobject自定义的键值对数据对象，用于存储与商品相关的额外信息。否
view_optionItemViewOption控制商品在商店中的显示方式. 允许的值：default、in_title

否
card_typeStoreCardType用于在商店中显示的商品卡片类型：default、featured
否
free_claimsFreeClaims将商品设置为可免费领取而不是购买的配置。
否
show_disabled_by_max_purchasesboolean当达到最大购买限制时，是否将商品显示为不可用
否

NestedItem Schema

键名类型描述是否必需
skustring商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。是
quantitynumber礼包中该商品的数量，主要用于可堆叠类型的商品（如游戏币、能量点等）。否
is_featuredboolean定义商品是否在礼包列表中突出显示。否
metadataobject自定义的键值对数据对象，用于存储与商品相关的额外信息。否

WebhookItemBonus 架构

键名Type描述是否必需
skustring商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。是
quantity数字礼包中该商品的数量，主要用于可堆叠类型的商品（如游戏币、能量点等）。否

The FreeClaims schema

键名Type描述是否必需
已启用boolean指示物品是否可以免费领取而不是购买。
是
max_claims数字指定期间内商品可被认领的最大次数。
是
周期周期用于重置max_claims的周期窗口。 如果省略，当达到最大认领次数后，限制不会重置。
否
exceeded_claims_behaviorExceededClaimsBehavior定义达到最大认领次数后的行为。 允许的值：hide - 从商店中移除物品；disable_with_timer - 保持可见但禁用，并带有倒计时直至下次重置。 如果省略了 period，则不会显示倒计时，并且该项目将保持禁用。
否

期限数据 Schema

键名Type描述是否必需
unitPeriodType用于索赔限额的期限类型。 可选值：month、week、day、hour。
是
duration数字期间的持续时间，以unit指定的单位测量（例如，duration：2 和 unit：day 表示一个两天的期间）。
是

动态优惠架构

键名Type描述是否必需
键名string用于确定物品是否已被购买或认领的唯一优惠键。是
placement_keystring滚动优惠将在Game Hub显示的模块键。是
namestring滚动优惠的标题。是
描述string滚动优惠的描述。是
rolling_itemsRollingItem[]滚动优惠中包含的物品列表。是
background_image_urlstring背景图片的URL。否
background_sizestring背景图片的大小。 可选值：contain、repeat、cover。否
expire_at数字优惠有效期的 Unix 时间戳。 优惠区块的计时器倒计时到此刻，优惠将在达到该时刻后隐藏。否

动态商品架构

键名Type描述是否必需
skustring礼包的唯一 SKU 标识符，用于动态生成的组合商品。是
quantity数字礼包中该商品的数量，主要用于可堆叠类型的商品（如游戏币、能量点等）。否
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",
      "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]

On this page