入门

概述

OZero Security 通过在一般黑客工具难以访问的 Native C++ 层执行安全逻辑来保护 Unity 游戏。只需在 Unity 编辑器内的仪表板中激活模块，即可运行核心保护功能。无需场景设置或编写额外代码。

1 导入包

打开 Unity 编辑器并导入 OZero Security 包。您可以通过 Unity 包管理器或双击 .unitypackage 文件进行导入。

当出现 Import Unity Package 对话框时，在勾选所有项目的情况下点击 Import。所需的脚本、原生插件和编辑器工具将自动添加。

2 打开仪表板

导入完成后，从 Unity 菜单栏打开 Config Dashboard：

打开 Config Dashboard 后，可以在此屏幕上一次性管理预设、安全模块、许可证和构建完整性设置。无需在 Project 窗口中直接查找并修改文件。

Unity 编辑器菜单说明

OZeroSecurity 将设置窗口放在 Window > OZero Security，将诊断和 bake 命令放在 Tools > OZero Security。安全预设会在 Config & Dashboard 中应用，方便您在保存前确认实际变更的设置。

3 激活模块

在仪表板内可以查看安全模块列表及切换开关。请激活您要使用的模块。以下是推荐的初始配置。

选择安全预设

首先选择一个预设，然后根据项目进行个别模块调整。对于一般的实时在线游戏，建议从 Standard 开始。这能在保护级别、性能和误报率之间取得最佳平衡。

只需在仪表板中开启要使用的模块并保存 OZeroSecurityConfig 资产即可。播放器启动时，SDK 会自动准备已激活的模块。

许可模式 — Standard / Pro

Standard无需服务器集成即可提供本地防护。Pro将项目专属原生二进制文件（Native Variant）和清单绑定与遥测、签名时间、远程安全配置、证明和服务器验证结合。

注册Pro许可密钥

Standard无需单独配置许可。Pro需要在Unity中创建OZeroLicenseConfig资源并输入项目密钥，用于专属Variant绑定、运行时激活和服务器功能。

1. 创建设置资产

从 Unity 顶部菜单打开 Window → OZero Security → Config & Dashboard。在 License & Server 区域点击 Create OZeroLicenseConfig 按钮。该按钮会把 OZeroLicenseConfig 资产自动创建到正确的 Resources/ 文件夹中，因此不需要手动创建文件夹或移动资产。

2. 填写 Inspector 字段

3. 构建与验证

不需要额外编写代码。应用启动时，SDK 会自动读取 OZeroLicenseConfig 资产。首次运行后，请在 Player 日志中确认是否出现类似 [OZeroLicense] activated; tier=pro caps=5 的行。如果已设置为 Pro 但日志显示 Standard 模式，请先确认资产的位置和名称。资产必须位于 Resources/ 文件夹下，名称必须正好是 OZeroLicenseConfig。

离线操作

先看结论：网络断开不会停止游戏或本地保护。Standard 原本就不使用服务器，Pro 也保留相同的离线本地保护。只有明确选择的服务器功能可在一定时间内使用已保存的激活信息。

Standard — 无需互联网即可启动

Standard 不会向服务器请求许可。它只运行应用内置的本地保护模块，所以玩家离线时游戏也能启动。只有遥测、signed time 等需要 Pro 服务器的功能不可用。

Pro — 本地保护保持离线，所选服务器功能使用缓存

启用可选的 Pro 服务器功能后，SDK 会在联网时确认设备和许可证。所选服务器功能可在有限时间内容忍短暂断网。此检查不会限制使用已获取 Native Variant 的构建或本地保护。

tokenTtlSeconds 是已保存服务器功能结果的有效期，默认值为 604800 秒，即 7 天。离线过期后，只有遥测上传、signed-time 验证等依赖服务器的功能在下次成功激活前不可用。游戏、已获取的 Native Variant 和本地检测器保持不变；SDK 不会静默地把产品层级切换为 Standard。

Pro — 门户中阻止的版本离线也会被阻止

