# 擂台赛组件-开发指南

# 功能说明

擂台赛组件是小游戏官方提供的赛事玩法互动组件。游戏内，擂主邀请好友参与擂台挑战，获胜方可领取擂台赛奖励；游戏外，以「服务通知」和「聊天工具」的社交形式增加回流触达。

# 玩法介绍

擂台赛玩法C端体验路径：跳一跳-单局超过200分发起「有奖擂台赛」

# 1. 发起擂台赛

● 用户在游戏内，完成游戏对局，产生结算分数，用户可向朋友发起擂台赛；

● 擂主发起后不可再次参与，分数不可更改。每个成功发起的擂台赛，有效时间 6 小时；

● 擂台赛发起入口、条件，由开发者自定义并控制。

# 2. 参与擂台赛

● 朋友可以通过分享链接，进入游戏，向擂主发起挑战；

● 参与玩家在赛事有效期内可多次尝试。

# 奖励规则

每个擂台赛配置4个礼包，守擂/挑战成功后，可领取对应奖励。

# 1. 擂主

● 守擂成功：任意用户参与擂台赛且在擂台赛举办期间未超过发起者的分数，视为发起者本次守擂成功；

● 奖励领取：每个擂台赛，擂主至少守擂成功一次，所有奖励领取时，可按10%概率抽取1次「擂主-稀有奖品」，并按成功次数获得「擂主-必中奖品」；

# 2. 参与者

● 挑战成功：参与擂台赛并超过擂主设定的目标分数后，视为本擂台赛挑战成功；

● 奖励领取：每个擂台赛挑战成功，挑战者将固定获得「挑战者-必中奖品」，并有10%的概率抽取「挑战者-稀有奖品」；

# 用户触达

组件支持以社交形式增加回流触达。群聊场景将以聊天工具卡片形式分享：聊天工具模式下，可在卡片实时展示挑战成功人数，并在用户参与/挑战成功/擂台赛结束时，通过群内消息形式下发全局通知。

# 如何接入擂台赛组件

开发者可参考以下方法，快捷完成接入。

# 1. 完成游戏玩法ID设置

● 用于上报用户当局游戏结果，结果支持数值、时间格式、枚举格式。

● 游戏玩法生效后，除枚举值新增/修改名称外，不支持更改。

# 2. 配置奖励礼包

● 礼包类型：擂台赛礼包礼包接入文档

● 建议每个礼包内只包含一个道具。多个道具情况下，采用首个道具icon与名称为c端展示。建议上传透明底的icon图。

● 需要提供 4 个礼包 id。建议擂主与挑战者在相同场景（保底、抽奖）奖励相同。

○ 礼包1：擂主守擂成功保底奖励（每日领取上限50次）

○ 礼包2：擂主守擂成功稀有奖励（每日领取上限5次）

○ 礼包3：参与者挑战成功保底奖励（每日领取上限50次）

○ 礼包4：参与者挑战成功稀有奖励（每日领取上限5次）

# 3. 开发接入实现

版本要求：从基础库 3.11.0 开始支持

支持平台：Android 微信 8.0.62 及以上版本、iOS 微信 8.0.62 及以上版本

# 3.1 接入前准备

擂台赛组件的分享和动态消息功能依赖于聊天工具模式。聊天工具

聊天工具的分享功能要求小游戏具备有效的登录态。为确保用户分享擂台赛时游戏已建立登录态，需要在擂台赛开始前调用 wx.login 接口完成登录流程。

# 3.2 发起擂台赛

擂台赛功能基于 wx.getRankManager() API 实现，通过该接口返回的类方法进行相关操作。

# 3.2.1 上报擂主分数

发起擂台赛前，需要先上报玩家发起擂台赛的基准分数。使用 update 方法进行分数上报。

// 获取排行榜管理器实例
const rankManager = wx.getRankManager();
// 上报用户分数
rankManager.update({
  scoreKey: 'score_key', // 在MP配置的scoreKey
  score: 100, // 具体分数值
  success: res => {
  console.log('分数上报成功', res);
  },
  fail: err => {
  console.error('分数上报失败', err);
  },
});

# 3.2.2 创建擂台赛

分数上报成功后，使用 createChallenge 方法发起擂台赛。

// 发起擂台赛
wx.getRankManager().createChallenge({
  scoreKey: 'score_key',
  success: res => {
  console.log('擂台赛创建成功', res);
  },
  fail: err => {
  console.error('擂台赛创建失败', err);
  },
});

注意事项：

一次 update 上报的分数只能创建一个擂台赛。
针对同一次上报多次调用 createChallenge 将返回已创建的擂台赛。

# 3.3 加入擂台赛

# 3.3.1 监听挑战开始事件

用户从他人分享的擂台赛卡片进入小游戏，小游戏会在 onShow 时弹起加入擂台赛半屏。用户点击半屏上的“立即挑战”按钮，擂台赛挑战开始。通过 rankManager.onChallengeStart(callback) 监听onChallengeStart事件，在onChallengeStart事件的回调中处理挑战开始逻辑。

// 监听擂台赛开始事件
wx.getRankManager().onChallengeStart((challengeInfo) => {
  // 处理挑战开始逻辑
  console.log('擂台赛开始', challengeInfo.scoreKey);
});

# 3.3.2 中途操作

擂台赛进行过程中，支持以下操作：

● 中途上报分数。擂台赛的最终分数将取中途上报分数和最终上报分数中最高的一次。

// 游戏过程中上报中间分数
wx.getRankManager().middleUpdate({
  scoreKey: 'score_key',
  score: gameState.score, // 当前分数
  success: res => {
  console.log('中途分数上报成功', res);
  },
  fail: err => {
  console.error('中途分数上报失败', err);
  },
});

● 中途退出挑战。中途退出的擂台赛，本次挑战为0分。

// 中途退出擂台赛
wx.getRankManager().abort({
  success: (res) => {
  console.log('擂台赛退出成功', res);
  },
  fail: (err) => {
  console.error('擂台赛退出失败', err);
  },
});

# 3.4 结束擂台赛

在擂台赛进行过程中调用 update 方法上报最终分数，系统将自动结束擂台赛并拉起结束界面。

// 结束擂台赛并上报最终分数
wx.getRankManager().update({
  scoreKey: 'score_key',
  score: 150, // 最终分数
  success: res => {
  console.log('擂台赛结束', res);
  },
  fail: err => {
  console.error('擂台赛结束异常', err);
  },
});

# 3.5 奖励领取

挑战者战胜擂主，或者擂主守擂成功时，可以在擂台赛组件结果页领取道具奖励。