美团游戏开放平台

# 开放平台直发礼包配置说明

更新时间：2026年6月13日

# 功能介绍

直发礼包是美团游戏中心提供的道具直发能力。用户在游戏中心点击领取后，平台通过 HTTPS POST 回调游戏厂商（CP）服务端，CP 将道具直接发至用户游戏内邮箱，无需用户手动输入兑换码。

相比礼包码方案，直发礼包消除了用户手动兑换步骤，提升领取转化率和用户体验。

接入直发礼包，CP 需完成两项工作：

  1. 服务端开发：实现接收道具发放通知的回调接口（开发侧）
  2. 后台配置：在开放平台创建道具和礼包并完成提审（运营/PM 侧）

两项工作可并行推进，均完成后方可进行测试验收。

# 接入前置条件

开始接入前，请确认以下条件已满足：

  1. 已在美团游戏开放平台完成游戏注册，可在「开发管理 → 开发设置」查看 appId 和 appSecret
  2. CP 服务端具备接收 HTTPS POST 回调的能力，回调端口必须为 80 或 443
  3. 已阅读服务端对接文档：游戏道具发放通知

# 整体接入流程

giftBundleFlowDiagram.png

后台配置线（运营/PM 操作）：

配置回调地址 → 创建道具 → 创建礼包 → 提交审核 → 审核通过上线

技术开发线（开发操作）：

实现服务端回调接口 → 本地自测 → 与平台联调

两条线可并行推进，但须在礼包测试前均完成。

# 后台配置

# 第一步：配置回调地址

礼包直发需要厂商提前配置礼包回调地址，用于接收平台下发的道具发放通知。

配置路径： 开发管理 → 开发设置 → 消息通用接口配置

配置时需完成手机号验证码验证。请确保在礼包上线前完成配置，否则将影响用户领取后的道具发放。

giftBundleNotifyUrl.png

回调接口的开发规范、加密/签名算法及多语言示例代码，请参阅：游戏道具发放通知。请确保服务端接口在礼包上线前联调通过，否则用户领取后无法收到道具。

# 第二步：道具管理

支持厂商在平台上自主配置道具和礼包。用户在美团游戏内点击领取后，礼包道具将直接发送至用户游戏内邮箱，无需用户手动兑换礼包码。

操作入口： 登录开放平台，在左侧菜单选择对应游戏，进入 活动管理 → 礼包管理。

礼包管理包含两个子 Tab：道具管理 和 礼包管理。

giftBundleList.png

# 新增道具

道具是礼包的组成单元。厂商需先在「道具管理」中上传道具，再将道具配置进礼包使用。

进入「道具管理」Tab，点击列表右上角「新建道具」按钮，弹出创建表单，填写以下内容：

道具名称（必填）：20 字符以内。

道具图标（必填）：点击上传区域选择图片，要求尺寸 200×200px，格式为 JPEG 或 PNG。上传成功后图片显示在下方。

道具单价（必填）：单位为"分"，填写该道具的价值供礼包价值自动计算使用。

道具 ID 由系统自动生成，无需手动填写。

填写完成后有两个提交选项：

  • 点击「保存」：仅保存内容，道具不提交上线，可后续继续编辑
  • 点击「提交」：保存并直接上线，道具状态变为"已上线"

giftBundleItemManage.png

# 编辑道具

道具上线后，点击列表操作列中的「编辑」可修改道具名称、单价、图标。

注意：

  • 若道具已被上线礼包使用，则无法直接修改，需先将相关礼包下线，再进行道具编辑
  • 若道具已被未上线礼包引用，系统弹窗提示后确认，修改内容将自动同步至关联礼包

# 道具下线

点击操作列「申请下线」，二次确认后道具下线，状态变为"已下线"，无法恢复。

注意 道具下线后状态不可恢复。若该道具被上线礼包使用，须先将相关礼包下线后才能操作。

# 第三步：创建礼包

点击列表右上角「新建礼包」，弹出创建表单。表单分为三个区块：道具配置、基础信息、图片素材。

# 道具配置

在「道具名称」下拉框中搜索并选择本游戏已上线的道具，填写「数量」（每种道具发放数量），点击「+ 添加道具」可添加多条道具。

giftBundleEdit.png

# 基础信息

字段 是否必填 说明
礼包名称 必填 透传至 C 端展示
礼包类型 必填 下拉选择，控制领取频次，见下方说明
礼包使用说明 选填 透传至 C 端部分场景展示
礼包内容 选填 默认根据道具配置自动生成，也可手动修改，透传至 C 端展示
礼包数量 必填 该礼包可发放的最大总次数
礼包有效期 必填 选择开始日期和截止日期（精确到天）

礼包类型说明：

