# 直播场景扫码换号能力（选接）
直播场景扫码换号能力，是抖音为小游戏开发者提供的直播场景下观众扫码、主播切换账号的解决方案，可实现看号、调号、起号、合宠、抽卡等内容互动模式，提升用户体验与留存、助力主播内容经营。了解更多内容请阅读抖音小游戏官方文档《实现直播场景扫码切换账号能力接入指南》 (opens new window)。
注意，生成二维码、扫一扫、确认授权与授权登录等服务流程均已由 SDK 侧完成，游戏侧只需按本文档接入相关 API，并自行实现二维码弹窗、确认授权弹窗等界面。
# 核心优势
- 主粉互动乐趣多：主播可在使用自身抖音账号直播的情况下，登录粉丝的小游戏账号，实现看号调号。
- 玩家游戏体验好：粉丝可在确保抖音账号安全的情况下，授权单个小游戏、单次的登录让主播看号调号，提升账号价值、优化玩游戏的成本。
# 示例介绍
小游戏内可在一个抖音账号生成二维码后，结合平台提供的扫码API能力，支持用户扫码授权登录，实现多个小游戏账号的切换。
| 首页扫码换号入口 | 主播点击扫码换号生成二维码 | 粉丝截图保存后在游戏内扫一扫 |
|---|---|---|
 |  |  |
| 主播显示切换账号成功 | 粉丝显示扫码成功并退出游戏 | 粉丝重新登录时主播被“顶号” |
 |  |  |
