KTV SDK 登录模块接入文档

概述

KTV SDK 提供了完整的登录体系，支持多种登录方式包括暗账号登录、匿名登录、三方自实现扫码登录等。本文档将详细介绍登录相关的核心接口和使用方法。

核心服务：KtvLoginService.kt

功能特性

支持的登录方式

游客登录（匿名登录） - 仅能调用接口，不能使用会员功能

三方自实现扫码登录 - 厂商自主实现扫码登录逻辑，提高安全性

暗账号登录

暗账号可实现静默登录，从而实现与三方账号的绑定，但它本身没有真实的K歌账号。

因为没有真实的K歌账号，所以无法使用用户资产相关的接口。比如上传/查询用户作品、个性化推荐接口。

注：此权限需要单独开通，找K歌产品沟通（K歌产品需在开通appid单独说明，并在内部“开放平台对接记录”表标明是登录方式为“暗账号登录”）

核心功能

多种登录方式支持

自动token刷新机制

登录状态监听和管理

VIP信息查询和刷新

数据上报功能

完善的错误处理机制

1. 监听器管理

2. 暗账号登录

方法定义：

3. 匿名登录（游客模式）

4. 三方自实现扫码登录

全民K歌开放平台提供了登录的相关接口，可让厂商自己实现登录（一般是厂商服务端请求登录接口，不要用sdk的网络框架接口）。
具体可查看登录鉴权方式介绍V2 中的方案三，获取用户级token。
不要将appKey放在本地
如果厂商自实现登录，需要实现接口以使sdk可以获取最新登录状态或者token，简单示例：

            ThirdPartyLoginService.setLoginTokenImpl(object : IKGetToken {
                    return if (!notLogin()) {
                        //未登录时返回false，未登录状态需厂商自己判断
                        ThirdPartyLoginToken(false, null, null)
                    } else {
                        //已登录，由接入方获取当前最新token（注意token有时效性，需要接入方保证token是最新的）
                        ThirdPartyLoginToken(true,"token", "openid")
                    }
            })

ThirdPartyLoginToken的第一个参数是是否登录，第二个参数是token，第三个参数是openId；
另外需要在三方登录成功和退出登录时，主动通知到sdk，以便及时更新状态；

        //登录成功时
            val loginParams = KtvLoginParams()
            loginParams.loginType = LoginType.QRCODE_LOGIN
            ThirdPartyLoginService.notifyLoginStateChanged(
                LoginEvent.LoginSuccess(loginParams, 
                    LoginToken("refreshToken","openId",0L,"token")))
        //退出登录时
        ThirdPartyLoginService.notifyLoginStateChanged(LoginEvent.Logout("openid"))

其中LoginToken参数分别为 refreshToken、openid、token过期时间、token，除了openid，其他可以不传。

登录异常处理：
当请求接口出现以下错误码时代表登录状态异常，接入方可以在网络请求框架中对这些错误码特殊处理：
40002：登录token失效，清除当前token，重新使用refresh_token刷新token；
40004：多设备登录导致帐号登录态失效，此时需要清空当前token和refresh_token，让用户重新登录。

API接入说明

1. 游客登录API

KtvLoginService.anonymouslyLogin()

方法定义：

参数说明：

loginAPI: 登录事件监听器，用于接收登录结果回调

使用流程：
2. 如果未登录，调用 anonymouslyLogin() 开始游客登录
3. 通过 loginAPI 监听登录结果
4. 登录成功后会收到 LoginEvent.LoginSuccess 事件
5. 登录失败会收到 LoginEvent.LoginError 事件

注意事项：

游客模式下功能可能受限，部分高级功能需要正式登录

游客登录无需任何用户凭证，适用于快速体验场景

登录过程是异步的，结果通过回调返回

错误处理：

SDKLoginError.ANONYMOUS_LOGIN_EXPIRED: 游客登录过期，需要重新登录

SDKLoginError.ANONYMOUS_LOGIN_FAIL: 游客登录失败，可重试

2. 暗账号登录API

KtvLoginService.hiddenAccountLogin()

方法定义：

参数说明：

code: 暗账号登录码，需要从服务端获取

