排查 SDK 初始化报错
解决 Unity Ads SDK 初始化期间可能出现的常见问题。
阅读时间1 分钟最后更新于 22 天前
当 Unity Ads SDK 无法正确初始化时，会发生这些错误。如果不成功初始化，则无法请求、加载或显示广告服务。使用此指南可以快速识别和修复初始化 Unity Ads SDK 时可能发生的问题。
Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52000] Unity Ads SDK 初始化失败：发生未知报错。
此报错消息表示由于未知或意外的内部报错，SDK 初始化失败。
Causes
报错的一个常见原因可能是 Unity Ads 服务器的临时后端问题。
Resolution
要解决此问题，请确认网络连接和游戏 ID 正确性，然后重试初始化。
如果报错仍然存在，请捕获详细日志并与 Unity 支持部门共享以供后端审查。您可能需要更新到最新版本的 Unity Ads SDK。
Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52001] Unity Ads SDK 初始化失败：无效游戏 ID：$gameId。在 Unity Ads Monetization（变现）后台中验证游戏 ID。
此报错消息表示 SDK 初始化失败，因为提供的游戏 ID 无效（不存在或非数字）或引用不正确。
Causes
报错的一个常见原因是使用不正确的游戏 ID，这可能出于以下一个或多个原因：
- 正在使用的无效/非数字游戏 ID
- 从后台复制或插入到代码中的游戏 ID 错误
- 从错误的项目中复制游戏 ID
- 在 Monetization（变现）后台中删除或存档的项目
Resolution
要解决此问题，请在 Monetization（变现）后台中验证游戏 ID，确保其与正确的项目匹配，并替换代码中的任何占位或非数字值。
如果刚在 Monetization（变现）后台中创建了项目，请等待几分钟进行后端同步。
Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52002] Unity Ads SDK 初始化失败：游戏 ID 不匹配。使用 Unity Ads Monetization（变现）后台中的目标平台的正确游戏 ID。
此报错消息表示 SDK 初始化失败，因为您传递的游戏 ID 与 app 运行的平台不匹配。
Causes
导致此报错的常见原因包括：
- 将 iOS 游戏 ID 传递给 Android 构建
- 将 Android 游戏 ID 传递给 iOS 构建
- 错误分配游戏 ID 或将其与 Monetization（变现）后台中的不同平台关联
- 从后台复制错误的游戏 ID 或将其插入代码
- 如果使用条件编译逻辑，无法在运行时选择平台指定的游戏 ID
Resolution
要解决此问题，请确保使用 Unity Ads Dashboard 中的正确 Android 或 iOS 游戏 ID，并确保代码在初始化期间有条件地选择正确的 ID。在调试日志中，确认 SDK 在 Android 和 iOS 之间检测到正确的平台。
Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52003] Unity Ads SDK 初始化失败：发生内部协议报错。稍后重试。
此报错消息表示 SDK 初始化失败，因为 SDK 向 Unity 服务器发送了请求，并收到了不完整或意外的响应。
Causes
导致此报错的常见原因包括：
- Unity 服务器的初始化响应的格式不正确
- 临时服务器问题
- 网络问题
Resolution
要解决此问题，请确保连接稳定，稍后重试初始化。
如果报错可重现，请启用日志以捕获 HTTP 响应并向 Unity 支持部门报告以供后端审查。
Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52004] Unity Ads SDK 初始化失败：发生系统报错。稍后重试。
此报错消息表示 SDK 初始化失败，因为设备遇到阻止 SDK 完成启动的内部系统级别问题。
Causes
导致此报错的常见原因包括：
- SDK 无法读取或写入所需的文件或系统信息
- 设备在初始化期间耗尽了可用存储空间或内存
- SDK 在创建其本本地缓存或文件夹遇到读取或写入报错
Resolution
要解决此问题，请确保 app 具有必要的权限和足够的设备存储空间，然后在重新启动后再次尝试初始化。
如果报错仍然存在，请清除 app 的缓存以删除损坏的本地 SDK 数据。
Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52005] Unity Ads SDK 初始化失败：发生网络报错。稍后重试。
此报错消息表示 SDK 初始化失败，因为 SDK 由于网络连接问题而无法与 Unity 服务器成功通信。
Causes
导致此报错的常见原因包括：
- 无互联网连接（或设备离线或处于飞机模式）
- 信号不稳定或连接薄弱
- VPN 可能阻挡 Unity Ads 域
- 设备无法解析或到达 Unity Ads 终端
Resolution
要解决此问题，请确保设备具有稳定的互联网连接，避免使用限制性防火墙或 VPN，并在验证连接后重试初始化。
如果报错仍然存在，请捕获日志以查看指定的 HTTP 代码是否重复（例如，、）。
-1009-1022Symptoms
尝试初始化 Unity Ads SDK 时，返回以下报错消息：
[52006] Unity Ads SDK 初始化失败：设备上的存储空间不足。释放空间，然后重试。
此报错消息表示 SDK 初始化失败，因为设备没有足够的可用存储空间让 Unity Ads SDK 在初始化期间创建或写入必要的本地文件来存储配置数据、缓存资源和日志。
Causes
导致此报错的常见原因包括：
- 设备的可用存储空间为零或很低
- app 分配的缓存或数据目录已满
- 持久缓存累积（旧日志、缓存资源或未清除的临时数据）
Resolution
要解决此问题，请通过清除磁盘空间（通过删除未使用的应用程序、媒体或文件）来释放设备存储空间，必要时从设备设置中清除 app 的缓存以删除旧的 SDK 数据，然后尝试再次初始化 SDK。