临时服务器或网络问题下继续以基础保护启动，和允许运营人员在门户中明确阻止的版本运行，是两件不同的事。Pro 激活成功时，服务器会同时下发带签名的阻止列表，例如被阻止的构建哈希、SDK 版本和应用版本。SDK 会将该策略与临时服务器功能状态分开处理。

请在 Config Dashboard 的 License & Server 区域通过 OZeroLicenseConfig.offlineProPolicyMode 配置此行为。它决定设备无法连接服务器时，本地 Build Integrity 如何处理最后一次收到的已签名 Pro 门户阻止策略。

总结来说，ApplyCachedBlockPolicies 是运营默认的 fail-open 模式，RequireFreshPolicy 是 fail-closed 策略模式，IgnoreCachedBlockPolicies 是测试用 bypass。如果每次验证都必须要求在线服务器确认，请不要只依赖此选项，还要同时配置服务器 Integrity 或 Managed Verification 的必需选项。

许可证问题解决

出现问题时，请先在 Unity Player 日志中搜索 [OZeroLicense]。这个日志会告诉你 SDK 是以 Standard 启动，还是 Pro 激活成功；如果失败，也会说明为什么降级到 Standard。安全事件上传问题则同时搜索 [OZeroTelemetry]。

项目设置

在调整各个安全模块之前，请先检查影响原生插件、商店构建和平台验证的 Unity Player Settings。

最低构建目标

发布构建的安全与体积优化设置建议

发布最终版本时，OZero 建议使用以下 Unity 设置来增强构建安全性并减少应用体积。

安全强化（IL2CPP 设置）：在 Android、iOS 等 Unity 支持的环境中，请将脚本后端设置为 IL2CPP。IL2CPP 不能完全阻止逆向分析，但可以减少 C# 代码和元数据的直接暴露范围，并帮助 OZero 安全检查在更稳固的发布环境中运行。路径：Project Settings > Player > Other Settings > Scripting Backend

体积优化（Managed Stripping 设置）：Managed Stripping 会移除未使用的 managed code，从而减少应用体积。如果一开始移除过多代码，应用可能在运行时出错，因此建议先从 Low 或 Medium 开始。

注意事项：修改设置后，请先在真实设备上测试场景切换、数据保存、Addressables，以及支付/广告等外部 SDK 是否正常工作，再提高 stripping level。

Android ProGuard / R8 设置

OZero Security 不需要单独的 Java SDK 包。但是，如果您的 Android 部署版本启用了 Minify、ProGuard 或 R8，则必须保留 Unity Java 桥接以及项目中使用的自定义 Android 桥接类。这样才能确保获取包信息、安装来源、APK 签名证书检查和启动资产加载所需的 JNI 调用在混淆后依然稳定运行。

# OZero Security - Unity Android ProGuard/R8 keep rules
-keep class com.unity3d.player.UnityPlayer { *; }
-keep class com.unity3d.player.UnityPlayerActivity { *; }
-keep class com.unity3d.player.UnityPlayerGameActivity { *; }
-keep class com.unity3d.player.UnityPlayerForActivityOrService { *; }
-keepattributes *Annotation*,InnerClasses,EnclosingMethod,Signature

# If your game adds custom Java/Kotlin bridge classes that OZero or your code
# calls through AndroidJavaClass / AndroidJavaObject, keep those classes too.
# Replace the package below with your own bridge package.
# -keep class com.yourcompany.yourgame.bridge.** { *; }

• 不要重命名、删除或重新打包 libOZeroSecurity.so。将插件保留在 Assets/OZeroSDK/Plugins/Android/arm64-v8a 下。如果您要分发 32 位版本，也请保留 armeabi-v7a。
• 如果您使用 Build Integrity > Check Platform Native 和 Android SHA Keys，请务必在应用 Minify/R8 后，使用最终签名的 APK 或 AAB 进行测试。调试密钥库的指纹与发布密钥库的指纹是不同的。
• 如果只有在开启 Minify 之后，Android 日志中才出现 JNI 查找失败、安装来源检测失败或 APK 签名检查结果为空的情况，请先检查您的自定义桥接的 keep 规则。
• 对于商店分发的构建版本，请基于 IL2CPP、Release 签名、Android Sha Keys 中注册的预期 Android SHA-256 指纹，并在至少一台真机上进行干净运行测试后再做判断。