loginAPI: 登录事件监听器，用于接收登录结果回调

使用流程：

从服务端获取暗账号登录码

KtvLoginService.isLogin()只能用于判断是否有本地登录token，不能判断token的有效性

如果未登录，调用 hiddenAccountLogin() 开始暗账号登录

通过 loginAPI 监听登录结果

登录成功后会收到 LoginEvent.LoginSuccess 事件

登录失败会收到 LoginEvent.LoginError 事件

注意事项：

暗账号登录码具有时效性，需要确保使用有效的登录码

登录成功后SDK会自动管理token的刷新

支持refresh_token自动刷新机制

错误处理：

SDKLoginError.HIDDEN_ACCOUNT_LOGIN_FAIL: 暗账号登录失败

SDKLoginError.REFRESH_TOKEN_NULL: 刷新token为空，需要重新登录

SDKLoginError.REFRESH_TOKEN_EXPIRED: 刷新token过期，需要重新登录

SDKLoginError.REFRESH_TOKEN_ERROR_UNKNOWN: 刷新token接口失败

**更详尽内容：**请参照全民K歌暗账号登录方案

3. 三方自实现扫码登录API

ThirdPartyLoginService.setLoginTokenImpl()

方法定义：

参数说明：

getTokenImpl: token获取接口实现，厂商需要实现此接口

IKGetToken接口定义：

ThirdPartyLoginToken数据结构：

ThirdPartyLoginService.notifyLoginStateChanged()

方法定义：

参数说明：

loginEvent: 登录事件，用于通知SDK登录状态变化

使用流程：

实现 IKGetToken 接口，提供token获取逻辑

调用 setLoginTokenImpl() 设置token获取实现

在登录成功时调用 notifyLoginStateChanged() 通知SDK

在退出登录时调用 notifyLoginStateChanged() 通知SDK

SDK会根据需要调用 onGetToken() 获取最新token

注意事项：

厂商需要自主实现扫码登录的完整流程

需要维护登录状态和token的有效性

及时通知SDK登录状态变化，确保SDK功能正常

4. 监听器管理API

KtvLoginService.bind()

方法定义：

参数说明：

loginAPI: 登录事件监听器

使用说明：

适用于页面级别的登录监听

用户登出时会自动清除

建议在Activity/Fragment中使用

KtvLoginService.bindForever()

方法定义：

参数说明：

loginAPI: 登录事件监听器

使用说明：

适用于全局级别的登录监听

用户登出时不会被清除

适用于用户信息管理、数据同步等场景

KtvLoginService.unbind()

方法定义：

参数说明：

loginAPI: 需要解绑的登录事件监听器

使用说明：

手动解除监听器绑定

建议在Activity/Fragment的onDestroy中调用

避免内存泄漏

5. 登录状态查询API

KtvLoginService.isLogin()

方法定义：

返回值：

true: 已登录

false: 未登录

KtvLoginService.getToken()

方法定义：

返回值：

当前有效的访问token，未登录时返回null

KtvLoginService.getLoginOpenId()

方法定义：

返回值：

当前登录用户的唯一标识

KtvLoginService.isAnonymouslyLoginMode()

方法定义：

返回值：

true: 当前为匿名登录模式

false: 当前为正式登录模式

KtvLoginService.getTokenOverTimeMs()

方法定义：

返回值：

token过期时间戳（毫秒）

6. 登录管理API

KtvLoginService.loginOut()

方法定义：

功能说明：

清除本地token信息

通知所有监听器登出事件

清除普通监听器（保留持久化监听器）

KtvLoginService.cancel()

方法定义：

参数说明：

loginAPI: 需要取消的登录监听器，传null表示取消当前登录

isRelease: 是否同时解除监听器绑定

功能说明：

取消当前正在进行的登录

可选择是否同时解除监听器绑定

7. VIP信息管理API

KtvLoginService.requestUserVipInfo()

方法定义：

参数说明：

listener: VIP信息请求结果监听器

RequestUserVipListener接口定义：

使用场景：

用户购买VIP后刷新信息

定期同步VIP状态

功能权限验证前的信息更新

8. 数据上报API

