抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 服务端 API 介绍
  • 接口调用凭证
  • 登录
  • 直播间能力
  • 用户战绩与排行榜接入说明

    收藏
    我的收藏

    更新记录

    时间
    更新内容
    2024.07.16
    创建文档
    2024.08.08
      补充「上传世界榜单列表数据」API、「上报用户世界榜单的累计战绩」API、「上报用户对局数据」API、「上报对局榜单列表」API的接口说明。
      新增第四章节「FAQ」板块。

    一、整体流程

    测试环境前置准备流程:
      在开发者平台添加调试成员。
      接口上传数据,需指定上传到测试环境,详情可以参考接口明细。

    二、接入时序

    三、接口明细

    四、FAQ

    Q:【上传世界榜单列表数据】world_rank/upload_rank_list 和 【上报用户世界榜单的累计战绩】world_rank/upload_user_result 接口区别是什么?为什么要上传两次?

    回答:
      1.第 1 部分 和 第 3 部分是榜单区域,目前限制榜单长度最多展示Top 150的用户数据,当然也可以低于 150,取决于上报的榜单列表长度。
      2.第 2 部分 和 第 4 部分是用户的个人数据区域;
    个人数据区域」 和 「榜单区域」 的数据取数逻辑是 不一样的。
      个人数据区域」
      第 2 部分:直接取自【上报用户对局数据】接口上报的用户数据。【上报用户对局数据】接口批量上报,底层是以用户id+room_id+round_id为维度存储,存储对应用户的对局数据用户id+room_id+round_id维度重复上报,是覆盖写的逻辑;
      第 4 部分:直接取自【上报用户世界榜单的累计战绩】接口上报的用户数据。【上报用户世界榜单的累计战绩】接口批量上报,底层是以用户id+榜单版本world_rank_version为维度存储,存储对应用户的世界战绩数据,用户id+榜单版本world_rank_version维度重复上报,是覆盖写的逻辑;
      「榜单区域」
      第 1 部分:直接取自【上报对局榜单列表】接口上报的榜单Top 150。【上报对局榜单列表】接口是一次性上传排好序的榜单Top 150的用户数据,数据直接展示在小摇杆的「对局榜」的榜单中,平台不做特殊处理,直接展示;底层是以room_id + round_id为维度存储,直接存储对局榜单列表room_id + round_id维度重复上报,是覆盖写的逻辑;
      第 3 部分:直接取自【上传世界榜单列表数据】接口上报的榜单Top 150。【上传世界榜单列表数据】接口是一次性上传排好序的榜单Top 150的用户数据,数据直接展示在小摇杆的「世界榜」中,平台不做处理直接展示;底层以榜单版本 world_rank_version 为维度存储完整榜单数据,榜单版本world_rank_version维度重复上报,是覆盖写的逻辑;
      比如:世界榜单更新逻辑是,每1分钟更新一次
      8:00:调用【上传世界榜单列表数据】接口一次,一次性上报当前时刻的世界榜单Top 150;
      8:01 调用【上传世界榜单列表数据】接口上报最新 Top 150 数据,该次调用会覆盖 8:00 上报的数据;

    Q:【设置当前生效的世界榜单版本】接口、【上传世界榜单列表数据】接口、【上报用户世界榜单的累计战绩】接口和【完成用户世界榜单的累计战绩上报】接口,调用时机是什么,world_rank_version该怎么传递 ?

    回答:
    比如:世界榜是月榜,每月1号0点更新
      1.2025.8.1 0 点
      a.调用 【设置当前生效的世界榜单版本】接口,设置生效的版本是 world_rank_version=month_8
      b.小摇杆的「世界榜」的榜单数据将展示world_rank_version=month_8的数据
      2.2025.8.1 0 点- 8.31 23点期间
      a.定时调用【上传世界榜单列表数据】更新榜单Top 150每次调用 world_rank_version都是month_8
      b.定时调用【上报用户世界榜单的累计战绩】接口,定时更新用户战绩数据。每次调用 world_rank_version都是month_8
      c.小摇杆的「世界榜」的榜单数据展示world_rank_version=month_8的数据
      3.9.1 0点
      a.调用【完成用户世界榜单的累计战绩上报】,传递world_rank_version=month_8,标记这个版本的数据已经上传完成。
      b.调用 【设置当前生效的世界榜单版本】接口,设置新的生效的版本是world_rank_version=month_9,小摇杆的「世界榜」的榜单数据将展示world_rank_version=month_9的数据

    Q:【上传世界榜单列表数据】接口已经上传了Top 150的用户数据,【上报用户世界榜单的累计战绩】接口是否需要再重复上传Top 150的用户数据

    回答:需要的。

    Q:【上报对局榜单列表】接口已经上传了Top 150的用户数据,【上报用户对局数据】接口是否需要再重复上传Top 150的用户数据

    回答:需要的。

    Q:【上报用户世界榜单的累计战绩】接口需要上传小玩法的所有玩家战绩数据,存在较大的系统瓶颈问题,如何处理?

    回答:如果小玩法的玩家数量非常大,所有玩家的战绩都上报,存在较大的系统瓶颈问题,可以只上报大于 x 积分的用户数据,低于 x 积分的用户数据不上报。x 积分由开发者自定义。

    Q:【上报用户世界榜单的累计战绩】接口,请求时机是什么时候?有什么官方建议?

    回答:【上报用户世界榜单的累计战绩】接口,可以在用户的战绩数据发生变化时触发上报。建议在用户参与的对局结束后,累计用户在当前世界榜单统计周期内的所有战绩数据,进行上报;
    另外为了保证前1000 名用户数据是准实时的,可以定时上报前 1000 名的用户数据,比如:可以每 1 分钟固定上报前 1000 名的用户数据。

    Q:【上报用户世界榜单的累计战绩】接口的rank排名字段是否需要传递,如何传递,如果有100万的玩家,也需要准确的实时排名吗?

    回答:需要传递,rank排名超过1000的用户,可以固定传递1000,抖音端会展示为 "999+";另外为了保证前1000 名用户数据是准实时的,可以定时上报前 1000 名的用户数据,比如:可以每 1 分钟固定上报前 1000 名的用户数据。

    Q:【同步对局状态】的round_id如何生成,有什么限制?

    回答:同一个直播间room_id下,round_id需要是递增的,建议使用开始对局时的时间戳。

    Q:【完成用户对局数据上报】有什么作用,不调用会产生什么影响?

    回答:该接口用于标记对局数据上报已完成,小摇杆的「本局榜」将展示本局榜单数据。如果未标记完成,本轮对局数据在小摇杆的「本局榜」中不展示。

    Q:【上报用户世界榜单的累计战绩】接口上报的用户数据,是否会影响【上传世界榜单列表数据】接口上报的Top 150 ?

    回答:不会。
    比如:
      【上传世界榜单列表数据】接口上报的Top 150,Top 1是用户A,score=10000,此时用户B不在Top 150中;
      用户 B 持续参与玩法,积分值大幅增长;
      【上报用户世界榜单的累计战绩】接口上报用户B(score=20000),用户B不会在榜单列表中展示,不会成为Top1;
      开发者需要重新调用【上传世界榜单列表数据】接口,上报最新的Top 150,包含用户B;此时用户B才会在榜单中展示;
    由于【上传世界榜单列表数据】接口的调用时机和【上报用户世界榜单的累计战绩】接口调用时机不同,用户个人战绩数据和世界榜单Top 150 的用户战绩数据存在短时间差异,即可能存在用户个人战绩数据比上榜的用户数据还大,但是未上榜的场景。但是榜单数据在统计周期内是动态变化的,统计周期结束,用户个人战绩数据和榜单列表数据会最终一致。

    Q:世界榜单接口全部调用完成,但是玩法直播间的小摇杆【我的面板】还是不可见榜单入口?

    回答:
      如果进入玩法直播间的观众是调试成员的话,需在接口参数中设置 is_online_version=false,且上报数据需包含调试成员信息,调试成员方可查询榜单数据
      如果进入玩法直播间的观众不是调试成员,是正式用户的话,将世界榜单接口的参数:is_online_version = true 传递,这样正式用户才能查询到自己的榜单数据,并且上报的世界榜单数据需要包括正式用户的数据才会可见