入门

概述

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 / Plus / Pro

OZero Security 提供 Standard、Plus、Pro 三种等级。Standard 模式不与服务器联动，仅使用本地保护功能。Plus 模式在此基础上加入了各项目特定的 Native Variant 包及清单 / Bundle ID 绑定。Pro 模式包含 Plus 的配置，并增加了遥测、签名验证的服务器时间、远程策略、服务器校验以及设备限制等运营功能。

Plus / Pro 许可证密钥注册

Standard 不需要单独的许可证设置即可使用。使用 Plus 或 Pro 时，请在 Unity 中创建 OZeroLicenseConfig 资产，并输入为项目签发的许可证密钥。Plus 密钥用于从门户下载项目专用 Native Variant 包，并在构建时确认该包属于当前项目。Pro 密钥还用于运行时服务器激活和 Pro 专用服务器功能。

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。

服务器激活流程

Pro 许可证会在应用启动时由 SDK 自动检查。该过程设计为不会阻塞游戏启动流程。如果服务器响应较慢或网络暂时不可用，SDK 会先检查保存的激活信息；如果该信息仍可使用，就继续运行。

引导序列

1. SDK 会在应用启动时自动初始化许可证运行时。
2. Standard 和 Plus 不需要运行时服务器激活，因此会立即启动本地保护功能。
3. 配置可选的 Pro 服务器功能后，SDK 会在后台发送 /v1/activate 请求，以检查当前许可证和设备状态。
4. 激活成功后，可以使用遥测、签名服务器时间(signed time)、构建证明(attestation) 等 Pro 服务器功能。
5. 如果发生服务器维护、临时网络错误或超时，SDK 会尽可能使用已保存的激活信息。如果没有可用的保存信息，或许可证已过期、暂停、撤销，则只有已选择的 Pro 服务器功能会不可用或受限。已获取的 Native Variant 和本地保护保持不变。

传输的信息

激活请求是一个小型 JSON POST。基本请求包含 licenseKey、deviceId、sdkVersion 和 platform。当 Unity 能提供值时，也会发送 appIdentifier、companyName、productName 和 webglOrigin。deviceId 默认使用 Unity 设备标识符；如有需要，可以通过 OZeroLicenseRuntime.DeviceIdProvider 改为游戏账号 ID 或自定义 UUID。

POST https://api.ozerosecurity.com/v1/activate
Content-Type: application/json

{
  "licenseKey":    "OZ-PRO-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX",
  "deviceId":      "<DeviceIdProvider result; default SystemInfo.deviceUniqueIdentifier>",
  "sdkVersion":    "<OZeroSdkVersion.ManagedVersion>",
  "platform":      "<android | ios | windows | macos | linux | webgl | ...>",
  "appIdentifier": "<Application.identifier>",
  "companyName":   "<Application.companyName>",
  "productName":   "<Application.productName>",
  "webglOrigin":   "<WebGL origin only>"
}

服务器会返回签名令牌、确定的层级、可用功能列表、服务器功能启用状态、令牌过期时间，以及服务器不可达时的处理策略。SDK 会使用配置的公钥验证签名令牌，然后才信任 Pro 功能。

无法使用服务器功能时

服务器维护、网络超时、许可证过期/暂停/撤销、Bundle ID 不匹配不会立即被视为篡改。这种情况下只有已选择的 Pro 服务器功能会不可用或受限，已获取的 Native Variant 和本地保护保持不变。相反，构建不匹配、被阻止的构建、注入、调试器等明确篡改状态会按照配置的响应策略处理。

离线操作

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

Standard — 无需互联网即可启动

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

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

启用可选的 Pro 服务器功能后，SDK 会在联网时通过 /v1/activate 确认设备和许可证，并把结果加密保存到 PlayerPrefs，使所选服务器功能能够容忍短暂断网。此激活不会限制使用已获取 Native Variant 的构建或本地保护。

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

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

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

使用推荐的 ApplyCachedBlockPolicies 模式时，只要保存的阻止列表仍然有效，即使玩家开启飞行模式，Build Integrity 也会拒绝被阻止的版本。你在门户中修改阻止规则后，每台设备都需要成功在线激活一次，才能取得新规则。

故障排除

出现问题时，请先在 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 进行访问。

通用设置

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

验证用 UI 管理

Pro Only 功能。配置 Build Integrity 和 Steam DRM 等流程中使用的在线重新验证、网络重试以及阻止/退出提示对话框。导入 optional OZero TMP dialog package 前，请先通过 Package Manager 安装 Unity UI 和 TextMeshPro。Unity 6 的 TextMeshPro 已包含在 Unity UI 2.x 中。不使用 TextMeshPro 的项目请使用 Custom UI / Callback Only。

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 主线程是否仍在正常运行。在发布构建中，非 Android 平台大约使用 6 秒 heartbeat deadline，Android 在启动宽限后大约使用 10 秒 deadline。如果在该时间内没有收到 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);
}

物理黑客检测器

注入检测器设置

检测异常的原生模块加载、可执行 private memory、inline hook、remote-thread 类型注入、高风险外部进程 handle，以及 WebGL 运行时篡改信号。

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 的核心防线已经在为您保驾护航了。翻查文档，全面探究每个接口，类、或控制选项的真谛。