5 OZeroSecurityConfig 设置

OZeroSecurityConfig ScriptableObject 资产会在包导入时包含。在 Project 窗口中选择它即可查看并调整所有安全模块设置。在运行时通过 OZeroSecurityConfig.Instance 进行访问。

通用设置

这些是所有安全模块共享的顶级设置。本表中的默认值以代码中定义的序列化初始值为准。

Managed UI（所有许可证）

Security Termination Notice、通用 dialog prefab 与 localization 对 Standard / Pro 全部开放。Pro 还显示 Build Integrity 与 Steam DRM 的 Managed Verification 重试、timeout 和 provider 设置。导入 optional package 前，请先从 Package Manager 安装 Unity UI 与 TextMeshPro。提示仅说明已经安排的终止，不能取消退出或延长 native deadline。

Global Threat Response

决定确认安全威胁后游戏的响应方式。在测试期间请先检查回调和日志，在实际部署构建中请根据项目的运营策略选择给玩家的提示时间和终止策略。

接入问题自查指南

如果启用 OZero Security 后应用退出，或只在特定环境中出现问题，请先通过本地诊断文件确认是哪个模块触发。不要先凭感觉修改设置，而是根据文件中的 module、subCode、reason 按下面的表逐步排查。

应用反复退出时先做什么

常见诊断字段

常见症状和第一步检查

构建完整性验证器设置

配置构建完整性检查器，以检测被修改的游戏文件、调试器连接以及异常的运行环境。

生成 RSA 签名密钥（Build Integrity Manifest）

Build Integrity 可以为构建时生成的 manifest 添加 RSA 签名。该 manifest 包含运行时要验证的 assembly hash 与文件完整性信息。对于发布构建，如果 manifest 本身被替换，验证基准就不再可信，因此发布前请在 Window > OZero Security > Config & Dashboard 中点击 Generate Key Pair 生成 manifest 签名密钥对。

为什么需要 Manifest 签名

构建时，OZero 会使用私钥为 manifest 签名。私钥不会包含在 player build 中，构建中只包含存储在 OZeroSecurityConfig 里的公钥。运行时，SDK 会用公钥确认 manifest 签名。如果签名有效，SDK 会认为“构建时生成的 manifest 仍保持原样”，并以该 manifest 作为 assembly/file hash 检查的可信基准。如果签名缺失或不匹配，则 manifest 可能已被替换或编辑，因此 Build Integrity 会将其视作失败。之后的处理会按照 Response Settings 执行，例如记录日志、触发回调或关闭应用。

生成密钥对

1. 在 Unity 编辑器中打开 Window > OZero Security > Config & Dashboard。
2. 在检查器 (Inspector) 中展开 Build Integrity 选项卡。
3. 勾选 Require Manifest Signature 复选框。
4. 点击 Generate Key Pair 按钮。
5. OZero 会生成用于 Build Integrity manifest signing 的密钥对。公钥存储在 OZeroSecurityConfig 中，私钥 默认保存在以下路径：
   [ProjectRoot]/OZeroSigningKeys/manifest_private_key.pem
6. 将显示指示私钥位置的确认对话框。点击 OK 关闭它。

重要提示 — 私钥安全