除非K歌产品明确要求厂商上报APP数据，否则此接口不要调用

KtvLoginService.sendAppReport()

方法定义：

参数说明：

key: 上报事件标识

reportMap: 上报数据键值对

callback: 上报结果回调

返回值：

上报数据对象，失败时返回null

登录事件处理

LoginEvent事件类型

LoginEvent.LoginSuccess

登录成功事件

loginParams: 登录参数

tokenInfo: 登录成功后的token信息

LoginEvent.AutoLoginSuccess

自动登录成功事件

openId: 用户唯一标识

overTimeMs: token过期时间戳

LoginEvent.RefreshTokenSuccess

token刷新成功事件

SDK会自动刷新token，接入方通常无需特殊处理

LoginEvent.LoginError

登录错误事件

exception: 登录异常信息，包含错误码和详细信息

LoginEvent.Logout

登出事件

用户主动登出或token失效时触发

错误码说明

SDKLoginError错误码定义

错误码	常量名	说明	处理建议
101	AUTH_CODE	授权码错误	检查授权码有效性
102	CANCEL	用户取消登录	无需特殊处理
103	UNKNOWN	未知错误	重试或联系技术支持
104	ANONYMOUS_LOGIN_EXPIRED	匿名登录过期	重新进行匿名登录
105	ANONYMOUS_LOGIN_FAIL	匿名登录失败	重试匿名登录
106	REFRESH_TOKEN_NULL	刷新token为空	重新登录
107	REFRESH_TOKEN_EXPIRED	刷新token过期	重新登录
108	REFRESH_TOKEN_ERROR_UNKNOWN	刷新token未知错误	重新登录
109	HIDDEN_ACCOUNT_LOGIN_FAIL	暗账号登录失败	检查登录码或重试
110	GET_TOKEN_NOT_LOGIN	获取token时未登录	先进行登录

LoginConst常量定义

常量值	常量名	说明
3003	CODE_SIGN_CHECK_FAILED	签名校验失败
3005	CODE_REFRESH_TOKEN_EXPIRED	token过期，需重新授权
3017	CODE_REFRESH_TOKEN_NOT_EXIST	token不存在或已被覆盖

文件间关系和调用流程

1. 整体架构关系

KtvLoginService (门面服务)
    ├── IKLoginAPI (事件监听接口)
    ├── LoginEvent (事件定义)
    ├── LoginToken (token数据)
    ├── LoginException (异常定义)
    └── ThirdPartyLoginService (三方登录服务)
        ├── IKGetToken (token获取接口)
        └── ThirdPartyLoginToken (三方token数据)

2. 典型调用流程

暗账号登录流程：

调用KtvLoginService.hiddenAccountLogin(code, loginAPI)

SDK内部创建登录链路，发起网络请求

登录成功后触发LoginEvent.LoginSuccess事件

通过IKLoginAPI.dispatchLoginEvent()回调给监听器

监听器处理登录成功逻辑

匿名登录流程：

调用KtvLoginService.anonymouslyLogin(loginAPI)

SDK生成匿名用户信息

触发LoginEvent.LoginSuccess或相应事件

回调给监听器处理

三方自实现扫码登录流程：

可查看登录鉴权方式介绍V2 中的方案三，获取用户级token

3. 监听器生命周期管理

绑定阶段：
bind() / bindForever() → 添加到监听器列表

事件分发阶段：
登录状态变化 → dispatchLoginEvent() → 遍历所有监听器 → 回调处理

清理阶段：
普通监听器：loginOut() 时自动清除
持久化监听器：需要手动 unbind()

接入建议和注意事项

1. 监听器选择

页面级监听：使用bind()，绑定SDK登录事件回调，这个回调在调用loginOut后会被取消

全局监听：使用bindForever()，用于用户状态管理、数据同步等

2. 错误处理

监听LoginEvent.LoginError事件

根据LoginException类型和错误码进行相应处理

网络错误时考虑重试机制

3. Token管理

暗账号和游客态登录方式中，SDK会自动管理token的刷新；厂商自实现扫码登录由厂商自己维护

可通过getTokenOverTimeMs()检查token有效期（仅暗账号和游客态登录）

