初始化与鉴权

初始化与鉴权

TmkTranslationSDK.shared

SDK 入口是单例：

TmkTranslationSDK.shared

类型：TmkTranslationSDK

sdkVersion

获取当前 SDK 版本号，返回不带前缀的语义化版本字符串（如 1.3.1）。该属性为类型级静态常量，无需 shared 实例即可读取。

public static let sdkVersion: String

示例：

let version = TmkTranslationSDK.sdkVersion // "1.3.1"

sdkInit(_:)

用于初始化 SDK 全局配置。

public func sdkInit(_ config: TmkTranslationGlobalConfig)

参数说明：

• config: TmkTranslationGlobalConfig

  • SDK 全局配置对象。

返回值：

• 无返回值。

行为说明：

• 只保存全局配置并初始化日志。

• 不会自动触发鉴权。

• 调用 destroy() 后，如需继续使用，必须重新调用 sdkInit(_:)。

示例：

let globalConfig = TmkTranslationGlobalConfig.Builder()
    .setAuth(appId: "your_app_id", secret: "your_app_secret")
    .setOnlineAuthContext(
        tenantId: "your_tenant_id",
        externalUserId: "your_external_user_id",
        installId: "your_install_id"
    )
    .setLogEnabled(true)
    .setDiagnosisConfig(
        TmkDiagnosisConfig(
            enabled: true,
            level: .essential,
            rootDirectory: nil,
            audioCaptureEnabled: false
        )
    )
    .setNetworkEnvironment(.test)
    .build()

TmkTranslationSDK.shared.sdkInit(globalConfig)

verifyAuth(_:)

执行在线/离线鉴权。

public func verifyAuth(_ callback: @escaping AuthCallback)

参数说明：

• callback

  • 鉴权回调。

  • 成功：.success(())

  • 失败：.failure(TmkTranslationError)

返回值：

• 无返回值。

行为说明：

• 首次调用时会懒初始化网络监听、诊断和鉴权基础设施。

• 在线翻译必须先鉴权成功。

• verifyAuth(_:) 内部会先执行在线鉴权；在线鉴权成功后，如果服务端开启离线能力，会继续尝试 License 获取和离线鉴权，用于记录离线支持状态。

• verifyAuth(_:) 的回调成功/失败只由在线鉴权结果决定；离线开关关闭、License 获取失败或离线鉴权失败都不会导致本次 verifyAuth(_:) 回调失败。

• 离线翻译建议先鉴权，再通过 isOfflineTranslationSupported() 判断当前账号是否支持离线能力。

• 离线翻译并不是完全零前置条件可直接使用：至少需要先成功鉴权一次、离线能力开关已开启、且相关离线模型曾下载成功。

• 在线 verifyAuth(_:) 的回调契约保持不变。iOS 设备密钥的 Security.framework 异常不会被笼统改写为 2001102；当后续离线能力接口或离线通道暴露该异常时，按 2001201-2001206/2001299 处理，并从 actualErrorCode、actualErrorDomain、actualErrorMessage 获取脱敏诊断信息，详见错误码速查。

示例：

TmkTranslationSDK.shared.verifyAuth { result in
    switch result {
    case .success:
        print("鉴权成功")
    case .failure(let error):
        print("鉴权失败: \(error.code) \(error.message)")
    }
}

isOfflineTranslationSupported()

查询当前鉴权结果是否支持离线翻译。

public func isOfflineTranslationSupported() -> Bool

返回值：

• true：当前鉴权上下文支持离线翻译。

• false：当前账号未开通离线翻译能力，或尚未完成离线鉴权。

注意

建议在 verifyAuth(_:) 成功后再调用。verifyAuth(_:) 成功仅表示在线鉴权成功；如果离线鉴权未成功，当前接口仍可能返回 false。

---

全局配置 TmkTranslationGlobalConfig

TmkTranslationNetworkEnvironment

SDK 内置环境枚举：

public enum TmkTranslationNetworkEnvironment: String {
    case dev
    case test
    case pre
}

建议

• dev 仅用于开发调试，对外接入请优先使用 test 或 Timekettle 指定环境。
• setNetworkBaseURL(_:) 一般只用于联调或特殊接入，不建议线上随意切换。

TmkTranslationGlobalConfig.Builder

public final class Builder {
    public init()
    public func setAuth(appId: String, secret: String) -> Builder
    public func setOnlineAuthContext(tenantId: String? = nil,
                                     externalUserId: String? = nil,
                                     installId: String? = nil) -> Builder
    public func setLogEnabled(_ isEnabled: Bool) -> Builder
    public func setDiagnosisConfig(_ config: TmkDiagnosisConfig) -> Builder
    public func setNetworkEnvironment(_ environment: TmkTranslationNetworkEnvironment) -> Builder
    public func setNetworkBaseURL(_ url: URL) -> Builder
    public func setNetworkBaseURL(_ urlString: String) -> Builder
    public func setOfflineModelBaseURL(_ url: URL) -> Builder
    public func setOfflineModelBaseURL(_ urlString: String?) -> Builder
    public func setNetworkTimeout(_ seconds: TimeInterval) -> Builder
    public func build() -> TmkTranslationGlobalConfig
}

各接口说明：

setAuth(appId:secret:)

• appId

  • 业务鉴权 App ID。

• secret

  • 业务鉴权 App Secret。

必填。

setOnlineAuthContext(tenantId:externalUserId:installId:)

• tenantId

  • 可选，租户标识。

• externalUserId

  • 可选，业务用户 ID。

  • 如果传入，则优先级高于 installId。

• installId

  • 可选，设备/安装实例 ID。

setLogEnabled(_:)

• true：输出 SDK 控制台日志。

• false：关闭控制台日志。

setDiagnosisConfig(_:)

• 设置分级诊断日志配置。

• 默认配置为 TmkDiagnosisConfig()，即开启诊断、essential 等级、使用默认诊断目录、不采集音频。

TmkDiagnosisConfig

public enum TmkDiagnosisLevel: String {
    case essential
    case diagnostic
    case trace
}

public struct TmkDiagnosisConfig {
    public init(enabled: Bool = true,
                level: TmkDiagnosisLevel = .essential,
                rootDirectory: URL? = nil,
                audioCaptureEnabled: Bool = false)
}

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

setNetworkEnvironment(_:)

• 设置预置环境。

setNetworkBaseURL(_:)

• 设置自定义服务端地址。

• 优先级高于 setNetworkEnvironment(_:)。

setOfflineModelBaseURL(_:)

• 设置离线模型仓库根地址，例如 https://your-domain.example/offline-models/v3.1。

• 该地址仅控制离线模型包的下载、包状态与就绪校验，与 setNetworkBaseURL(_:) 相互独立。

• 传入 nil、空字符串或非法地址时，SDK 回退到内置默认模型仓库。生产环境应使用 Timekettle 指定的 HTTPS 模型仓库。

setNetworkTimeout(_:)

• 设置所有网络请求的统一超时时间（秒）。

• 作用于鉴权、建房、建通道、语言列表、音色更新等所有网络请求，以及对应的 watchdog 超时。

• 非有限值或小于等于 0 时忽略，回退默认 15 秒。

build()

• 生成不可变的 TmkTranslationGlobalConfig。

---