• 私钥文件存储在 Assets/ 文件夹 外部，以防止 Unity 将其打包进构建中。切勿将其移入 Assets/ 中。
• 请将 OZeroSigningKeys/ 从版本控制中排除。使用 Git 时加入 .gitignore，使用 SVN 时加入 svn:ignore。将私钥提交到仓库是严重的安全风险。
• 请将私钥备份到安全位置。任何拥有此文件的人都可以为该项目创建有效的 Build Integrity manifest。
• 如果丢失私钥，已发布的旧构建仍会继续运行。但是下一次更新构建无法再用旧密钥签署新的 manifest。请生成新的密钥对，重新生成 integrity manifest，并通过 clean build 发布更新。公钥、fingerprint、manifest 和 signature 必须互相匹配，否则 Build Integrity 验证可能失败。

自定义私钥路径（CI/CD 和团队环境）

Manifest Signing Private Key Path 字段不是用来选择 Generate Key Pair 生成新密钥的位置。它用于告诉构建和验证工具从哪里读取 PEM 私钥。Generate Key Pair 会在项目默认路径生成密钥，并把该路径记录到 Config 中。对于 CI/CD 或团队构建，请先把同一个 PEM 还原到安全路径，再让此字段指向该路径。

• CI/CD 管道 — 将 PEM 保存为 CI Secret，并在 Unity 构建前还原。构建 runner 不需要长期把私钥保存在磁盘上。
• 团队环境 — 使用只有发布构建负责人或构建 runner 可访问的安全挂载路径或 Secret Manager。所有发布构建机器都必须使用同一个 PEM。

验证现有密钥对

如果要确认磁盘上的私钥是否与 OZeroSecurityConfig 中保存的公钥一致，请点击 Validate Key Pair。OZero 会从 PEM 重新推导公钥，并与 Config 中的公钥比较。如果不匹配，请还原对应的私钥，或生成新的密钥对，然后进行 clean build。

何时应重新生成密钥对

• 当私钥丢失或泄露时。
• Validate Key Pair 报告不匹配（密钥未同步）时。
• 作为既定安全策略的一部分，有意轮换密钥时。

重新生成后，已经发布的旧构建仍会使用自身内置的密钥和 manifest 继续运行。下一次更新构建必须让新的公钥、fingerprint、manifest 和 signature 作为同一套匹配数据使用。请重新生成 integrity manifest，并通过 clean build 发布。

双指纹密钥轮换

点击 Generate Key Pair 按钮后，公钥会保存在 OZeroSecurityConfig 中，同时识别该密钥的 fingerprint 也会记录在 Assets/OZeroSDK/Scripts/Security/BuildIntegrity/OZeroManifestTrustAnchor.cs 中。运行时 SDK 会先确认 asset 中的公钥是否匹配受信任的 fingerprint，然后才接受已签名的 manifest。

当前密钥与旧密钥

ExpectedPublicKeyFingerprintHex 是当前构建使用的密钥 fingerprint。PreviousPublicKeyFingerprintHex 是只在密钥轮换期间使用的辅助槽位。它不能替代 manifest 重新生成，也不是服务端密钥管理功能。OZeroSecurityConfig 中的公钥、fingerprint、manifest 和 signature 仍然必须基于同一把密钥组成一套匹配数据。

安全的密钥轮换步骤

1. 备份当前指纹。 打开 Assets/OZeroSDK/Scripts/Security/BuildIntegrity/OZeroManifestTrustAnchor.cs，将 ExpectedPublicKeyFingerprintHex 的值复制到临时记录中。
2. 注册到旧密钥槽。 在同一文件中，将第 1 步复制的值粘贴到 PreviousPublicKeyFingerprintHex 中并保存。
3. 生成新的密钥对。 打开 Window > OZero Security > Config & Dashboard，在 Build Integrity 区域点击 Generate Key Pair。新的公钥和 Expected fingerprint 会自动更新。请保留第 2 步写入的 Previous 值。
4. 重新生成 integrity manifest，并制作 clean build。 新的 manifest 和 signature 必须基于新的私钥生成。
5. 保留更新过渡期。 已发布的旧构建会继续使用自身内置的密钥和 manifest 运行。Previous 槽位是在新构建发布过程中减少回滚或构建产物混用问题的安全措施。对于在线运营游戏，通常可以按 1 到 4 周作为参考。
6. 清空旧密钥槽。 当旧版本的使用量足够低后，将代码改回 PreviousPublicKeyFingerprintHex = ""，再次发布后轮换即告完成。

