抖音开放平台Logo
开发者文档
直播小玩法
控制台
  • 小摇杆能力接入

    • 小摇杆能力接入

    收藏
    我的收藏

    小摇杆介绍

    ​
    【小摇杆】功能介绍
      •2024年8月6日起，直播小玩法的【小魔盒】将会升级为【小摇杆】
      •【小摇杆】将承载多种互动组件，对于观众可降低玩法参与门槛和理解成本，对于开发者可提升直播间与玩法的结合度，并增加玩法的设计空间
    ​

    小摇杆能力简介

    小摇杆目前支持以下三种能力
    能力
    说明
    接入效果
    用户快捷选队
      1.接入效果：开发者在小玩法后台配置用户快捷选队能力并接入openAPI后，观众可在小摇杆内通过点选按钮快捷加入玩法。
      2.适合玩法：存在2-4个阵营设计的玩法可接入，阵营数量 > 4或无阵营设计的玩法无需接入。
    ​
    ​
    礼物进阶互动效果
      1.接入效果：开发者在小玩法后台配置【礼物进阶互动效果】能力并接入openAPI后，观众可在小摇杆内查看礼物效果、组刷礼物。
      2.适合玩法：礼物及效果描述为必接能力，组刷可根据玩法设计选接。
    ​
    ​
    用户战绩与排行榜
      1.接入效果：开发者在小玩法后台配置【用户战绩与排行榜】能力并接入openAPI后，观众可在小摇杆内查看单局榜、总榜及历史战绩。
      2.适合玩法：存在榜单设计的玩法可接入。
    ​
    ​
    ​

    接入流程

    ​
    ​

    用户快捷选队

    更新记录

    时间
    更新内容
    2024.8.20
    创建文档

    一、能力说明

      1.接入效果：开发者在小玩法后台配置用户快捷选队能力并接入openAPI后，观众可在小摇杆内通过点选按钮快捷加入玩法。
      2.适合玩法：存在2-4个阵营设计的玩法可接入，阵营数量 > 4或无阵营设计的玩法无需接入。
    ​

    二、接入引导

    接入流程
    ​
    ​

    2.1 能力配置

    配置项
    配置说明
    示意图
    能力申请
      1.开发者可在小玩法后台【能力】-【能力配置】中找到【用户快捷选队】，点击【申请开通】后即可开通能力
      2.开通后请点击【配置信息】按钮跳转配置页
    ​
    快捷选队配置
    【必配】选择阵营数量
      •开发者可根据玩法内设计，选择：2阵营、3阵营、4阵营，小摇杆将根据该数量展示对应数量的按钮。
      •阵营数量需要与玩法设计一致
    【必配】添加Group_ID
      •每个阵营都需要配置唯一的Group_ID，用户加入玩法后平台将返回该字段，作为用户的加入结果通知开发者。
      •如果在【礼物进阶互动效果】中也配置了Group_ID，则不同能力间Group_ID需保持一致，否则将影响包体提审。
    ​
    【必配】添加阵营名称
      •每个阵营需要配置唯一的阵营名称，最多5个字。
      •阵营名称需要与玩法设计一致
    ​
    【选配】阵营按钮背景图
      •开发者可为小摇杆的选阵营按钮添加一张按钮底图。
      •底图设计时，需严格遵循设计规范，否则包体会被拒审：
      ◦两个按钮底图尺寸、比例、圆角等设计要素需完全一致
      ◦按钮底图不可以撰写文字
      ◦按钮需要很好的与白色文字、深色背景板有良好的对比度
      •正确示范
      •错误示范
    ​
      •设计规范
    ​
    开发配置
    ​
      •观众阵营选择数据推送配置
      ◦平台将在用户点选阵营按钮后，将选择结果（Group_ID）推送到此处配置的域名
    ​
      •平台查询观众阵营数据配置
      ◦平台需查询观众阵营数据，开发者可在【开发】-【开发配置】-【观众阵营数据配置】中录入查询地址

    2.2 API接入

    能力名称
    接入指引
    能力作用
    【必选】同步对局状态
    API接口调用顺序、API接口明细请参考：
    【技术接入指南】用户快捷选队
    开发者在对局开始时调用，同步对局开始事件；
    在对局结束时再次调用，同步对局结束事件。
    【必选】上报阵营数据
    观众通过评论、送礼等方式加入玩法时，调用该接口上报当前观众的阵营数据。
    【必选】查询观众阵营数据
    查询观众当前阵营数据，在观众进入直播间打开小摇杆互动面板时，平台服务器请求该接口获取用户在指定直播间最新的阵营数据。
    【必选】观众选择阵营
    观众在互动面板可以选择加入开发者在「用户快捷选队」中配置的阵营，平台服务器将用户的请求推送给开发者，开发者返回用户最终实际加入的阵营。

    2.3 能力测试

    测试项
    配置说明
    示意图
    openAPI自测
      •观众阵营选择数据推送配置
      a.配置协议类型及测试数据推送地址
      a.选择角色并添加Group_ID后推送
      a.开发者可根据返回的推送结果，确定接口调用的状态
    ​
      •平台查询观众阵营数据配置
      a.配置协议类型及测试数据查询地址
      a.选择角色并点击【查询】，平台将向测试地址查询观众阵营数据
      a.开发者返回的阵营标识将在查询结果中展示
    ​
    直播间测试
      1.使用真实的抖音账号添加调试成员
      2.通过伴侣挂载本地包体，调试成员可在直播间查看小摇杆内的快捷选队按钮
      3.玩法上线后，请删除测试账号的调试成员配置
    注：每个抖音账号仅能添加1个玩法的调试成员，有多个玩法需要调试时，请使用其他抖音号或重新添加调试成员
    /
    ​

    FAQ

    Q：开发者服务器收到【观众阵营选择数据】后，是否需要控制用户加入阵营？是否会推送入队的评论指令？
      1.收到【观众阵营选择数据】后，需要控制用户加入阵营。
      2.点击选阵营按钮是一种额外的加入方式，点击后平台不会再次推送评论指令。
    ​
    Q：没有配置【用户快捷选队】能力时，小摇杆内会怎么展示？
    未配置时，小摇杆内仅展示礼物信息。
    ​
    Q：不同版本的【用户快捷选队】配置会冲突吗？
    不会，不同包体版本的【用户快捷选队】配置会对应版本号生效。
    ​

    礼物进阶互动效果

    更新记录

    时间
    更新内容
    2024.7.16
    创建文档

    一、能力说明

      1.接入效果：开发者在小玩法后台配置【礼物进阶互动效果】能力并接入openAPI后，观众可在小摇杆内查看礼物效果、组刷礼物。
      2.适合玩法：礼物及效果描述为必接能力，组刷可根据玩法设计选接。
    展示礼物效果
    一键批量送礼
    ​

    二、接入引导

    接入流程
    ​

    2.1 能力配置

    配置项
    配置说明
    示意图
    能力申请
    ​
      1.开发者可在小玩法后台【能力】-【能力配置】中找到【礼物进阶互动效果】，点击【申请开通】后即可开通能力
      2.开通后请点击【配置信息】按钮跳转配置页
    能力配置
    ​
    添加礼物
      •开发者可在礼物菜单中选择要使用的礼物，最多支持添加8种不同的礼物
      •添加的礼物将展示在小摇杆互动区域内
    添加礼物描述
      •开发者可配置送出礼物后对应的效果描述，最多允许输入 5 个字
      •如：送出甜甜圈召唤小兵，可配置为：召唤小兵
    ​
    添加礼物数量
      •每种礼物的保底数量 = 1
      •开发者可根据玩法设计，配置多种礼物数量及对应的效果，当礼物数量 > 1时，小摇杆内将展示组刷区域以支持用户一键批量送礼
      •如：送出66个甜甜圈召唤超级小兵，可配置为：礼物数量 = 66，礼物效果为“超级小兵”
    礼物效果区分阵营
      •礼物效果支持区分阵营配置，最多支持区分4个阵营
      •如果玩法内不同阵营具有不同的礼物效果，开发者可在【礼物效果是否区分阵营】中选择【是】，并对应阵营来配置礼物信息
      •区分阵营时，开发者必须添加group_id的参数名，并在用户加入玩法时上报到平台，平台将根据该字段向用户展示对应礼物效果
      •如果在其他能力中也配置了Group_ID，则不同能力间Group_ID需保持一致，否则将影响包体提审。
    配置审核
    ​
      •礼物进阶互动配置必须与包体内容一致。开发者完成上述配置并接入能力后，需上传新的包体
      •在包体上传流程中，礼物进阶互动配置将替换原礼物配置，并与包体内容同步审核
      •新包体上线后，配置信息将对应包体版本同步生效
    ​
    观众阵营数据配置
      •平台需查询观众阵营数据，开发者可在【开发】-【开发配置】-【观众阵营数据配置】中录入查询地址
    ​

    2.2 API接入

    能力名称
    接入指引
    能力作用
    【必选】同步对局状态
    ​
    API接口调用顺序、API接口明细请参考：
    【技术接入指南】礼物进阶互动效果
    ​
    开发者在对局开始时调用，同步对局开始事件；
    在对局结束时再次调用，同步对局结束事件。
    【必选】上报阵营数据
    观众通过评论、点赞、送礼等方式加入玩法时，调用该接口上报当前观众的阵营数据。
    【必选】查询观众阵营数据
    查询观众当前阵营数据，在观众进入直播间打开小摇杆互动面板时，平台服务器请求该接口获取用户在指定直播间最新的阵营数据。

    2.3 能力测试

    测试项
    配置说明
    示意图
    openAPI自测
      •开发者可在【开发】-【自查工具】-【openAPI自测工具】-【查询观众阵营数据】中录入测试地址
      •点击【查询】后，平台将向测试地址查询观众阵营数据，开发者返回的阵营标识将在查询结果中展示
    直播间测试
      •礼物进阶效果配置通过审核后将在小摇杆内展示，可在线上环境确认表现
      •通过直播伴侣挂载本地包体时，小摇杆内将展示最近一次通过审核的礼物配置
    /
    ​

    FAQ

    Q：配置【礼物进阶互动效果】后，还需要保留玩法内的规则贴纸吗？
    需要，玩法内依然需要设置贴纸向观众展示规则。
    ​
    Q：没有配置【礼物进阶互动效果】时，小摇杆内会什么都不展示吗？
    不会，开发者未配置【礼物进阶互动效果】时，小摇杆会兜底展示包体上传时的礼物配置信息。
    由于字数限制，兜底效果可能不佳，请开发者尽快完成【礼物进阶互动效果】配置。
    ​
    Q：上传新包体后，旧版本的礼物配置后受影响吗？
    不会，礼物配置会和包体版本对应生效。
    ​
    Q：【礼物进阶互动效果】会和原本的礼物配置冲突吗？
    不会，配置【礼物进阶互动效果】后将替换原本的礼物配置，包体上线后将展示最新的【礼物进阶互动效果】。
    ​

    用户战绩与排行榜

    更新记录

    时间
    更新内容
    2024.7.16
    创建文档
    2024.8.7
    添加榜单与用户数据的FAQ介绍。

    一、能力说明

      1.接入效果：开发者在小玩法后台配置【用户战绩与排行榜】能力并接入openAPI后，观众可在小摇杆内查看单局榜、总榜及历史战绩。
      2.适合玩法：存在榜单设计的玩法可接入。
    小摇杆内展示总榜排名
    用户单局榜
    用户总榜
    用户历史对局
    ​

    二、接入引导

    2.1 能力配置

    配置项
    配置说明
    示意图
    能力申请
      1.开发者可在小玩法后台【能力】-【能力配置】中找到【用户战绩与排行榜】，点击【申请开通】后即可开通能力
      2.开通后请点击【配置信息】按钮跳转配置页
    ​
    排行榜配置
    添加排行榜
      •开发者最多可配置2个榜单，每个榜单可选择单局榜、总榜其中一种
      •平台后续将开发更多榜单类型
    ​
    排行榜数据
      •小摇杆为排行榜提供了2个数值展示区域，分别为核心数值和次要数值
      •核心数值为榜单排名依赖的数值，当前提供了【个人积分】类型，开发者上报用户积分的数值即可
      •次要数值提供了【连胜】和【胜点】2类，排行榜将根据开发者选择的类型展示文案，开发者上报对应的数值即可。如：选择【连胜】，排行榜内将展示【连胜】，开发者上传连胜次数即可
      •平台后续将开放更多数值类型
    截榜时间
      •当开发者配置【总榜】时，须根据玩法设计配置截榜时间
      •截榜时间支持按【月】、【双周】、【周】的维度统计
    榜单奖励
      •当玩法设计了【总榜】奖励时，开发者需要在【榜单奖励】内选择【有】，并上传1张排名与奖励的映射说明图，图片将在小摇杆【说明】入口内向用户展示
      •开发者须严格按规则向获奖观众发放奖励
    排行榜配置审核
      •榜单配置须与包体内容一致
      •开发者完成上述配置并接入能力后，需上传新的包体，排行榜配置将与包体内容同步审核
      •新包体上线后，配置信息将对应包体版本同步生效
    /

    2.2 API接入

    能力名称
    接入指引
    能力作用
    【必选】设置当前生效的世界榜单版本
    API接口调用顺序、API接口明细请参考：
    【技术接入指南】用户战绩与排行榜
    设置线上环境/测试环境生效的世界榜单版本，设置后，小摇杆的「世界榜」将展示新世界榜单版本的数据。
    【必选】上传世界榜单列表
    设置正式环境/测试环境的世界榜单列表数据，榜单最多设置150个成员。
    【必选】上报用户世界榜单数据
    上报用户世界榜单的累计战绩，单次调用最多上报50名用户。
    【必选】完成用户世界榜单数据的上报
    当到达截榜时间且有线上生效的世界榜单版本时，在完成用户世界榜单的累计战绩上报后，调用本接口，标记本次截榜时间内的世界榜单累计战绩完成了上报。
    【必选】同步对局状态
    ​
    开发者在对局开始时调用，同步对局开始事件；
    在对局结束时再次调用，同步对局结束事件。
    【必选】上报对局榜单列表
    ​
    对局结束后，上报对局榜单列表，榜单最多设置150个成员。
    【必选】上报用户对局数据
    对局结束后，上报用户对局数据，需要分批次调用，单批次最多上报50个用户对局数据。
    【必选】完成用户对局数据上报
    当完成用户对局数据上报后，调用本接口，标记对局数据上报已完成，小摇杆的「本局榜」将展示本局榜单数据。

    2.3 能力测试

    测试项
    配置说明
    示意图
    单局榜测试
      1.使用真实的抖音账号添加调试成员
      2.通过伴侣挂载本地包体，调试成员参与玩法后可在单局榜内确认表现
    当前暂不支持在测试时展示连胜、胜点数值
    /
    总榜测试
      1.使用真实的抖音账号添加调试成员
      2.在openAPI中设置总榜的测试环境
      3.通过伴侣挂载本地包体，调试成员参与玩法后，将从总榜的测试环境中读取数据
      4.玩法上线后，请删除测试账号的调试成员配置
    注：每个抖音账号仅能添加1个玩法的调试成员，有多个玩法需要调试时，请使用其他抖音号或重新添加调试成员
    /
    ​

    FAQ

    Q：没有配置【用户战绩与排行榜】时，小摇杆内会怎么展示？
    开发者未配置【用户战绩与排行榜】时，小摇杆内不会展示战绩、排行榜信息。
    ​
    Q：不同版本的【用户战绩与排行榜】配置会冲突吗？
    不会，不同包体版本的【用户战绩与排行榜】配置会对应版本号生效。
    ​