# 体验流程示意
主播端&用户端的整体体验流程如下图所示：
# 接入流程介绍
# 名词说明
- 主播端：直播中主播所使用的设备，负责申请并展示换号二维码，粉丝授权后以粉丝的账号登录游戏；
- 粉丝端：观看直播的粉丝所使用的设备，负责扫描换号二维码并确认授权；
- 授权登录状态：主播端以粉丝授权的账号登录游戏后所处的状态，可通过「获取是否为授权登录状态」接口判断。
# 主播端接入流程
- Step 1：游戏启动后，接入「监听换号二维码状态变化事件」与「监听登录过期事件」API 能力，须在申请二维码之前完成注册；
- Step 2：主播已登录后，在游戏内展示「扫码换号」按钮，点击时接入「申请换号二维码」API 能力，并在游戏内弹窗展示返回的二维码图片；
- Step 3：二维码状态变为已授权（
CONFIRMED）时，关闭二维码弹窗，接入「授权登录」API 能力，以粉丝的账号重新登录并进入游戏； - Step 4：二维码状态变为已过期（
EXPIRED）、已失效（INVALID）或检测异常终止时，提示主播重新申请二维码； - Step 5：授权登录状态下，粉丝重新登录游戏时会触发登录过期事件，此时提示主播登录凭证已过期并退出游戏服，回到游戏登录界面。
# 粉丝端接入流程
- Step 1：在游戏内展示「扫一扫」按钮，点击时接入「扫一扫换号二维码」API 能力，获取二维码内容；
- Step 2：扫码成功后，由游戏自行展示授权确认弹窗，粉丝确认后接入「确认换号授权」API 能力；
- Step 3：确认授权成功后，提示粉丝授权成功并自动退出当前游戏登录状态。
# API说明
# 申请换号二维码
# 接口说明
用于主播端申请换号二维码（2.5.0 版本新增），申请成功后返回二维码图片，同时 SDK 自动开始检测二维码状态，状态变化时通过「监听换号二维码状态变化事件」接口注册的回调函数通知游戏。
注意，调用此接口前需先完成《登录》，未登录时调用将直接触发失败回调函数；授权登录状态下也可再次申请二维码，以便主播连续切换账号。
sdkInstance.createAccountSwitchQRCode(options);
二维码状态检测规则
- 同一时间只检测一张二维码，重新申请二维码后将停止检测上一张二维码，上一张二维码的状态变化不再通知游戏；
- 当前登录的账号发生变化（如授权登录成功）后，停止检测二维码状态；
- 游戏进入后台期间暂停检测，回到前台后自动恢复。
# 调用时机
在主播点击游戏内「扫码换号」按钮时调用。
# 参数说明
参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| success | function | 否 | -- | 接口调用成功的回调函数 |
| fail | function | 否 | -- | 接口调用失败的回调函数 |
| complete | function | 否 | -- | 接口调用完成的回调函数，成功或失败均会调用 |
# 返回值说明
注意
返回值格式：JSON 格式。
| 选项 | 类型 | 说明 |
|---|---|---|
| code | string / number | 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败 |
| data | object / null | 接口调用成功时返回二维码数据，失败时返回 null |
| data.qrUuid | string | 二维码ID |
| data.qrcode | string | 二维码图片，格式为 data:image/png;base64, 开头的 Base64 图片地址 |
| message | string | 接口调用成功或失败时的相应描述信息 |
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 主播点击“扫码换号”按钮时，申请换号二维码
sdkInstance.createAccountSwitchQRCode({
success: function(response) {
// 在游戏内弹窗展示二维码图片，注意：这是一段伪代码，具体由开发者自行实现
showQRCodeModal(response.data.qrcode);
},
fail: function(error) {
sdkInstance.modal.message(error.message);
},
complete: function(result) {
// do something here...
}
});
# 监听换号二维码状态变化事件
# 接口说明
用于主播端监听换号二维码状态变化事件（2.5.0 版本新增），二维码已授权、已过期、已失效，或因异常而终止检测时触发回调函数。
注意，请在调用「申请换号二维码」接口之前注册监听；多次注册时以最后一次注册的回调函数为准。
sdkInstance.onAccountSwitchQRCodeStatusChange(callback);
# 参数说明
参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| callback | function | 是 | -- | 事件回调函数 |
# 返回值说明
注意
返回值格式：JSON 格式。
| 选项 | 类型 | 说明 |
|---|---|---|
| code | number | 响应状态码，为 0 时表示获取到二维码状态，其他非 0 状态码均表示检测异常终止 |
| data | object / null | 获取到二维码状态时返回状态数据，检测异常终止时返回 null |
| data.status | string | 二维码状态：
|
| data.qrUuid | string | 二维码ID，用于「授权登录」接口的 qrUuid 参数 |
| data.authorizationId | number | 授权ID，二维码已授权时返回，用于「授权登录」接口的 authorizationId 参数 |
| message | string | 相应描述信息 |
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 游戏启动后注册监听，须在申请二维码之前完成注册
sdkInstance.onAccountSwitchQRCodeStatusChange(function(result) {
// 检测异常终止，可在二维码弹窗上提示主播重新申请，或直接弹出提示信息
if (result.code !== 0) {
return sdkInstance.modal.message(result.message);
}
// 二维码已授权，关闭二维码弹窗，并以粉丝的账号执行授权登录
if (result.data.status === "CONFIRMED") {
// 提示粉丝授权成功，正在切换账号
sdkInstance.modal.message("二维码已授权，正在切换账号...");
// 关闭二维码弹窗，注意：这是一段伪代码，具体由开发者自行实现
closeQRCodeModal();
// 授权登录
sdkInstance.login({
qrUuid: result.data.qrUuid,
authorizationId: result.data.authorizationId,
success: function(response) {
// 退出当前游戏服，并以粉丝的账号重新登录游戏服，注意：这是一段伪代码，具体由开发者自行实现
reloginGameServer(response.data);
},
fail: function(error) {
sdkInstance.modal.message(error.message);
}
});
}
// 二维码已过期或已失效，可在二维码弹窗上提示主播重新申请，或直接弹出提示信息
else {
sdkInstance.modal.message("二维码已失效，请重新申请");
}
});
# 取消监听换号二维码状态变化事件
# 接口说明
用于主播端取消监听换号二维码状态变化事件（2.5.0 版本新增）。
sdkInstance.offAccountSwitchQRCodeStatusChange();
# 参数说明
无
# 返回值说明
无
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 取消监听换号二维码状态变化事件
sdkInstance.offAccountSwitchQRCodeStatusChange();
# 扫一扫换号二维码
# 接口说明
用于粉丝端调起抖音扫码界面扫描换号二维码（2.5.0 版本新增），扫码成功后返回二维码内容，用于「确认换号授权」接口。
注意，扫描的二维码不是当前游戏的换号二维码时，将直接触发失败回调函数，并返回「无效的换号二维码」；授权登录状态下不支持调用此接口，调用时将直接触发失败回调函数，返回值中的 code 为 delegated。
sdkInstance.scanAccountSwitchQRCode(options);
# 调用时机
在粉丝点击游戏内「扫一扫」按钮时调用。
# 参数说明
参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| success | function | 否 | -- | 接口调用成功的回调函数 |
| fail | function | 否 | -- | 接口调用失败的回调函数 |
| complete | function | 否 | -- | 接口调用完成的回调函数，成功或失败均会调用 |
# 返回值说明
注意
返回值格式：JSON 格式。
| 选项 | 类型 | 说明 |
|---|---|---|
| code | string / number | 响应状态码，为 0 时表示接口调用成功，为 cancel 时表示用户取消扫码，为 delegated 时表示当前为授权登录状态，其他非 0 状态码均表示接口调用失败 |
| data | object | 接口调用成功时返回扫码结果，失败时返回失败信息 |
| data.qrContent | string | 二维码内容，用于「确认换号授权」接口的 qrContent 参数 |
| message | string | 接口调用成功或失败时的相应描述信息 |
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 粉丝点击“扫一扫”按钮时，扫描换号二维码
sdkInstance.scanAccountSwitchQRCode({
success: function(response) {
// 弹出二次确认弹窗，粉丝确认后再确认换号授权，此处以SDK内置的确认弹窗为例，游戏也可自行实现符合游戏风格的二次确认弹窗
sdkInstance.modal.confirm({
title: "确认授权",
content: "确认将您的游戏账号授权给对方登录吗？",
success: function(result) {
// 粉丝点击了取消
if (!result.confirm) {
return;
}
// 确认换号授权
sdkInstance.authorizeAccountSwitch({
qrContent: response.data.qrContent, // 二维码内容
success: function(res) {
// 提示粉丝授权成功
sdkInstance.modal.message("授权成功");
// 退出游戏服登录，回到游戏登录界面，注意：这是一段伪代码，具体由开发者自行实现
logoutGameServer();
},
fail: function(err) {
sdkInstance.modal.message(err.message);
}
});
}
});
},
fail: function(error) {
// 此处返回接口调用失败的错误信息，error.code为cancel时，表示用户主动取消了扫码，此时可以不向用户弹出提示
if (error.code === "cancel") {
return;
}
// 此处可向用户弹出接口返回的错误消息
sdkInstance.modal.message(error.message);
},
complete: function(result) {
// do something here...
}
});
# 确认换号授权
# 接口说明
用于粉丝端将自己的游戏账号授权给主播登录（2.5.0 版本新增），授权仅单次有效。已登录时以当前登录的账号进行授权；未登录时以当前设备抖音号对应的账号进行授权。
注意，确认授权成功后，SDK 会清除粉丝端的登录信息，游戏需提示粉丝授权成功并退出游戏服登录；粉丝重新登录游戏后，主播端的授权登录将失效。授权登录状态下不支持调用此接口，调用时将直接触发失败回调函数，返回值中的 code 为 delegated。
sdkInstance.authorizeAccountSwitch(options);
# 调用时机
在粉丝扫码成功，并在二次确认弹窗中点击确认后调用。
# 参数说明
参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| qrContent | string | 是 | -- | 二维码内容，通过「扫一扫换号二维码」接口获取 |
| success | function | 否 | -- | 接口调用成功的回调函数 |
| fail | function | 否 | -- | 接口调用失败的回调函数 |
| complete | function | 否 | -- | 接口调用完成的回调函数，成功或失败均会调用 |
# 返回值说明
注意
返回值格式：JSON 格式。
| 选项 | 类型 | 说明 |
|---|---|---|
| code | string / number | 响应状态码，为 0 时表示授权成功，为 delegated 时表示当前为授权登录状态，其他非 0 状态码均表示授权失败（如二维码已过期、已被他人授权等） |
| data | object / null | 授权结果，游戏侧无需使用，根据 code 判断是否授权成功即可 |
| message | string | 接口调用成功或失败时的相应描述信息 |
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 粉丝在二次确认弹窗中点击确认后，确认换号授权
sdkInstance.authorizeAccountSwitch({
qrContent: "xxxxxxxxxx", // 二维码内容，通过“扫一扫换号二维码”接口获取
success: function(response) {
// 提示粉丝授权成功
sdkInstance.modal.message("授权成功");
// 退出游戏服登录，回到游戏登录界面，注意：这是一段伪代码，具体由开发者自行实现
logoutGameServer();
},
fail: function(error) {
sdkInstance.modal.message(error.message);
},
complete: function(result) {
// do something here...
}
});
# 授权登录
# 接口说明
用于主播端在二维码已授权后，以粉丝授权的账号执行登录，并获取该账号的SDK开放平台用户信息（2.5.0 版本新增）。
注意，授权登录成功后，当前登录的账号即切换为粉丝的账号，并进入授权登录状态，游戏需以粉丝的账号重新登录并进入游戏、重新上报角色信息。
sdkInstance.login(options);
授权登录状态说明
- 授权仅单次有效，主播杀掉小游戏进程后重新进入游戏并登录，即恢复为主播自身的账号；
- 授权登录状态下，SDK 会定时检测授权登录凭证是否失效，粉丝重新登录游戏后凭证失效，并触发「监听登录过期事件」接口注册的回调函数；
- 授权登录状态下，部分能力不可用，详情请查看下文《授权登录状态下的能力限制》章节。
# 调用时机
在「监听换号二维码状态变化事件」的回调函数中，二维码状态为已授权（CONFIRMED）时调用。
# 参数说明
参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| qrUuid | string | 是 | -- | 二维码ID，取自换号二维码状态变化事件回调中的 data.qrUuid |
| authorizationId | number | 是 | -- | 授权ID，取自换号二维码状态变化事件回调中的 data.authorizationId |
| success | function | 否 | -- | 登录成功的回调函数，返回SDK开放平台用户信息 |
| fail | function | 否 | -- | 登录失败的回调函数，返回错误信息 |
| complete | function | 否 | -- | 登录完成的回调函数，成功或失败均会调用 |
# 返回值说明
注意
返回值格式：JSON 格式。
| 选项 | 类型 | 说明 |
|---|---|---|
| code | number | 登录请求状态码，为 0 时表示登录成功，其他非 0 状态码均表示登录失败 |
| data | object / null | 登录成功时返回粉丝账号的SDK开放平台用户信息，失败时返回 null |
| data.accountId | number | 账号ID |
| data.accountName | string | 账号名称 |
| data.accountView | string | 账号缩略 |
| data.region | number | 所属地区，1 表示中国大陆，0 表示港澳台及海外 |
| data.loginType | number | 登录类型 |
| data.loginTimestamp | number | 登录时间，秒级时间戳 |
| data.expireTimestamp | number | 登录态过期时间，秒级时间戳 |
| data.token | string | 登录token |
| data.sign | string | 签名（本地验签使用） |
| data.isDelegatedLogin | boolean | 是否为授权登录状态，授权登录成功时为 true |
| data.userExtraInfo | object | 用户扩展信息，用于存储用户于第三方渠道侧的信息 |
| data.userExtraInfo.openId | string | 用户在抖音侧的唯一标识（openId） |
| message | string | 登录成功或失败时的相应描述信息 |
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 在换号二维码状态变化事件的回调函数中，二维码已授权时执行授权登录
sdkInstance.login({
qrUuid: result.data.qrUuid, // 二维码ID，必填
authorizationId: result.data.authorizationId, // 授权ID，必填
success: function(response) {
console.log(response.data.accountId); // 粉丝的账号ID
console.log(response.data.isDelegatedLogin); // 是否为授权登录状态，此处为true
// 退出当前游戏服，并以粉丝的账号重新登录游戏服，注意：这是一段伪代码，具体由开发者自行实现
reloginGameServer(response.data);
},
fail: function(error) {
sdkInstance.modal.message(error.message);
},
complete: function(result) {
// do something here...
}
});
# 登录验证
授权登录成功后，需获取返回值 response.data 中的 accountId、loginType 及 token 等数据，并发送给游戏服务器，由游戏服务器按照《服务端对接 > 登录支付 > 登录验证》文档说明调用验签接口进行登录验证！
# 监听登录过期事件
# 接口说明
用于主播端监听登录过期事件（2.5.0 版本新增），授权登录状态下，授权登录凭证失效（如粉丝重新登录游戏）时触发回调函数，此时 SDK 已清除当前的登录信息。
注意，多次注册时以最后一次注册的回调函数为准；回调函数触发后，游戏需提示主播登录凭证已过期并退出游戏，回到游戏登录界面，主播可重新调用《登录》接口恢复自身的账号。
sdkInstance.onLoginExpired(callback);
# 参数说明
参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| callback | function | 是 | -- | 事件回调函数，未传入或不是函数类型时，在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示） |
# 返回值说明
无
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 游戏启动后注册监听
sdkInstance.onLoginExpired(function() {
// 提示主播登录凭证已过期
sdkInstance.modal.message("登录凭证已过期，请重新登录");
// 退出游戏服，回到游戏登录界面，注意：这是一段伪代码，具体由开发者自行实现
logoutGameServer();
});
# 取消监听登录过期事件
# 接口说明
用于主播端取消监听登录过期事件（2.5.0 版本新增）。
sdkInstance.offLoginExpired();
# 参数说明
无
# 返回值说明
无
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 取消监听登录过期事件
sdkInstance.offLoginExpired();
# 获取是否为授权登录状态
# 接口说明
用于获取当前是否为授权登录状态（2.5.0 版本新增）。
const isDelegatedLogin = sdkInstance.isDelegatedLogin();
# 参数说明
无
# 返回值说明
返回值类型为 boolean，为 true 时表示当前为授权登录状态，未登录或非授权登录状态下返回值为 false。
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
// 授权登录状态下，隐藏游戏内的充值入口，注意：这是一段伪代码，具体由开发者自行实现
if (sdkInstance.isDelegatedLogin()) {
hidePayEntry();
}
# 授权登录状态下的能力限制
授权登录状态下，抖音侧的用户信息、支付、订阅等能力仍绑定在主播设备自身的抖音号上，与当前登录的粉丝账号并不一致，因此 SDK 对以下接口进行了拦截，调用时将直接触发失败回调函数，返回值中的 code 为 delegated：
| 接口 | 说明 |
|---|---|
| getUserInfo | 获取抖音用户信息 |
| pay | 支付 |
| subscribeMessage | 一次性订阅消息 |
| subscribeLongestMessage | 长期订阅消息 |
| checkFeedSubscribeStatus | 查询直玩订阅授权状态 |
| subscribeFeedMessage | 直玩订阅 |
| joinGroup | 加入群聊 |
| scanAccountSwitchQRCode | 扫一扫换号二维码 |
| authorizeAccountSwitch | 确认换号授权 |
# 特殊风控说明
- 单次授权：扫码授权后仅当次有效，主播杀掉小游戏进程后重新进入游戏，恢复为主播自身抖音号对应的账号；
- 用户顶号：主播使用粉丝账号期间，粉丝重新登录游戏时，主播端将触发登录过期事件，游戏需提示主播「登录凭证已过期」并退出游戏。
← 登录 获取抖音用户信息（选接） →