Previous 槽位的作用

已经发布的旧构建不需要知道新密钥也能继续运行，因为旧构建中已经包含当时的公钥、fingerprint、manifest 和 signature。Previous 槽位是在新的发布线中进行受控密钥轮换时使用的安全措施。只在需要过渡时保留，之后的版本中建议清空。

故障排除

遇到问题时，先按简单顺序检查：没有密钥就执行 Generate Key Pair，已有密钥就执行 Validate Key Pair，然后重新生成 integrity manifest 并制作 clean build。大多数问题来自以下四项之一不同步：私钥 PEM、OZeroSecurityConfig 中的公钥、OZeroManifestTrustAnchor 中的 fingerprint、生成出的 manifest/signature 文件。

症状 1 — 部署构建在运行后立即退出

ExpectedPublicKeyFingerprintHex 可能为空。发布构建在缺少 fingerprint 时会为了安全直接失败。解决：执行 Generate Key Pair，等待 Unity 重新编译完成后制作 clean build。如果该值已经存在，请执行 Validate Key Pair，并清空构建输出文件夹后重新构建。

症状 2 — 构建刚开始前就提示 "no manifest signing public key is configured" 并中断

当 OZeroSecurityConfig.Integrity.ManifestSigningPublicKey 为空时触发。解决：打开 Window > OZero Security > Config & Dashboard，在 Build Integrity 区域点击 Generate Key Pair，然后重新构建。

症状 3 — 运行时日志："Manifest signing public key does NOT match the pinned trust anchor fingerprint — APK appears to have been repacked with attacker-controlled keys"

当 OZeroSecurityConfig 的公钥与 OZeroManifestTrustAnchor 中记录的 fingerprint 不一致时发生。只还原了密钥对的一部分，或手动修改了生成文件时经常出现。解决：执行 Validate Key Pair。如果报告不一致，请还原匹配的 PEM，或生成新的密钥对，然后重新生成 integrity manifest 并制作 clean build。如果只有已发布构建出现此消息，也请确认 APK 或可执行文件是否被重新打包。

症状 4 — 密钥轮换后新构建的 manifest 验证失败

轮换后的密钥数据中可能有一部分仍是旧值。请确认公钥、fingerprint、manifest、signature 是否都基于同一把密钥。解决：只有在需要过渡期时才把旧 fingerprint 保留在 PreviousPublicKeyFingerprintHex，然后依次执行 Validate Key Pair、重新生成 integrity manifest、清理构建输出文件夹、重新进行 clean build。

症状 5 — 本地构建成功，但 CI 构建时提示 "private key not found" 或使用错误的密钥签名

CI 不会自动拥有本地 PC 上的 OZeroSigningKeys/manifest_private_key.pem 文件。解决：将 PEM 保存在 CI Secret 中，并在 Unity 构建前还原到默认路径，或还原到 Manifest Signing Private Key Path 指定的路径。所有发布 runner 都必须使用同一个 PEM，并建议在发布环境中执行一次 Validate Key Pair 进行确认。

安装来源设置

限制游戏仅在通过已批准的商店或途径安装时才能运行。这有助于防止侧载或重新打包的 APK。

Steam 防盗版配置

对在 Steam 发售的 PC 端查明 Steam 调用通道、App ID、权限情况、发布档设定。Standard 是局端核实，要想通过 Steam 取得牢固权证唯有依赖 Pro 级别之内的 Steam Attestation 来供给。

设备绑定设置

保存首次信任设备的识别信息，并在后续启动时与当前设备进行比较。可用于发现同一账号或受保护存档是否被移动到其他设备。

运营中的使用方式

在 Pro 中，Device Binding 可以作为运营工具使用。服务器会记录每个许可证对应的设备指纹，因此可以阻断反复出现风险信号的设备，减少简单的许可证共享，并在不禁用整个许可证的情况下支持合法的设备更换。

