常见问题

Q: SDK 初始化失败怎么办？

A: 请检查以下几点：

• 确认 appKey 是否正确
• 检查网络连接是否正常
• 确认目标语言代码是否正确
• 查看初始化回调中的错误信息

Q: 获取词条返回空字符串？

A: 可能的原因：

• 词条ID不存在或拼写错误
• 该语言的翻译文件尚未发布
• SDK 尚未初始化完成
• 建议使用带默认值的方法，避免显示空内容

Q: 切换语言后没有生效？

A: 切换语言是异步操作，请确保：

• 等待初始化回调成功后再使用新语言
• 检查语言代码是否正确
• 确认该语言的翻译文件已发布

Q: LoxiBot 悬浮按钮没有出现？

A: SDK 1.2.8+ 不再自动显示悬浮按钮，需要集成方主动调用：

• LoxilyLocalize.showAgentBubble() 显示悬浮按钮
• LoxilyLocalize.hideAgentBubble() 隐藏悬浮按钮
• 或者直接调用 LoxilyLocalize.reviewCurrentScreen() 程序化触发审查

Q: reviewCurrentScreen 传入 string_id 和不传有什么区别？

A: 不传 string_id 时，AI 通过 OCR 识别截图中的文字来匹配 string_id，可能出现相同文字匹配到错误 string_id 的问题。传入 string_id 后，SDK 从后端精确查询每个 string_id 的源文本和所有语言翻译，AI 直接使用这些精确映射进行分析，准确性更高。推荐使用传入 string_id 的方式。

Q: 游戏引擎（Unity）截图黑屏怎么办？

A: Unity 使用独立的 Surface 渲染（OpenGL ES/Vulkan），传统的 View.draw() 截图会黑屏。SDK 1.3.3+ 推荐使用外部截图模式：

// Unity 侧通过 RenderTexture 截图，得到 byte[]
LoxilyLocalize.reviewCurrentScreen(stringIds, imageBytes);

这种方式完全不依赖 Android 系统截图 API，也不需要 FOREGROUND_SERVICE_MEDIA_PROJECTION 权限，避免 Google Play 上架审核问题。

Q: suggestTranslation 调用后没有反应？

A: 请检查以下前提条件：

• SDK 已完成初始化（init() 回调返回成功）
• 已通过 updateUserInfo() 设置了 userId（未设置时 SDK 会打印日志并跳过）
• stringIds 不为空数组
• 当前有可用的 Activity（SDK 需要在前台 Activity 上打开共创界面）

Q: 点击气泡/触发截图审查时闪退（TransactionTooLargeException）？

A: 此问题已在 SDK 1.4.1 中修复。旧版本中截图的 Base64 数据通过 Intent 传递，高分辨率设备上数据量可能超过 Android Binder 事务的 ~500KB 限制，导致 TransactionTooLargeException。新版本改为通过临时文件传递截图数据，彻底规避了此限制。请升级至最新版本。

Q: 如何处理依赖冲突？

A: SDK 使用的类库包括 recyclerView、material、okhttp、gson、glide。如果遇到依赖冲突，可以在 build.gradle 中排除冲突的依赖：

dependencies {
  implementation('com.loxily:android-localize-sdk:1.3.3') {
    exclude group: 'com.squareup.okhttp3', module: 'okhttp'
    // 排除其他冲突的依赖
  }
}

Q: SDK 支持哪些 Android 版本？

A: SDK 支持 Android API Level 21 (Android 5.0) 及以上版本。