建议在token即将过期前主动刷新

4. 线程安全

所有回调可能在任意线程执行

UI操作需要切换到主线程

避免在回调中执行耗时操作

5. 内存泄漏防护

及时调用unbind()解除监听

避免在匿名内部类中持有Activity引用

使用弱引用或生命周期感知组件

KtvSDK-登录

KTV SDK 登录模块接入文档#

概述#

核心服务：KtvLoginService.kt#

功能特性#

支持的登录方式#

核心功能#

1. 监听器管理#

2. 暗账号登录#

3. 匿名登录（游客模式）#

4. 三方自实现扫码登录#

API接入说明#

1. 游客登录API#

KtvLoginService.anonymouslyLogin()#

2. 暗账号登录API#

KtvLoginService.hiddenAccountLogin()#

3. 三方自实现扫码登录API#

ThirdPartyLoginService.setLoginTokenImpl()#

ThirdPartyLoginService.notifyLoginStateChanged()#

4. 监听器管理API#

KtvLoginService.bind()#

KtvLoginService.bindForever()#

KtvLoginService.unbind()#

5. 登录状态查询API#

KtvLoginService.isLogin()#

KtvLoginService.getToken()#

KtvLoginService.getLoginOpenId()#

KtvLoginService.isAnonymouslyLoginMode()#

KtvLoginService.getTokenOverTimeMs()#

6. 登录管理API#

KtvLoginService.loginOut()#

KtvLoginService.cancel()#

7. VIP信息管理API#

KtvLoginService.requestUserVipInfo()#

8. 数据上报API#

KtvLoginService.sendAppReport()#

登录事件处理#

LoginEvent事件类型#

LoginEvent.LoginSuccess#

LoginEvent.AutoLoginSuccess#

LoginEvent.RefreshTokenSuccess#

LoginEvent.LoginError#

LoginEvent.Logout#

错误码说明#

SDKLoginError错误码定义#

LoginConst常量定义#

文件间关系和调用流程#

1. 整体架构关系#

2. 典型调用流程#

暗账号登录流程：#

匿名登录流程：#

三方自实现扫码登录流程：#

3. 监听器生命周期管理#

接入建议和注意事项#

1. 监听器选择#

2. 错误处理#

3. Token管理#

4. 线程安全#

5. 内存泄漏防护#

KTV SDK 登录模块接入文档

概述

核心服务：KtvLoginService.kt

功能特性

支持的登录方式

核心功能

1. 监听器管理

2. 暗账号登录

3. 匿名登录（游客模式）

4. 三方自实现扫码登录

API接入说明

1. 游客登录API

KtvLoginService.anonymouslyLogin()

2. 暗账号登录API

KtvLoginService.hiddenAccountLogin()

3. 三方自实现扫码登录API

ThirdPartyLoginService.setLoginTokenImpl()

ThirdPartyLoginService.notifyLoginStateChanged()

4. 监听器管理API

KtvLoginService.bind()

KtvLoginService.bindForever()

KtvLoginService.unbind()

5. 登录状态查询API

KtvLoginService.isLogin()

KtvLoginService.getToken()

KtvLoginService.getLoginOpenId()

KtvLoginService.isAnonymouslyLoginMode()

KtvLoginService.getTokenOverTimeMs()

6. 登录管理API

KtvLoginService.loginOut()

KtvLoginService.cancel()

7. VIP信息管理API

KtvLoginService.requestUserVipInfo()

8. 数据上报API

KtvLoginService.sendAppReport()

登录事件处理

LoginEvent事件类型

LoginEvent.LoginSuccess

LoginEvent.AutoLoginSuccess

LoginEvent.RefreshTokenSuccess

LoginEvent.LoginError

LoginEvent.Logout

错误码说明

SDKLoginError错误码定义

LoginConst常量定义

文件间关系和调用流程

1. 整体架构关系

2. 典型调用流程

暗账号登录流程：

匿名登录流程：

三方自实现扫码登录流程：

3. 监听器生命周期管理

接入建议和注意事项

1. 监听器选择

2. 错误处理

3. Token管理

4. 线程安全

5. 内存泄漏防护