跳至主要内容

商店数据获取 Webhook

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

此 Webhook 在以下情况下触发：

  • 玩家登录游戏枢纽时触发。
  • 玩家点击打开商店界面时触发。
  • 玩家完成商品购买后触发。
获取商店 Webhook
获取商店 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"
  },
  "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"
}

事件 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当前用户的操作是否匿名

Response Schema

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

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

Item Schema

键名类型描述是否必需
skustring商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。是
start_atnumber商品对玩家可见并可购买的起始时间（Unix 时间戳）。否
end_atnumber商品对玩家不再可见或可购买的结束时间（Unix 时间戳）。否
max_purchasesnumber限制玩家能够购买该商品的最大次数。否

BundleItem Schema

键名类型描述是否必需
skustring礼包的唯一 SKU 标识符，用于动态生成的组合商品。是
pricenumber价格（美分）。是
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在nested_items中首次可堆叠项应用的奖励百分比否
bonus_fixed数字应用于嵌套项目中第一个可堆叠项目的固定奖励值。 如果设置，bonus_percent 将被忽略。否
metadataobject自定义的键值对数据对象，用于存储与商品相关的额外信息。否
view_optionItemViewOption控制商品在商店中的显示方式。 允许的值：default, in_title

否
card_typeStoreCardType用于在商店中显示的商品卡片类型：default, featured
否
free_claimsFreeClaims将物品设置为可以免费领取而不是购买。
否

NestedItem Schema

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

WebhookItemBonus 架构

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

The FreeClaims schema

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

期限数据 Schema

键名Type描述是否必需
unitPeriodType用于索赔限额的期限类型。 可选值：month、week、day、hour。
是
durationnumber期间的持续时间，以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 标识符，用于动态生成的组合商品。是
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