# 擂台赛组件-开发指南

# 功能说明

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

【平台限时激励包奖励】 2026年春节期间，可配置平台「擂台赛比拼玩法激励包」作为擂台赛奖励。查看详情

# 玩法介绍

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

# 1. 发起擂台赛

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

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

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

# 2. 参与擂台赛

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

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

# 奖励规则

每个擂台赛配置4个礼包，守擂/挑战成功后，可领取对应奖励。开发者可自行设置奖励限额、不同用户不同概率

# 1. 擂主

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

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

# 2. 参与者

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

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

# 用户触达

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

# 如何接入擂台赛组件

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

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

● 位置：MP-运营功能管理-基础配置-游戏玩法ID设置

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

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

# 2. 配置奖励礼包

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

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

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

○ 礼包1：擂主守擂成功保底奖励

○ 礼包2：擂主守擂成功稀有奖励

○ 礼包3：参与者挑战成功保底奖励

○ 礼包4：参与者挑战成功稀有奖励

# 3. 配置擂台赛

位置：MP-能力地图-擂台赛组件-关联擂台赛的奖励、ID

# 4. 开发接入实现

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

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

# 4.1 接入前准备

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

# 4.2 发起擂台赛

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

# 4.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);
  },
});

# 4.2.2 创建擂台赛

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

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

注意事项：

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

# 4.3 加入擂台赛

# 4.3.1 监听挑战开始事件

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

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

# 4.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);
  },
});

# 4.4 结束擂台赛

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

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

# 4.5 奖励领取

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

// 监听挑战赛福利组件信息变更
wx.onOfficialComponentsInfoChange(componentInfo => {
    let receiveDetail = componentInfo.challengeRewardsComponentInfo?.receiveDetail;
    if (receiveDetail) { // 挑战赛礼包领取事件
        // 处理奖励领取结果
        switch (receiveDetail.awardResult) {
            case 1:
                console.log('奖励全部领取成功！');
                break;
            case 2:
                console.log('奖励部分领取成功');
                break;
            case 3:
                console.log('奖励领取失败');
                break;
        }
        // 检查是否领取了稀有奖励
        if (receiveDetail.receivedRareReward === true) {
            console.log('恭喜！领取了稀有奖励！');
        }
        // 遍历用户领取的奖励列表
        receiveDetail.userSourceList.forEach((userSource, index) => {
            if (userSource.source) {
                console.log(`第${index + 1}个奖励:`);
                console.log('  礼包名称:', userSource.source.sourceName);                
                // 遍历道具列表
                userSource.source.propList?.forEach(prop => {
                    console.log(`${prop.propName} x${prop.propNum}`);
                });
            }
        });
    }
});

# 4.6 查询擂台赛的成功邀请次数（灰度测试）

开发者可以通过该接口，查询擂主或参与者，当天成功发起擂台赛邀请的次数。仅包括通过小程序卡片发起的邀请。

接口需要通过小游戏官方插件进行调用，小游戏官方插件的使用指南请参考：小游戏官方插件

接口定义：

getGamePkShareData(pkRole: number):  Promise<GamePkShareDataResponse>

参数:

属性	类型	说明
pkRole	number	邀请发起人身份, 1表示擂主，2表示参与者

返回值 GamePkShareDataResponse：

属性	类型	说明
shareCount	number	今天成功发起擂台赛邀请次数

error对象结构：

属性	类型	说明
errMsg	string	错误原因

使用示例：

const pkRole = 1;
GameGlobal.miniGameCommon.getGamePkShareData(pkRole)
  .then((res) => {
    console.log('邀请次数为：', res.shareCount);
  }).catch((err)=>{
    console.error('error', err.errMsg);
  });