Skip to main content
Version: v1.3.2

初始化与鉴权

初始化与鉴权​

TmkTranslationSDK.shared​

SDK 入口是单例：

TmkTranslationSDK.shared

类型：TmkTranslationSDK

sdkVersion​

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

public static let sdkVersion: String

示例：

let version = TmkTranslationSDK.sdkVersion // "1.3.2"

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"
    )
    .setDiagnosisConsoleEnabled(true)
    .setDiagnosisConfig(
        TmkDiagnosisConfig(
            enabled: true,
            level: .essential,
            rootDirectory: nil,
            audioCaptureEnabled: false
        )
    )
    .setNetworkEnvironment(.test)
    .build()

TmkTranslationSDK.shared.sdkInit(globalConfig)

verifyAuth(_:) 与 verifyAuth(_:_:)​

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

public func verifyAuth(_ mode: TmkAuthVerifyMode, _ callback: @escaping AuthCallback)

public func verifyAuth(_ callback: @escaping AuthCallback)

public enum TmkAuthVerifyMode {
    case `default`
    case online
    case offline
    case all
}

参数说明：

  • callback

    • 鉴权回调。

    • 成功：.success(())

    • 失败：.failure(TmkTranslationError)

返回值：

  • 无返回值。

各模式的回调结果如下：

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

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

行为说明：

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

  • SDK 不会根据业务入口自动选择鉴权模式；调用方应根据所需的在线/离线鉴权结果选择模式。

  • SDK 会管理鉴权会话和离线授权数据缓存；应用无需自行维护。各模式是否需要请求在线服务，由所选模式及当前账号状态决定。

  • .default 保留历史“在线成功即可完成回调”的语义：SDK 仍会检查/刷新离线 License，但离线失败只更新离线能力状态，不会使本次回调失败；.all 则要求在线和离线 License 鉴权均成功。

  • License 请求若收到后台 1007（当前 token 与设备授权上下文不匹配），SDK 会清理缓存 token、强制刷新一次并重试一次 License 请求；第二次仍失败时回调原始错误信息。App 应提示用户联网重新鉴权，不要自行删除设备密钥或处理 token。

  • 离线鉴权成功后，再通过 isOfflineTranslationSupported() 判断当前账号是否支持离线能力。

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

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

示例：

let mode: TmkAuthVerifyMode = .online // 按需改为 .default、.offline 或 .all

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

isOfflineTranslationSupported()​

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

public func isOfflineTranslationSupported() -> Bool

返回值：

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

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

注意

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

全局配置 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 setDiagnosisConsoleEnabled(_ 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。

setDiagnosisConsoleEnabled(_:)​

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

  • false：关闭控制台日志。

  • 默认值为 false（关闭）；与 Android 默认 true 不同，如需输出控制台日志请显式调用 setDiagnosisConsoleEnabled(true)。

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)
}
配置默认值说明
enabledtrue是否启用诊断日志采集；关闭后不采集 SDK、网络、工作流、Agora 或音频诊断文件。
level.essential诊断等级：.essential 采集主流程和错误；.diagnostic 增加 Agora 普通日志和 completed/final 结果；.trace 增加高频追踪日志。
rootDirectorynil诊断日志根目录；为空时使用 iOS 默认目录 Library/sdk_diagnosis。
audioCaptureEnabledfalse音频诊断采集开关；仅在 .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。