Version: v1.3.2

初始化与鉴权

`TmkTranslationSDK`

Android SDK 入口是 Kotlin object：

TmkTranslationSDK

`sdkVersion`

获取当前 SDK 版本号，返回不带前缀的语义化版本字符串（如 1.3.2）。该属性为静态只读，无需初始化即可读取。

@JvmStatic
val sdkVersion: String

示例：

val version = TmkTranslationSDK.sdkVersion // "1.3.2"

Java 调用：

String version = TmkTranslationSDK.getSdkVersion();

`sdkInit(context, config)`

用于初始化 SDK 全局配置。

fun sdkInit(context: Context, config: TmkTransGlobalConfig)

参数说明：

参数	说明
`context`	建议传入 `ApplicationContext`，SDK 内部会保存 application context
`config`	SDK 全局配置对象

行为说明：

初始化鉴权、诊断日志、MMKV 和埋点基础设施。
不会自动触发鉴权。
调用 destroy() 后，如需继续使用，必须重新调用 sdkInit(context, config)。

示例：

val globalConfig = TmkTransGlobalConfig.Builder()
    .setAuth("your_app_id", "your_app_secret")
    .setDiagnosisConfig(
        TmkDiagnosisConfig(
            enabled = true,
            level = TmkDiagnosisLevel.ESSENTIAL,
            rootDirectory = null,
            audioCaptureEnabled = false
        )
    )
    .setDiagnosisConsoleEnabled(false)
    .build()

TmkTranslationSDK.sdkInit(applicationContext, globalConfig)

`verifyAuth(callback)` 与 `verifyAuth(mode, callback)`

调用方可通过带 mode 的重载选择鉴权方式。无模式重载等同于 DEFAULT。SDK 不会根据收听、一对一等业务场景自动选择或强制某个鉴权模式。

fun verifyAuth(
    mode: TmkAuthVerifyMode,
    callback: AuthCallback,
)

fun verifyAuth(callback: AuthCallback)

enum class TmkAuthVerifyMode {
    DEFAULT,
    ONLINE,
    OFFLINE,
    ALL,
}

回调说明：

interface AuthCallback {
    fun onSuccess()
    fun onError(errorId: Int, e: Exception)
}

各模式的回调结果如下：

模式	是否执行在线鉴权	离线 License 处理	回调成功条件	失败影响
`DEFAULT`	始终执行	检查本地 License；有效时直接复用，需要更新时才申请并执行离线鉴权	在线鉴权成功即 `onSuccess`	在线失败返回 `onError`；离线失败仅使离线能力不可用
`ONLINE`	始终执行	不检查、不申请	在线鉴权成功	在线失败返回 `onError`；不改变已有离线鉴权结果
`OFFLINE`	不执行在线鉴权	优先复用有效本地 License；无有效 License 时，复用或获取 token 后申请 License	离线 License 鉴权成功	获取 token、申请 License 或离线鉴权任一失败均返回 `onError`
`ALL`	始终执行	在线成功后检查本地 License；有效时直接复用，否则申请并执行离线鉴权	在线和离线鉴权都成功	任一阶段失败均返回 `onError`

verifyAuth(callback) 等同于 verifyAuth(TmkAuthVerifyMode.DEFAULT, callback)。DEFAULT 成功不代表离线鉴权成功。

行为说明：

首次调用前必须完成 sdkInit(context, config)。
SDK 不会根据业务入口自动选择鉴权模式；调用方应根据所需的在线/离线鉴权结果选择模式。
SDK 会管理鉴权会话和离线授权数据缓存；应用无需自行维护。各模式是否需要请求在线服务，由所选模式及当前账号状态决定。
DEFAULT 保留历史“在线成功即可完成回调”的语义：SDK 仍会检查/刷新离线 License，但离线失败只更新离线能力状态，不会使本次回调失败；ALL 则要求在线和离线 License 鉴权均成功。
License 请求若收到后台 1007（当前 token 与设备授权上下文不匹配），SDK 会清理缓存 token、强制刷新一次并重试一次 License 请求；第二次仍失败时通过 TmkTranslationException 保留原始后端错误信息。App 应提示用户联网重新鉴权，不要自行处理 token 或删除 Keystore 中的设备密钥。
Android 离线 License 鉴权失败对外统一使用 2001102 / AUTHENTICATION_FAILED；底层 native 返回码和诊断摘要通过 TmkTranslationException.actualErrorCode、actualErrorMessage、actualErrorDomain 保留。iOS 专属的 2001201-2001206/2001299 不在 Android 侧产生。
并发调用同一鉴权模式时，SDK 会合并同一轮鉴权请求，并把结果回调给所有等待方。

示例：

val mode = TmkAuthVerifyMode.ONLINE // 按需改为 DEFAULT、OFFLINE 或 ALL