Reset Token 支持流程

1. 先通过正常客服流程确认玩家账号，以及为什么需要重置设备。
2. 进入 Customer Portal → Device Binding，选择目标设备并发放 Reset Token。
3. 令牌只能通过已认证的支持渠道发送。不要留在公开聊天、截图或长期保存的工单中。
4. 游戏或支持用 UI 应将令牌传递给 OZeroDeviceBindingDetector.Instance?.ClearStoredFingerprint(token.Trim())。
5. SDK 接受令牌后，重启应用或再次运行受保护的启动流程，当前设备指纹就会重新注册。

Speed & Time Hack 设置

对比 Unity 时间、原生基准时钟、后台计时器以及 Web/Pro 服务器时间，用来检测加速或减速游戏的操控，以及设备时钟变化。

使用 OZeroTime.timeScale，而不是 Time.timeScale

启用 Speed & Time Hack 保护模块时，项目代码不得直接修改 Unity 内置的 Time.timeScale。如果绕过 OZero 直接修改，OZero detector 可能会将其视为外部作弊工具造成的可疑运行时时间篡改，并执行已配置的响应策略。

OZeroSecurityConfig.TimeScaleTamperExemptions 是用于登记仍需直接访问 Time.timeScale 的脚本的例外列表。请尽量保持该列表最小化。

仅在现有结构无法避免直接访问 Time.timeScale 时，将例外限制分配给已验证的第三方插件或 legacy adapter script。

除此之外，项目中的所有游戏逻辑都应无例外地优先使用 OZeroTime.timeScale。暂停、慢动作、过场速度控制、倍速播放等游戏内有意变速场景，都必须使用 OZeroTime.timeScale。

using OZeroSDK.Security;

// Correct: the detector knows this is an intentional game-side change.
OZeroTime.timeScale = 0.5f;

// Avoid: this bypasses OZero's expected time-scale tracking.
Time.timeScale = 0.5f;

防止长时间加载时 Watchdog 意外终止应用

OZero 的原生 Watchdog 通过周期性的 heartbeat 确认 Unity 主线程仍在运行。发布版中 heartbeat 期限在所有平台上约为 10 秒(启动宽限期之后)。超过期限时，Watchdog 先查看主线程在做什么：线程被阻塞且不消耗 CPU 的状态(长时间同步加载、日志刷写、磁盘 I/O、虚拟机暂停线程)视为停顿，仅记录；游戏仍在运行却不再发送 heartbeat 则视为篡改，按配置的响应策略终止。停顿超过五分钟的进程按无响应关闭。

大型场景加载、同步资源解压、shader warmup 或 Addressables 准备等正当工作，也可能因为主线程被有意阻塞数秒而触发这种情况。

请使用 OZeroWatchdog.BeginLoadingGrace(maxGraceMs) 包住这类可信加载边界。加载开始时 grace 开始，scope 被 dispose 或调用 End() 时会立即结束，因此不需要提前知道准确的加载时长。

using OZeroSDK.Security;
using UnityEngine.SceneManagement;

public void LoadLargeScene()
{
    using (OZeroWatchdog.BeginLoadingGrace(60000))
    {
        SceneManager.LoadScene("Battle", LoadSceneMode.Single);
        // Grace ends as soon as the using scope exits.
    }
}

public void WarmUpLargeAssets()
{
    OZeroWatchdog.RunWithLoadingGrace(() =>
    {
        BuildLargeRuntimeCache();
    }, 60000);
}

物理黑客检测器

注入检测器设置

检测进入运行中游戏的程序：被注入的原生模块、可执行私有内存、内联挂钩、远程线程式注入、高风险进程句柄以及 WebGL 运行时篡改。正常的覆盖层和录制工具也以同样方式进入游戏，因此检测器通过文件哈希和签名者识别每个模块，并允许逐个模块做出判定。

检测器如何识别模块

