版本：v1.3.1

初始化与鉴权

`TmkTranslationSDK`

Android SDK 入口是 Kotlin object：

TmkTranslationSDK

`sdkVersion`

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

@JvmStatic
val sdkVersion: String

示例：

val version = TmkTranslationSDK.sdkVersion // "1.3.1"

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)`

执行在线/离线鉴权。

fun verifyAuth(callback: AuthCallback)

回调说明：

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

行为说明：

首次调用前必须完成 sdkInit(context, config)。
在线翻译必须先鉴权成功。
verifyAuth(callback) 内部会先执行在线鉴权；在线鉴权成功后，如果服务端开启离线能力，会继续尝试 License 获取和离线鉴权，用于记录离线支持状态。
对齐 iOS：最终 onSuccess/onError 只由在线鉴权结果决定；离线开关关闭、License 获取失败或离线 License 鉴权失败都不会导致本次 verifyAuth(callback) 失败，但会影响离线能力状态。
Android 离线 License 鉴权失败对外统一使用 2001102 / AUTHENTICATION_FAILED；底层 native 返回码和诊断摘要通过 TmkTranslationException.actualErrorCode、actualErrorMessage、actualErrorDomain 保留。iOS 专属的 2001201-2001206/2001299 不在 Android 侧产生。
并发调用 verifyAuth(callback) 时，SDK 会合并同一轮鉴权请求，并把结果回调给所有等待方。

示例：

TmkTranslationSDK.verifyAuth(object : AuthCallback {
    override fun onSuccess() {
        val offlineEnabled = TmkTranslationSDK.isOfflineTranslationSupported()
    }

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

`isOfflineTranslationSupported()`

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

fun isOfflineTranslationSupported(): Boolean

返回值：

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

注意

建议在 verifyAuth(callback) 成功后再调用。
verifyAuth(callback) 成功仅表示在线鉴权成功；如果后台未开启离线能力，当前接口仍会返回 false。

全局配置 `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 默认应用私有目录 `files/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。

初始化与鉴权​

TmkTranslationSDK​

sdkVersion​

sdkInit(context, config)​

verifyAuth(callback)​

isOfflineTranslationSupported()​

全局配置 TmkTransGlobalConfig​

TmkTransGlobalConfig.Builder​

TmkDiagnosisConfig​

TmkTranslationNetworkEnvironment​

setOfflineModelBaseURL(url)​

凭据说明​