TmkTranslationSDK.verifyAuth(mode, object : AuthCallback {
    override fun onSuccess() {
        // 所选模式的鉴权已成功
    }

    override fun onError(errorId: Int, e: Exception) {
        // errorId 通常对应 TmkTranslationException.ErrorCodes
        // 如需后台/native 原始错误码，可读取 (e as? TmkTranslationException)?.actualErrorCode
    }
})

`isOfflineTranslationSupported()`

查询当前鉴权上下文是否支持离线翻译。

fun isOfflineTranslationSupported(): Boolean

返回值：

true：当前鉴权上下文支持离线翻译。
false：当前账号未开通离线翻译能力，或尚未完成鉴权。

注意

建议在鉴权完成后再调用。若需要确认离线 License 鉴权结果，应使用 OFFLINE 或 ALL，并在对应鉴权回调成功后调用；DEFAULT 或 ONLINE 成功仅表示在线鉴权成功，不代表离线 License 鉴权成功。

全局配置 `TmkTransGlobalConfig`

`TmkTransGlobalConfig.Builder`

Builder 方法	说明
`setAuth(appId, secret)`	设置业务鉴权凭据
`setOnlineAuthContext(tenantId, externalUserId, installId)`	设置在线鉴权扩展上下文，`externalUserId` 优先级高于 `installId`
`setDiagnosisConfig(config)`	设置分级诊断日志配置；默认 `TmkDiagnosisConfig()`
`setDiagnosisConsoleEnabled(enabled)`	是否同步输出诊断日志到控制台，默认 `true`
`setNetworkEnvironment(environment)`	设置预置网络环境
`setNetworkBaseURL(url)`	设置自定义服务端地址，优先级高于预置环境
`setOfflineModelBaseURL(url)`	设置离线模型仓库根地址；为空或非法地址时使用 SDK 默认地址
`setNetworkTimeout(seconds)`	设置所有网络请求与 SDK watchdog 的统一超时（秒），作用于鉴权、建房、建通道等；非正数或超过 Android 支持范围的值会忽略并回退默认 15 秒
`build()`	构建 `TmkTransGlobalConfig`

`TmkDiagnosisConfig`

enum class TmkDiagnosisLevel {
    ESSENTIAL,
    DIAGNOSTIC,
    TRACE
}

data class TmkDiagnosisConfig(
    val enabled: Boolean = true,
    val level: TmkDiagnosisLevel = TmkDiagnosisLevel.ESSENTIAL,
    val rootDirectory: File? = null,
    val audioCaptureEnabled: Boolean = false
)

配置	默认值	说明
`enabled`	`true`	是否启用诊断日志采集；关闭后不采集 SDK、网络、工作流、Agora 或音频诊断文件。
`level`	`ESSENTIAL`	诊断等级：`ESSENTIAL` 采集主流程和错误；`DIAGNOSTIC` 增加 Agora 普通日志和 completed/final 结果；`TRACE` 增加高频追踪日志。
`rootDirectory`	`null`	诊断日志根目录；为空时使用 Android 默认应用私有目录 `filesDir/sdk_diagnosis`。
`audioCaptureEnabled`	`false`	音频诊断采集开关；仅在 `TRACE` 等级下生效，用于采集 PCM/Agora 音频相关文件。

`TmkTranslationNetworkEnvironment`

SDK 内置环境枚举：

enum class TmkTranslationNetworkEnvironment {
    DEV,
    TEST,
    PRE
}

建议

DEV 仅用于开发调试，对外接入请优先使用 TEST 或 Timekettle 指定环境。
setNetworkBaseURL(url) 一般只用于联调或特殊接入，不建议线上随意切换。
自定义地址必须是合法 http 或 https URL；SDK 会在构建配置时做基础格式归一。
setOfflineModelBaseURL(url) 仅控制离线模型包的下载、包状态与就绪校验，不替代在线服务地址配置。生产环境应使用 Timekettle 指定的 HTTPS 模型仓库。

`setOfflineModelBaseURL(url)`

设置离线模型仓库根地址，例如 https://your-domain.example/offline-models/v3.1。
该地址与 setNetworkBaseURL(url) 相互独立；不要通过在线服务地址配置替换离线模型仓库。
传入 null、空字符串或非法地址时，SDK 回退到内置默认模型仓库。

凭据说明

凭据安全

appId / clientSecret 是业务鉴权凭据，建议通过 Gradle properties、环境变量或 CI Secret 注入，不要写入公开仓库。

val appId = BuildConfig.TMK_APP_ID
val appSecret = BuildConfig.TMK_APP_SECRET

val config = TmkTransGlobalConfig.Builder()
    .setAuth(appId, appSecret)
    .setOnlineAuthContext(
        tenantId = "your_tenant_id",
        externalUserId = "your_external_user_id",
        installId = "your_install_id"
    )
    .setNetworkEnvironment(TmkTranslationNetworkEnvironment.TEST)
    .build()

说明：

tenantId、externalUserId、installId 均为可选扩展参数，按 Timekettle 为接入方分配的鉴权策略填写。
同时传入 externalUserId 和 installId 时，SDK 使用 externalUserId 作为业务用户维度，忽略 installId。