检测器每隔几秒遍历游戏进程中加载的全部模块，并与启动时的集合比较。新模块通过文件哈希识别，在 Windows 和 macOS 上还通过签名证书指纹识别。规则只看模块本身而不看安装目录名称，因此正常程序不会因安装路径而被误判。

每次检查按检测族返回三种结果之一：已检测、扫描后正常或尚未到检查时间。只有真实样本才会改变计数；未执行的检查不会清除先前的检测，完全无法执行的检查会作为扫描器健康问题上报，而不是正常结果。

Pro：在门户中允许或阻止检测到的模块

开启 enableServerWhitelist 后，Pro 构建在启动时以及每个 serverWhitelistRefreshInterval 下载一份签名判定列表。该列表合并了团队在客户门户(注入 → 检测状态 → 检测到的模块)中做出的判定与 OZero 基于全部客户数据的判定。

• 列表绑定到您的许可证，并使用许可证服务器密钥(Ed25519)签名。SDK 用其在激活时已信任的同一公钥进行验证。
• 验证过的列表保存在设备上，离线启动时同样生效。验证失败的列表不会被接受，检测本身也绝不会关闭。
• 从未连接过的设备只使用构建中自带的基线信任列表。之后的刷新连上服务器时，会获取并缓存列表。
• 当 OZero 阻止了您项目允许的模块时，门户中的当 OZero 与本项目判定不一致时设置决定以谁为准(默认：OZero)。您项目阻止的模块始终被阻止。
• ABI 21 SDK 还会上报 Windows 和 macOS 模块的代码签名主体(例如 Discord Inc.)，门户可在证书指纹旁显示公司名。iOS 和 Android 模块没有可读的签名者。
• 检测器已发现但尚未处理的模块会以来源 决定前已发现 进入门户的 已观测模块 列表，您可以在任何玩家受影响之前允许或阻止。设备上证书链验证通过的模块显示为 可信签名，此类模块不会被 identity 规则自动关闭，而是等待您的决定。

扫描器不可用(abort code 0x15)

若原生扫描器本身无法运行(配置应用失败、原生扫描反复出错，或 managed/native 契约不一致)，SDK 会上报 ModulationType.InjectionScannerUnavailable(值 10，abort code 0x15，message key injection_scanner_unavailable)，即使关闭了 ForceQuitOnDetection 也会关闭游戏。这不是攻击检测，而是防止悄然损坏的扫描器让游戏失去保护。请向玩家显示 OZ-SEC-15 等支持代码，并在日志中保留 abort code。

PlayerPrefs 加密

对于需要保护的新 key，请使用 OZeroSafePlayerPrefs，而不是 Unity 的 PlayerPrefs。常见的 Get/Set、HasKey、Delete、Save 方法名保持熟悉的形式，但加密数据与已有的普通 PlayerPrefs 数据不兼容。

using OZeroSDK.Security;

// Save a value
OZeroSafePlayerPrefs.SetInt("score", 4200);
OZeroSafePlayerPrefs.SetFloat("volume", 0.8f);
OZeroSafePlayerPrefs.SetString("username", "Hero");

// Read a value
int    score    = OZeroSafePlayerPrefs.GetInt("score", 0);
float  volume   = OZeroSafePlayerPrefs.GetFloat("volume", 1.0f);
string username = OZeroSafePlayerPrefs.GetString("username", "");

存档文件加密

要加密存档文件，请使用 OZeroSV_File 代替 File.ReadAllText / File.WriteAllText。文件在写入时自动加密，在读取时自动解密。加载时还会检查是否被篡改。

using OZeroSDK.Security;

string path = Application.persistentDataPath + "/save.json";

// Write encrypted file
OZeroSV_File.WriteAllText(path, jsonString);

// Read and decrypt file
string json = OZeroSV_File.ReadAllText(path);

4 游戏内变量保护（Secure Types）

Secure Types 会将常规 C# 变量类型替换为加密类型。因为值存储在 Native C++ 堆中，诸如 Cheat Engine 的工具即使扫描内存也无法找到。只需更改类型名称，其余代码即可照常运行。