礼包类型 领取限制
每日礼包 有效期内，每自然日限领取一次
单次礼包 有效期内，每个账号终身限领取一次
更多类型 后续陆续新增…

# 图片素材

素材类型 是否必填 规格 备注
礼包 Icon 必填 200×200px，JPEG 或 PNG 部分C端场景展示
礼包 Banner 选填 335×236px，JPEG 或 GIF 部分C端场景展示

填写完成后点击「提交」创建礼包，点击「取消」放弃创建。

注意：提交前系统会自动校验所有已添加道具是否均为"已上线"状态。若存在已下线道具，将拦截提交。

# 第四步：礼包提审与上线

礼包创建后默认处于「待提交审核」状态，需手动提交审核。在列表操作列点击「提交审核」后，礼包进入平台审核流程，状态变为"审核中"，期间不可编辑。

审核结果：

  • 审核通过：礼包自动上线，状态变为"已上线"，可在 C 端对用户展示
  • 审核驳回：列表显示驳回原因，修改后可重新提交审核

# 编辑礼包

礼包上线前（未上线状态）可自由编辑全部字段。

礼包上线后，仅支持修改以下两项：

  • 礼包数量：可追加库存
  • 礼包有效期：可延长截止日期

上线后的礼包不允许修改道具内容和道具数量。修改完成后需重新提交审核，审核通过后修改自动生效。

# 礼包下线

点击操作列「下线」提交下线申请，经平台审核通过后礼包自动下线。

重要 礼包下线后无法重新上线。如需继续发放，请重新创建新礼包。礼包下线不影响其所含道具的状态。

# 服务端开发

服务端需实现一个 HTTPS POST 回调接口，用于接收平台的道具发放通知。

完整接口协议、加密/验签算法、多语言示例代码，请参阅：

游戏道具发放通知（完整技术文档）

开发时的关键要点：

  1. 幂等处理：以 orderId 为唯一键去重。同一 orderId 发放成功后，无论后续调用多少次均返回 code=0，不得重复发货
  2. 验签优先：收到回调后先验证 sign，签名不符的请求直接拒绝
  3. 区分测试请求：testFlag=true 为测试请求，不消耗礼包库存
  4. resultCode 规范：用户未注册返回 USER_UNREGISTERED、其他已知业务错误返回对应枚举值，减少不必要的平台重试，避免触发熔断策略

# 测试与验收

礼包审核通过上线后，可在正式发放前进行链路测试，验证发放流程是否接通。测试不消耗礼包库存，不影响礼包线上状态。

点击操作列「测试」，弹出测试框，输入游戏内已有角色的账号手机号（多个账号用英文逗号","分隔），点击「立即测试」，系统触发发放流程并实时展示日志和测试结果（成功 / 失败）。

giftBundleSendTest.png

# 验收标准

上线前须通过以下 3 个场景的测试：

验收场景 说明 预期响应
正常发放成功 使用已创建游戏角色的手机号测试 code=0，角色收到道具
未注册用户 使用未创建游戏角色的手机号测试 code≠0，resultCode=USER_UNREGISTERED
幂等验证 对同一账号触发两次发放（相同 orderId） 两次均返回 code=0，道具不重复发放

测试功能须在礼包**审核通过（状态为"已上线"）**后方可操作。

# 平台策略

# 重试策略

仅当回调接口**无响应（超时）**时，平台采用递增间隔进行重试。CP 服务端只要返回了响应（无论成功或失败），平台均不重试。

# 熔断策略

若 CP 发货接口持续失败——具体表现为大量返回 resultCode=OTHER（非 USER_UNREGISTERED / SEND_CONDITION_NOT_SATISFIED 的错误）——平台可能触发熔断策略，对相关礼包执行停用处理。停用后需重新完成测试验收方可上线。

建议：服务端对系统异常做好监控告警，确保非业务类错误能被及时发现和修复，避免触发熔断。

# 注意事项汇总

  1. 道具下线不可恢复：道具下线后状态无法重置；被上线礼包引用的道具须先将礼包下线
  2. 礼包下线不可重新上线：礼包下线后无法恢复，如需继续发放请重新创建
  3. 上线礼包不可修改道具：礼包上线后不允许修改道具内容和数量；仅支持追加库存和延长有效期
  4. 修改需重新提审：修改已上线礼包的库存或有效期后，须重新提交审核方可生效
  5. 回调端口限制：服务端回调接口端口必须为 80 或 443
  6. 持续失败触发停用：发货失败率持续偏高（大量 OTHER 结果码）可能触发平台熔断策略，导致礼包被停用
  7. 测试须在上线后操作：礼包须审核通过后才能使用测试功能；测试不消耗库存，但测试失败次数过多可能导致礼包被停用
上次更新: 8/10/2026, 5:36:37 PM