示例代码

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using OZeroSDK.Security;

public class PlayerStats : MonoBehaviour
{
    [SerializeField] OZeroSV_Int Gold = 5000;
    [SerializeField] OZeroSV_Float Speed = 3.5f;
    [SerializeField] OZeroSV_Int HP = 1000;
}

支持类型

7 安全事件处理（可选）

默认情况下，当 OZero 检测到威胁时，它会按照配置的响应策略来终止应用或只留存日志。如果您需要直接显示警告屏幕、发送您自己的服务器日志或在退出之前执行保存操作，则可以注册回调。该回调将通过 OZeroSecurityEvent 提供修改类型、中止代码、消息键、详细消息以及是否即将退出等信息。

using UnityEngine;
using OZeroSDK.Security;

public class SecurityHandler : MonoBehaviour
{
    void OnEnable()
    {
        // RegisterUserCallback runs on the user chain only.
        // The built-in default handler runs independently and cannot be silenced.
        OZeroSecurityManager.Instance.RegisterUserCallback(OnThreatDetected);
    }

    void OnDisable()
    {
        OZeroSecurityManager.Instance.UnregisterUserCallback(OnThreatDetected);
    }

    void OnThreatDetected(OZeroSecurityEvent evt)
    {
        // evt contains Type, AbortCode, AbortCodeHex, MessageKey, Message, and WillAbort.
        Debug.LogWarning(
            $"OZero threat: {evt.Type} {evt.AbortCodeHex} {evt.Message}");

        switch (evt.Type)
        {
            case ModulationType.SpeedHack:
                // e.g. kick the player, show warning, report to server
                break;

            case ModulationType.BuildIntegrity:
                // evt.WillAbort is usually true for fatal build integrity violations.
                break;

            case ModulationType.Injection:
                break;
        }

        if (evt.WillAbort)
        {
            // Last chance to flush your own analytics or save state.
        }
    }
}

OZeroSecurityEvent、ModulationType 以及 OZeroAbortCode 的完整列表已记录在 API 参考中。

门户策略回调

Customer Portal 策略可以分阶段运营。Observe 只记录证据，Callback 将服务器下发的 policy action 传递给游戏，Device Block 会在后续服务器验证中阻止选中的设备。在使用更强的设备封禁之前，如需由游戏显示警告、限制匹配、要求重新登录或引导玩家联系支持，请使用 Callback。

using UnityEngine;
using OZeroSDK.Security;

public class PolicyActionHandler : MonoBehaviour
{
    void OnEnable()
    {
        OZeroSecurityManager.Instance.RegisterUserPolicyActionCallback(OnPolicyAction);
    }

    void OnDisable()
    {
        OZeroSecurityManager.Instance.UnregisterUserPolicyActionCallback(OnPolicyAction);
    }

    void OnPolicyAction(OZeroPolicyActionEvent evt)
    {
        Debug.LogWarning(
            $"Policy callback: {evt.Module}, score={evt.Score}, reason={evt.Reason}");

        if (evt.Score >= 80)
        {
            // Show your own UI, limit sensitive actions, or ask the player to reconnect.
        }
    }
}

下一步

现在 OZero 的核心防线已经在为您保驾护航了。翻查文档，全面探究每个接口，类、或控制选项的真谛。

故障排除参考

Use this section when an OZero dialog appears, a security log is reported, or the app closes for a security reason. Start with the code shown on screen or in the log, then follow the first checks below.

Support Codes

Support codes are short labels shown in OZero dialogs and logs. When a player sends this code to support, the development or QA team can quickly identify which broad area to check. OZ-SEC-* means a security event was reported, and OZ-MV-* means an online or managed verification state needs attention.

Abort Codes

Abort codes are stable categories used in logs, callbacks, and OZ-SEC-* support codes. They tell the development team which protection area responded without exposing detailed evidence to the player.

For API fields and callback examples, see OZeroAbortCode & Event Messages.

解决流程