API 参考

OZeroSecurityManager OZeroSDK.Security

管理所有活动安全模块和安全事件的全局管理器。即使场景切换它也会保持存在，并且可以通过 Instance 属性进行访问。SDK 会在应用启动时自动创建，因此您无需直接进行实例化。

特性

方法

当项目代码需要接收安全事件时注册回调。OZero 的内置响应会在独立流程中继续执行，因此注册或移除这个回调不会关闭 SDK 的保护行为。回调会收到 OZeroSecurityEvent，其中包含检测区域、公共中止代码、消息键、诊断消息以及应用是否即将关闭。

删除先前注册的用户回调。请务必从 OnDisable 或 OnDestroy 调用它，以避免内存泄漏。

注册供 CustomCallbackOnly 使用的项目回调。仅在原生代码设定不可撤销的致命退出期限后调用。回调可以显示通知或执行简短清理，但不能取消退出或延长期限。

移除已注册的安全终止通知回调。

立即完成已经处于等待状态的致命安全退出。通常从通知对话框的确认按钮调用；若没有待处理退出，则不执行任何操作。

Registers a callback for server-issued policy actions delivered by the Pro device policy heartbeat. Use this for portal policies such as Callback responses. It is separate from local security detection callbacks.

Removes a previously registered policy action callback. Register in OnEnable and unregister in OnDisable when using a scene object.

注册用于接收面向用户的 activation 或 DRM 状态变化的回调。使用 OZero-managed Steam DRM 和默认 Managed Verification UI 时，SDK 已经显示需要联网、重试、timeout 和阻止状态；只有自定义 UI、telemetry 或游戏专用 session gate 需要时才注册。

移除先前注册的 activation 状态回调。在场景对象中使用时，请在 OnEnable 注册并在 OnDisable 解除。

Registers a callback for the shared OZero Managed Verification state used by Pro Build Integrity and Steam DRM. The default SDK UI handles these states automatically when enabled; use this callback only for custom UI, custom telemetry, or game-specific session gates.

Removes a previously registered managed verification state callback. Register in OnEnable and unregister in OnDisable when using a scene object.

Replaces individual built-in verification UI strings at runtime. Use JSON files under Assets/OZeroSecurity/Resources/OZeroLocalization for normal localization, and use this provider only when text must be supplied dynamically.

Removes a previously registered managed verification text provider.

Retries SDK-managed Build Integrity attestation after an online-required or retry-timeout state. The default Managed Verification UI calls this automatically. If your own game server validates OZA tokens, retry your own login or session-refresh request instead.

重试由 OZero 服务器托管的 Steam Activation / DRM 验证。默认 Managed Verification UI 会在 SDK 内部调用匹配的 retry 流程。只有在有意替换默认 UI 的自定义 UI 中才从游戏代码调用它；如果由你的游戏服务器执行 Steam 验证，请改为重试你自己的登录或会话请求。

代表

这是 RegisterUserCallback 使用的回调签名。当需要警告 UI、自有服务器日志或短保存步骤时，请查看 evt.Type、evt.AbortCodeHex、evt.MessageKey、evt.Message 和 evt.WillAbort。如果 evt.WillAbort 为 true，应用已经计划关闭，请避免耗时操作。

例子

using OZeroSDK.Security;
using UnityEngine;

public class MySecurityListener : MonoBehaviour
{
    void OnEnable()
        => OZeroSecurityManager.Instance.RegisterUserCallback(OnThreat);

    void OnDisable()
        => OZeroSecurityManager.Instance.UnregisterUserCallback(OnThreat);

    void OnThreat(OZeroSecurityEvent evt)
        => Debug.Log(
            $"Threat={evt.Type}, Code={evt.AbortCodeHex}, Message={evt.Message}");
}

OZeroSecurityTerminationNoticeEvent class

仅在原生致命退出期限设定后发出的用户侧载荷。它包含原始安全事件，以及可供客户支持使用的稳定支持代码。

OZeroSecurityEvent class

传递给 RegisterUserCallback 的面向客户公开的违规事件。它仅公开稳定且安全的诊断信息，而不是内部检测详情。

OZeroPolicyActionEvent class

Server policy callback payload passed to RegisterUserPolicyActionCallback. These events are issued by the customer portal policy system and delivered on the Unity main thread through the Pro device policy heartbeat.

Policy callback example

Use this when a Customer Portal security policy is configured as Callback. The SDK delivers the policy action to the game, and your game decides how to notify, restrict, or move the user.

using OZeroSDK.Security;
using UnityEngine;

public sealed class OZeroPolicyListener : MonoBehaviour
{
    private void OnEnable()
        => OZeroSecurityManager.Instance.RegisterUserPolicyActionCallback(OnPolicyAction);

    private void OnDisable()
        => OZeroSecurityManager.Instance.UnregisterUserPolicyActionCallback(OnPolicyAction);

    private void OnPolicyAction(OZeroPolicyActionEvent evt)
    {
        Debug.LogWarning($"Policy={evt.PolicyId}, Module={evt.Module}, Score={evt.Score}, Reason={evt.Reason}");

        if (evt.Score >= 80)
        {
            ShowSecurityNotice(evt.Reason);
            DisableRankedMatchmaking();
        }
    }
}

OZeroUserActivationStateEvent class

User-facing activation or DRM state payload passed to RegisterUserActivationStateCallback. Steam Activation / DRM uses it to tell the game whether cached offline play is still allowed or online revalidation is required.

Activation 状态回调使用条件

OZero-managed Steam DRM 与默认 Managed Verification UI 一起使用时，不需要 activation callback 代码；SDK 会向玩家显示需要联网、重试、timeout 和阻止状态。只有在有意替换默认 UI、添加自己的 session gate，或运行客户游戏服务器验证流程时才注册此回调。不要把 Steam Web API Key 或 OZero Server API Key 放入客户端。

OZeroUserManagedVerificationStateEvent class

传递给 RegisterUserManagedVerificationStateCallback 的面向用户 managed verification payload。Build Integrity 和 Steam DRM 都使用此事件，但默认 Managed Verification UI 会自动消费它。只有自定义 UI、自定义 telemetry 或游戏专用 session gate 需要时，才在游戏代码中处理。

Managed verification 回调使用条件

当 Security Config > Pro - License & Online Services > Online Verification UI > Ui Policy 使用 OZero 内置对话框时，SDK 已经处理 Build Integrity 和 Steam DRM 的 managed-verification UI、重试和 timeout 状态。只有在 Custom UI / Callback Only、额外 telemetry 或游戏专用 session gate 中才注册 RegisterUserManagedVerificationStateCallback。在自定义 UI 模式下，请调用与 Provider 匹配的 retry 方法；在客户游戏服务器模式下，请重试自己的登录或会话请求。

OZeroManagedVerificationUiPolicy enum

决定 SDK 如何向玩家显示来自 Build Integrity 和 Steam DRM 的 managed verification 状态。两个 Built-In policy 都需要 TextMeshPro、TMP Essential Resources 和 optional OZero Built-In TMP Dialog package。若缺少这些条件仍选择 Built-In policy，build preflight 会停止 player build。请在 Window > OZero Security > Check Setup 中点击对应错误项的 Import Package 进行修复。

OZeroSecurityTerminationNoticePolicy enum

控制在已经设定的致命安全退出前显示的可选用户通知。Standard、Pro 许可证均可使用。

OZeroManagedVerificationTimeoutAction enum

当在线必需或重试状态未在配置的超时时间内解决时，决定内置 managed verification UI 的处理方式。

ModulationType enum

标识哪个安全模块发出了警报。通过 OZeroSecurityEvent.Type 传递。

OZeroBootstrapper OZeroSDK.Security

负责初始化 SDK 的自动启动入口点。您不需要在项目代码中直接调用。它根据 Unity 启动流程加载安全设置，并在游戏开始前准备好激活的检测器。

OZeroSecurityConfigRuntime OZeroSDK.Security

在玩家运行时读取和验证受保护的构建设置的配置加载程序。验证打包的设置，准备内存中的 OZeroSecurityConfig 运行设置，并在验证失败时应用配置的威胁响应策略。

特性

方法

可以安全重复调用的加载器。第一次调用验证并加载打包设置，后续调用重用相同的设置快照。失败处理遵循配置的响应策略。

OZero Secure Variables OZeroSDK.Security

可替代常规数字、字符串和向量类型的加密类型。值存储在受保护的内存区域中，并支持大多数算术运算符和隐式转换。只需更改类型名称即可应用于现有代码。

支持类型

支持的运算符

数字类型（Int、Int64、UInt、UInt64、Short、UShort、Byte、Float、Double、Decimal）支持算术（+ - * / %）、比较（== != < > <= >=）、复合赋值 (+= -= *= /=)、递增/递减 (++ --) 运算符以及与基本类型的隐式转换。Vector2·Vector3 支持算术和等式运算符，而 Bool 仅支持等式运算符。字符串支持 ==、!=、+。Buffer 可以通过索引运算符直接访问字节数组。

OZeroSafePlayerPrefs OZeroSDK.Security

可以像 Unity 的 PlayerPrefs 一样使用的加密存储。由于密钥名称和值均受到保护，因此即使直接打开 Windows 注册表或 iOS 配置文件，也很难读取原始值。

方法

提供常见的 PlayerPrefs 风格方法，并额外提供 Int64、Double、Bool、IncrementInt 辅助方法。已有的 plain PlayerPrefs 值不会自动迁移；请从今后需要保护的 key 开始使用 OZeroSafePlayerPrefs。

OZeroSV_File OZeroSDK.Security

使用内部加密逻辑保护文件的读写。由于不使用设备绑定密钥，因此即使像 Steam 云存档那样需要在多台设备上读取同一个存档文件，也可以使用。如果故意篡改文件，读取时的完整性检查将会失败并抛出 InvalidDataException。

方法

加密 contents 并保存到 path。父文件夹不会自动创建，必要时请先调用 Directory.CreateDirectory。

读取 path 指定的文件，验证完整性后返回解密后的字符串。如果文件被篡改，将抛出 InvalidDataException。

加密数据并安全保存到 path。

读取 path 指定的文件。在读取时验证文件的完整性，并检测是否发生篡改。

解密已经加载到内存中的加密字节缓冲区。适用于远程下载或自定义存储后端，无法将文件路径传给 ReadAllText 的情况。

示例代码

using OZeroSDK.Security;

string path = Application.persistentDataPath + "/save.json";
string json = JsonUtility.ToJson(saveData);

// Write (encrypts automatically)
OZeroSV_File.WriteAllText(path, json);

// Read (decrypts + integrity check)
try
{
    string loaded = OZeroSV_File.ReadAllText(path);
    saveData = JsonUtility.FromJson<SaveData>(loaded);
}
catch (System.IO.InvalidDataException)
{
    // File was tampered — handle accordingly
    Debug.LogError("Save file integrity check failed.");
}

OZeroBuildIntegrityValidator OZeroSDK.Security

处理构建篡改、调试器/计时异常、平台原生完整性检查以及可选的 Pro 服务器验证的验证器。当 OZeroSecurityConfig 中启用构建完整性时，由 SDK 自动创建。

检查项目

公共属性

事件和方法

当所有启用的本地检查通过时调用。

当启用的本地检查或 Pro 证明拒绝构建时调用。

在线附加组件中为 OZeroOnlineAttestation.OnAttestationPassed：服务器证明成功且 OZeroOnlineAttestation.Token 持有有效令牌时调用。

在线附加组件中已移至 OZeroOnlineAttestation.RequestGameServerAttestation。仅限 CustomerGameServer：本地检查通过后，使用服务器签发的 audience、64 位 hex challenge 和 session ID 开始证明；令牌通过 OZeroOnlineAttestation.TokenReady 送达。参见使用服务器 API 密钥集成游戏服务器。

开始手动验证。对于一般项目，建议使用仪表板的启动/定期验证设置。

OZeroBuildAttestationToken

Pro attestation 的结果。将 AttestToken 发送到游戏服务器，并在登录、PvP、排行榜或货币流程使用前调用 IsValid(nowMillis) 确认有效性。

超过服务器颁发的过期时间后返回 true。

令牌成功签发且尚未过期时返回 true。

OZeroSpeedHackDetector OZeroSDK.Security

使用五个独立的检测信号检测速度黑客和时间操纵。仅在信号相互确认时才报告威胁，从而减少误报。

检测信号

检测通过带有 ModulationType.SpeedHack 或 ModulationType.TimeHack 的 OZeroSecurityManager 回调进行。设置在 OZeroSecurityConfig 中。

OZeroWatchdog OZeroSDK.Security

用于可信长时间加载工作的公共 helper。在同步工作可能合理地阻塞 Unity 主线程超过发布版 deadline 时，有限延后原生 Watchdog heartbeat deadline。

方法

开始一个受限的 loading grace scope。可信加载工作完成后，请立即调用返回 scope 的 End() 或 dispose 它。支持嵌套 scope；最后一个 scope 结束后会恢复正常 Watchdog timing。

手动结束此 loading grace scope。Dispose() 会调用相同逻辑，因此 using 块和显式 End() 等效。

用于同步加载工作的便捷 wrapper。它创建 loading grace scope，执行 work，并通过 using 块安全结束 scope。

示例

using OZeroSDK.Security;
using UnityEngine.SceneManagement;

public void LoadLargeScene()
{
    using (OZeroWatchdog.BeginLoadingGrace(60000))
    {
        SceneManager.LoadScene("Battle", LoadSceneMode.Single);
    }
}

OZeroInjectionDetector OZeroSDK.Security

检查正在运行的游戏是否附加了可疑模块，或者是否存在挂钩或调试器痕迹。定期检查在可能的情况下会使用稍微变动的检查时间，使简单的绕过尝试变得更加困难。

检测目标

检测通过带有 ModulationType.Injection 的 OZeroSecurityManager 回调进行。

OZeroPCStoreAntiPiracy OZeroSDK.Security

Steam Anti-Piracy 的运行时控制 API。大多数项目只需在 Config Dashboard 中设置；如果游戏提供自己的策略 UI 或 QA 开关，可以通过这个静态 API 临时覆盖本地检测动作。还提供可选 DLC 的所有权查询（QueryDlcOwnership）。

OZeroPCStoreDetectionAction

方法

在运行时覆盖本地 Steam Anti-Piracy 检测动作。适用于 QA 构建中临时降级为 Observe，或让操作员从管理员菜单中选择特定操作。

清除运行时覆盖的操作，恢复为在 OZeroSecurityConfig 或 Pro 门户中设置的基本操作。

示例

using OZeroSDK.Security;

// QA session: observe Steam violations without blocking gameplay.
OZeroPCStoreAntiPiracy.SetDetectionActionOverride(
    OZeroPCStoreDetectionAction.Observe);

// Restore the dashboard/server policy.
OZeroPCStoreAntiPiracy.ClearDetectionActionOverride();

最近验证结果

返回最近一次 Steam 验证快照，包括 reported AppID、BuildID、SteamID、服务器验证状态、soft signal 和 native score 字段。可用于调试 UI 或 QA 报告，但不要作为唯一的游戏权限判断依据。

QueryDlcOwnership

查询当前 Steam 用户是否拥有某个可选 DLC。这是只查询、不会终止游戏的 API，用于解锁 DLC 内容等判断。加入 requiredDlcAppIds 的必需 DLC 会在启动时自动检查，无需调用此 API。请使用此 API，而不是直接调用 Steamworks.NET。

using OZeroSDK.Security;

// Optional DLC: unlock the content only when the account owns it.
OZeroDlcOwnership dlc = OZeroPCStoreAntiPiracy.QueryDlcOwnership(1234560);
if (dlc.Owned)
{
    UnlockExpansion();
}

OZeroInstallSourceValidator OZeroSDK.Security

Android 安装来源验证器。启用 Install Source 后组件会自动创建。客户代码通常读取最近结果，用于支持 UI、诊断日志或按商店分流处理。

方法和事件

安装来源确认完成后调用。

返回最近一次检查的缓存结果。

必要时先进行初始化，然后返回 Android 安装来源结果。

InstallSourceResult

AndroidInstallSource

InstallSourceResult.DetectedSource 返回的准确 enum 值。manual 中的商店名称只是便于阅读的显示名；代码中请与下面这些 enum 名称比较。

OZeroDeviceBindingDetector OZeroSDK.Security

用于绑定到设备的存档槽和客服重置流程的辅助 API。启用 Device Binding 后，验证器会自动启动。只有在需要把云存档、账号存档槽等数据绑定到当前设备时，才需要直接调用下面的 token 方法。

方法

准备本地设备指纹，然后进行注册或验证。普通项目中通常会在 SDK 启动时自动调用。

创建一个将存档槽 key 与当前设备关联的令牌。请将令牌保存在存档元数据或服务器记录中，不要放入玩家可编辑的存档正文。

检查已保存的存档槽令牌是否与当前设备匹配。如果不匹配，SDK 会触发配置好的 Device Binding 违规响应。

返回当前设备指纹 hash 的调试/演示用辅助方法。不要在正式游戏代码中显示、上传或保存这个值。

清除此设备上保存的指纹，并重新绑定当前设备。在玩家构建中，如果配置了 Pro 许可证和服务器设置，非空令牌会在后台作为服务器签发的 Reset Token 验证，因此解除会在此调用返回之后发生；如需等待结果，请使用 ClearStoredFingerprintAsync。其他情况下由授权回调判断，并通过 AuthorizationToken 接收令牌。不使用服务器 Reset Token 时，请使用 RequestReset。

ClearStoredFingerprint 的可 await 形式。请在主线程上调用并 await，清除指纹后返回 true。服务器检查不会阻塞主线程，因此在 HTTP 运行于主线程的环境（Windows 和 macOS IL2CPP、WebGL）中游戏也不会卡住。

请求清除已保存的指纹。在玩家构建中由授权回调判断，reason 会传给回调供你记录日志。批准后，SDK 会清除指纹，在同一会话中重新绑定当前设备并返回 true。在编辑器中始终会解除。

注册游戏的回调，用于在玩家构建中批准（true）或拒绝解除。传入 null 可移除回调。回调会在请求解除的线程上同步调用。没有授权回调时，除非提供有效的服务器 Reset Token，玩家构建会拒绝解除。

OZeroDeviceBindingResetRequest

传给授权回调的只读结构体。

传给 RequestReset 的原因；没有时为空字符串。

传给 ClearStoredFingerprint 的令牌；没有时为空字符串。

示例

using OZeroSDK.Security;

var detector = OZeroDeviceBindingDetector.Instance;
string slotKey = "account:1234:slot:main";

string token = detector.BindToSaveSlot(slotKey);
// Store token next to your save metadata.

bool ok = detector.ValidateSaveSlot(slotKey, token);

// Reset flow: register an authorizer that performs your own check.
OZeroDeviceBindingDetector.SetResetAuthorizer(request =>
    MyAccountService.HasVerifiedResetFor(request.Reason));
bool cleared = detector.RequestReset("ticket-1234");

OZeroSecurityConfig ScriptableObject

OZero 模块的安全设置。在编辑器中通过 Edit > Project Settings > OZero Security 编辑，并保存在 ProjectSettings/OZeroSecuritySettings.asset（共享）和 UserSettings/OZeroSecuritySecrets.json（按用户保存的机密）中；构建时会烘焙进玩家包。在代码中用 OZeroSecurityConfig.Instance 读取当前设置；要在编辑器脚本中修改，请使用 OZeroSecurityProjectSettings（Load、LoadOrCreate、Save）。

字段

字段会分组到 Response、Integrity 等嵌套设置类中。下表汇总了代码中经常查看或集成时经常调整的字段；完整 Inspector 设置表请参考 manual。默认值以代码中保存的序列化初始值为准。如果发布构建中运行时值会被强制改写，则用 * 标记。

WebTimeUnavailablePolicy

配置的 web-time 地址连续失败 maxConsecutiveFailures 个回合后应用的策略。它决定临时网络问题只记录日志，还是上报为安全回调。

OZeroLicenseConfig OZeroSDK.Security.License

在线许可证设置。在编辑器中保存在 ProjectSettings/OZeroLicenseSettings.asset 中，可在 Window > OZero Security > Online Services 窗口或 Edit > Project Settings > OZero Security 的 Pro 卡片中编辑；构建时会以加密资源形式放入玩家包。它选择许可证层级，并保存 Pro 许可证密钥与 Pro 运行时服务器设置。如果设置文件不存在或密钥为空，则其运行方式与 Standard 相同。要在编辑器脚本中修改，请使用 OZeroSDK.Security.License.OZeroLicenseProjectSettings（Load、LoadOrCreate、Save、Reload）。

字段

本地时间策略

此策略在客户门户 > 许可证 > 本地时间中管理，Unity 中无需同步设置。在线 Pro 激活使用服务器时间；所选允许范围只用于判断已保存的 Pro 激活信息能否用于离线启动。

OZeroDeclaredSecurityLevel

启用安全等级验证时发送给 Pro 服务器的 enum。服务器会确认该值是否满足许可证配置的最低等级。

OZeroOfflineProPolicyMode

这个 enum 决定设备无法连接服务器时，本地 Build Integrity 如何处理已签名的 Pro 门户阻止策略。各值明确区分 fail-open 运营、fail-closed 策略强制和测试 bypass 行为。

特性

从 Resources 加载运行时设置。如果为 null，请按照与 Standard 相同的方式处理。

对于 Standard 或空许可证密钥，它为 true；需要 Pro 激活时为 false。

在 Pro 中为 true。用于识别可执行 Native Variant 验证的等级；是否存在 private Variant 会根据已导入的签名清单自动判断。

只有当前项目启用显式 native variant 兼容性覆盖时才为 true。

OZeroLicenseRuntime OZeroSDK.Security.License

读取当前许可证状态的运行时 API。它在应用启动时自动初始化，因此大多数项目只需读取状态或调用 HasCapability 即可。

特性

方法

多次调用也是安全的启动方法。通常由 SDK 自动调用，在自定义引导中可以在读取许可证状态之前等待。

返回当前激活信息中是否具有 telemetry、signed_time、attestation 等功能权限。在 Standard 中为 false。

[Pro] 将用户 UUID（账号 ID）关联到当前会话。请在登录后调用。该值在设备内哈希，只发送哈希值。如果去掉首尾空白后为空、超过 128 个字符或包含控制字符，则返回 false。可以在激活前调用，哈希会在激活后发送。约 5 秒后会执行一次设备策略检查（最短间隔 30 秒）。

[Pro] 解除用户 UUID 的关联。请在登出时调用。

许可证服务器运行时调用

Pro 功能使用 /v1 下的 HTTPS JSON API。OZA v2 是绑定 audience、256-bit challenge、session ID 和 build evidence 的一次性令牌。/v1/validate 必须提交 License Server API Key 和相同的 binding 值；每个成功令牌都会被原子性 consume。没有自有后端的团队使用带 root-signed keyset 和 OZMS receipt 的 OZero Managed。

POST /v1/activate contract

这是 Unity SDK 启用 Pro 许可证时发送的基础请求契约。服务器 schema 可以接收额外的原生验证字段，但当前 SDK 的基础激活请求会发送下面这些字段。

使用服务器 API 密钥集成游戏服务器

[Pro] 服务器 API 密钥让你的游戏服务器可以与 OZero 完成三件事：登录时确认玩家的构建是正版（validate）、为客服和运营查询用户与设备（read）、封禁或解封用户（block）。密钥只放在你的游戏服务器上。游戏客户端从不持有密钥，只运行 OZero SDK 并把令牌发送到你的服务器。

概览

Game client (OZero SDK)          Your game server                         OZero API
-----------------------          ----------------                         ---------
sign-in request        ------->  issue audience, challenge, sessionId
RequestGameServerAttestation()
TokenReady: attestToken ------>  POST /v1/validate            [validate]  ----> valid / reason
                                 allow or refuse the sign-in
SetExternalUserId(uuid)          (the SDK sends only the hash h1 with policy checks)
                                 support tool: GET /customer-api/...  [read]  ---->
                                 sanctions: POST/DELETE user-blocks   [block] ---->
policy check: callback or end  <---------------------------------------------  rule applied

The server API key lives only on your game server. Never put it in the game client.

服务器 API 密钥的权限范围

该 API 使用你现有的服务器 API 密钥（Customer Portal > Server Keys > Server API Keys）并附加权限范围。签发密钥时选择范围，密钥列表会显示每个密钥的范围。之前签发的密钥只有 validate。

• validate：通过 /v1/validate 验证令牌（原有用途）。
• read：查询用户、设备、事件和封禁规则（所有 GET 请求）。
• block：创建、更新和解除用户封禁规则（包括会结束用户游戏的强制结束规则）。
• config：查询、登记和解除安全设置哈希（/v1/customer-api/config-hashes，所有方法）。用于 CI：CI 密钥只授予 config，不要授予 block。

在签发页面勾选 block 时，read 也会一起勾选（可以取消）。只有 block 时，密钥可以创建和解除封禁规则，但无法查询用户、设备或规则列表。如需同时查询，请使用 read + block。

认证与限制

所有请求都发送到 https://api.ozerosecurity.com/v1，并附带 Authorization: Bearer <服务器 API 密钥>，只有处于有效状态的 Pro 许可证可以使用。POST /v1/validate 需要 validate 范围，并有按 IP 的限制。/v1/customer-api/* 的 GET 需要 read，规则变更需要 block（例外：/v1/customer-api/config-hashes 的所有方法，包括 GET，都需要 config）；每个密钥每分钟最多 120 次请求，同时还有按 IP 的限制。列表通过 limit 和 before（上一页的 nextBefore）分页。

1. 验证（validate）：是正版构建吗？

SDK 会把构建完整性证据发送给 OZero，并获得一个绑定到你的服务器所选值的一次性 OZA 证明令牌。POST /v1/validate 会告诉你的服务器：该令牌是 OZero 为此许可证的正版构建、为本次登录签发的，且尚未被使用。请在登录、排位赛或购买前使用。需要开启 Online Services > Build Integrity > Check Integrity With Server，并将 Attestation Verification Mode 设为 CustomerGameServer。

1. 游戏服务器为本次登录签发绑定值：audience（游戏固定名称，由字母、数字和 ._:- 组成，3-128 个字符）、challenge（每次新生成的 32 字节随机数，64 位 hex）和 sessionId（相同字符集，16-128 个字符）。
2. 客户端调用 OZeroOnlineAttestation.RequestGameServerAttestation(audience, challenge, sessionId)。如果上述设置未开启、本地检查尚未通过、正在执行中或值无效，则返回 false。
3. 令牌通过 OZeroOnlineAttestation.TokenReady（或 RegisterTokenCallback）送达。客户端把 context.AttestToken 发送给你的游戏服务器。
4. 游戏服务器使用拥有 validate 范围的密钥调用 POST /v1/validate，请求体为 { attestToken, licenseKey, audience, challenge, sessionId, enforceVersionWhitelist }，并原样使用自己签发的值。
5. valid: true 时允许登录，payload 中包含平台、SDK 和应用版本、清单哈希等信息。valid: false 时拒绝登录并记录 reason。每个令牌只能验证一次，第二次调用会返回 TOKEN_REPLAYED。

游戏客户端（Unity）：

using OZeroSDK.Online;
using OZeroSDK.Security;
using UnityEngine;

public sealed class OZeroSignInAttestation : MonoBehaviour
{
    private void OnEnable() => OZeroOnlineAttestation.RegisterTokenCallback(OnToken);
    private void OnDisable() => OZeroOnlineAttestation.UnregisterTokenCallback(OnToken);

    // 1) Your game server answered the sign-in request with a binding.
    public void OnBindingReceived(string audience, string challenge, string sessionId)
    {
        if (!OZeroOnlineAttestation.RequestGameServerAttestation(audience, challenge, sessionId))
            Debug.LogWarning("OZero attestation did not start (check Security Config > Build Integrity > Pro - Online).");
    }

    // 2) The SDK issued a token bound to that binding: send it to your game server.
    private void OnToken(OZeroAttestationTokenContext context)
    {
        MyGameServer.SendAttestToken(context.AttestToken);   // your networking code
    }
}

请求与响应：

POST https://api.ozerosecurity.com/v1/validate
Authorization: Bearer <server API key with the validate scope>
Content-Type: application/json

{
  "attestToken": "<header>.<payload>.<signature>",
  "licenseKey": "<your license key>",
  "audience": "my-game-login",
  "challenge": "<64 hex characters, new for every sign-in>",
  "sessionId": "4b1d6c2e-8f3a-4c55-9a0e-2f1b7d9c3e11",
  "enforceVersionWhitelist": false
}

200 OK (genuine build)
{
  "valid": true,
  "reason": null,
  "payload": {
    "licenseSubject": "...", "platform": "...", "sdkVersion": "1.2.0", "appVersion": "...",
    "manifestHash": "...", "integrityFlags": "...", "deviceBindingHash": "...",
    "deviceBinding": null, "installSource": null, "countryCode": null,
    "issuedAt": "...", "expiresAt": "...", "tokenId": "..."
  }
}

403 Forbidden (rejected)
{ "valid": false, "reason": "TOKEN_REPLAYED", "payload": null }

/v1/validate 的常见结果：

4xx 和 5xx 响应也带有 JSON 响应体。请在抛出错误前读取它：密钥和请求错误返回 { "code", "message" }，被拒绝的令牌返回 { "valid": false, "reason" }。

2. 查询（read）：查找用户与设备

客服常见的问题：被举报用户用哪些设备玩过、OZero 最近检测到了什么、举报中的设备是否关联该用户。用用户 UUID 和许可证 salt 计算 h1，然后调用下面的 GET 端点。服务器只保存带密钥的哈希，因此无法列出你的用户的 h1；要检查某设备上的某个用户，请传入 ?h1=。

GET /users/{h1}/devices 的响应示例：

{
  "userKeyPrefix": "a1b2c3d4",
  "devices": [
    { "deviceId": "...", "firstSeenAt": 1789900000000, "lastSeenAt": 1790000000000, "eventCount": 12 }
  ],
  "block": null
}

3. 封禁（block）：处罚与解除

常见用法：反作弊审核确认作弊后自动封禁、在运营工具中执行限期处罚、申诉成功后解除。callback 把处理交给游戏代码；terminate 会结束游戏。再次为同一用户提交会更新生效中的规则。

游戏中会发生什么：游戏调用 SetExternalUserId 后约 5 秒（最短间隔 30 秒），规则会在设备策略检查时生效。callback 会向游戏发送 Module = "user_policy" 的 policy action；terminate 会先发送 policy action，然后显示 OZ-SEC-0E 提示并结束会话，OZeroLicenseRuntime.LastServerBlockCode 变为 "USER_BLOCKED"。参见手册中的设备 ID 与用户 UUID。

4. 设置（config）：安全设置哈希（CI）

为每个发布构建登记哈希后，安全等级检查只会放行你的构建（参见手册中的安全设置哈希许可列表）。所有方法都需要 config 范围。哈希是构建日志行 [OZero] Security config digest for this <Target> build: … 中的 64 位小写 hex。

请求与响应：

POST https://api.ozerosecurity.com/v1/customer-api/config-hashes
Authorization: Bearer <server API key with the config scope>
Content-Type: application/json

{
  "configHash": "<64 hex characters from the build log>",
  "label": "1.2.0 release (Windows)",
  "expiresInDays": 365,
  "acknowledgeEnforcement": true
}

201 Created
{
  "hash": {
    "configHash": "...", "label": "1.2.0 release (Windows)", "status": "active",
    "createdAt": 1790000000000, "createdBy": "api-key:...", "expiresAt": 1821536000000,
    "revokedAt": null, "revokedBy": null
  },
  "created": true,
  "enforcementStarted": true
}

409 Conflict (first approval without acknowledgeEnforcement)
{ "code": "ENFORCEMENT_ACK_REQUIRED", "message": "the first approved hash turns on enforcement: ..." }

GET https://api.ozerosecurity.com/v1/customer-api/config-hashes
{
  "policy": { "activeCount": 1, "mode": "enforced" },
  "approved": [ { "configHash": "...", "label": "...", "status": "active", "expiresAt": null, "...": "..." } ],
  "observed": [ { "configHash": "...", "firstSeenAt": 1789900000000, "lastSeenAt": 1790000000000, "seenCount": 3,
                  "lastDeclaredLevel": 2, "lastSdkVersion": "1.2.0", "lastPlatform": "...", "approval": "active" } ],
  "schemaReady": true
}

DELETE https://api.ozerosecurity.com/v1/customer-api/config-hashes/<configHash>
{ "hash": { "configHash": "...", "status": "revoked", "...": "..." },
  "policy": { "activeCount": 0, "mode": "compatibility" } }

CI 示例（bash，Unity 构建之后）：从构建日志（-logFile 指定的文件）中读取哈希并登记。请把密钥保存为 CI 机密。

#!/usr/bin/env bash
# CI step after the Unity build. BUILD_LOG is the file passed to Unity with -logFile.
# OZERO_CONFIG_API_KEY: a server API key with only the config scope, stored as a CI secret.
set -euo pipefail

BUILD_LOG="${BUILD_LOG:-build.log}"
LABEL="${BUILD_LABEL:-ci build}"   # letters, digits and spaces only (it goes into JSON as is)

HASH=$(grep -oE 'Security config digest for this [A-Za-z0-9]+ build: [0-9a-f]{64}' "$BUILD_LOG" \
  | tail -n 1 | awk '{print $NF}')
if [ -z "$HASH" ]; then
  echo "No security config digest in $BUILD_LOG" >&2
  exit 1
fi

STATUS=$(curl -sS -o ozero-response.json -w '%{http_code}' -X POST \
  "https://api.ozerosecurity.com/v1/customer-api/config-hashes" \
  -H "Authorization: Bearer ${OZERO_CONFIG_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"configHash\":\"${HASH}\",\"label\":\"${LABEL}\",\"expiresInDays\":365}")

case "$STATUS" in
  200|201) echo "Approved security config hash ${HASH}" ;;
  409) echo "First approval turns on enforcement: approve once in the Customer Portal," \
            "or send \"acknowledgeEnforcement\": true on purpose." >&2
       cat ozero-response.json >&2; exit 1 ;;
  *)   echo "OZero API returned HTTP ${STATUS}:" >&2   # the body has { "code", "message" }
       cat ozero-response.json >&2; exit 1 ;;
esac

客户 API 错误

4xx 和 5xx 响应的响应体中也会返回 { "code", "message" }。请读取响应体并按 code 分支处理：

通过 API 创建的规则在 Customer Portal 规则列表中显示为 Server API，并在 Operation history 中记录为 server-api-key … 加密钥最后 4 个字符。

5. 示例：一个游戏服务器文件

一个完整的 Node.js 模块（18+，无需额外依赖），涵盖 validate、read 和 block，随后是同样流程的 C# 和 Python 示例。密钥、许可证密钥和 salt 从环境变量读取。哈希函数在使用前用测试向量自检。429 和 503 使用指数退避重试。

// ozero-server.js - Node.js 18+ (built-in fetch and crypto, no extra packages)
const crypto = require("crypto");

const API = "https://api.ozerosecurity.com/v1";
const VALIDATE_KEY = process.env.OZERO_VALIDATE_API_KEY; // scope: validate (sign-in servers)
const OPS_KEY = process.env.OZERO_SERVER_API_KEY;        // scopes: read + block (operations tools)
const LICENSE_KEY = process.env.OZERO_LICENSE_KEY;
const SALT = process.env.OZERO_EXTUID_SALT;              // Customer Portal > User UUID > Settings
const AUDIENCE = "my-game-login";

// h1 = SHA-256("OZERO-EXTUID-V1|" + salt + "|" + uuid) as lowercase hex.
function extUserHash(salt, uuid) {
  const id = uuid.replace(/^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g, "");
  return crypto.createHash("sha256").update("OZERO-EXTUID-V1|" + salt + "|" + id, "utf8").digest("hex");
}

// Self-check with the published test vector.
const TEST_SALT = Array.from({ length: 32 }, (_, i) => i.toString(16).padStart(2, "0")).join("");
if (extUserHash(TEST_SALT, "player-123") !== "2d5a23607064e6dbc02dc32dc96af8cf54862d2f51d778596cfbe9d6ba8f8a3a") {
  throw new Error("extUserHash does not match the test vector");
}

// 4xx and 5xx responses carry a JSON body with "code" (for example SCOPE_REQUIRED).
class OZeroApiError extends Error {
  constructor(status, data) {
    super(`OZero API ${status}: ${data.code ?? "HTTP_" + status} ${data.message ?? ""}`.trim());
    this.status = status;
    this.code = data.code ?? `HTTP_${status}`;
  }
}

// One request helper: reads the JSON body for every status and retries 429 and 503
// with exponential backoff (0.5, 1, 2, 4 s).
async function call(key, method, path, body, attempt = 0) {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  if ((res.status === 429 || res.status === 503) && attempt < 4) {
    await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
    return call(key, method, path, body, attempt + 1);
  }
  return { status: res.status, data: await res.json().catch(() => ({})) };
}

async function callOk(key, method, path, body) {
  const { status, data } = await call(key, method, path, body);
  if (status >= 400) throw new OZeroApiError(status, data);
  return { status, data };
}

// 1) validate --------------------------------------------------------------
function newSignInBinding() {
  return {
    audience: AUDIENCE,
    challenge: crypto.randomBytes(32).toString("hex"),
    sessionId: crypto.randomUUID(),
  };
}

async function validateSignIn(binding, attestToken) {
  const { status, data } = await call(VALIDATE_KEY, "POST", "/validate", {
    attestToken,
    licenseKey: LICENSE_KEY,
    ...binding,
    enforceVersionWhitelist: false,
  });
  if (data.valid === true) return { ok: true, payload: data.payload };
  if (data.valid === false) return { ok: false, reason: data.reason }; // e.g. TOKEN_REPLAYED: refuse
  throw new OZeroApiError(status, data); // e.g. SERVER_API_KEY_REQUIRED: fix the key or setup
}

// 2) read ------------------------------------------------------------------
async function lookUpUser(uuid) {
  const h1 = extUserHash(SALT, uuid);
  const devices = await callOk(OPS_KEY, "GET", `/customer-api/users/${h1}/devices`);
  const events = await callOk(OPS_KEY, "GET", `/customer-api/users/${h1}/events?limit=20`);
  return { devices: devices.data.devices, block: devices.data.block, events: events.data.events };
}

async function isUserOnDevice(uuid, deviceId) {
  const h1 = extUserHash(SALT, uuid);
  const { data } = await callOk(OPS_KEY, "GET",
    `/customer-api/devices/${encodeURIComponent(deviceId)}/users?h1=${h1}`);
  return data.linked === true;
}

// 3) block -----------------------------------------------------------------
async function blockUser(uuid, action, reason, days) {
  const body = { h1: extUserHash(SALT, uuid), action, reason }; // action: "callback" | "terminate"
  if (days) body.expiresInDays = days;                            // omit to keep it until lifted
  const { data } = await callOk(OPS_KEY, "POST", "/customer-api/user-blocks", body);
  return data.block.id; // 201 created, 200 updated the user's rule in effect
}

async function liftBlock(ruleId) {
  await callOk(OPS_KEY, "DELETE", `/customer-api/user-blocks/${ruleId}`);
}

// Branch on the error code, for example in your operations tool:
async function blockFromTool(uuid) {
  try {
    return await blockUser(uuid, "terminate", "Cheating", 30);
  } catch (e) {
    if (e.code === "SCOPE_REQUIRED") throw new Error("This key has no block scope: issue a read + block key.");
    if (e.code === "API_KEY_INVALID") throw new Error("The key was revoked: deploy the new key.");
    throw e;
  }
}

module.exports = {
  newSignInBinding, validateSignIn, lookUpUser, isUserOnDevice, blockUser, liftBlock, blockFromTool, OZeroApiError,
};

// C# (.NET 6+): the same flow
using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

// 4xx and 5xx responses carry a JSON body with "code" (for example SCOPE_REQUIRED).
public sealed class OZeroApiException : Exception
{
    public OZeroApiException(int status, string code, string message)
        : base($"OZero API {status}: {code} {message}".Trim())
    {
        Status = status;
        Code = code;
    }

    public int Status { get; }
    public string Code { get; }
}

public sealed class OZeroServerClient
{
    // Leave out null fields such as expiresInDays when no expiry is given.
    private static readonly JsonSerializerOptions Json = new() { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
    private static readonly Uri Api = new("https://api.ozerosecurity.com/v1/");
    private readonly HttpClient _validate = Create(Env("OZERO_VALIDATE_API_KEY"));
    private readonly HttpClient _ops = Create(Env("OZERO_SERVER_API_KEY"));
    private readonly string _licenseKey = Env("OZERO_LICENSE_KEY");
    private readonly string _salt = Env("OZERO_EXTUID_SALT");

    private static string Env(string name) =>
        Environment.GetEnvironmentVariable(name) ?? throw new InvalidOperationException(name + " is not set");

    private static HttpClient Create(string key)
    {
        var http = new HttpClient { BaseAddress = Api };
        http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);
        return http;
    }

    public static string ExtUserHash(string salt, string uuid)
    {
        var id = uuid.Trim(' ', '\t', '\n', '\v', '\f', '\r');
        var bytes = SHA256.HashData(Encoding.UTF8.GetBytes("OZERO-EXTUID-V1|" + salt + "|" + id));
        return Convert.ToHexString(bytes).ToLowerInvariant();
    }

    // Sends the request (retrying 429 and 503 with exponential backoff) and always reads the JSON body.
    private static async Task<(int Status, JsonElement Body)> Send(Func<Task<HttpResponseMessage>> request)
    {
        for (int attempt = 0; ; attempt++)
        {
            using var res = await request();
            bool retry = res.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable;
            if (retry && attempt < 4)
            {
                await Task.Delay(500 * (1 << attempt));
                continue;
            }
            JsonElement body;
            try { body = await res.Content.ReadFromJsonAsync<JsonElement>(); }
            catch (JsonException) { body = default; } // not JSON (for example a proxy error page)
            return ((int)res.StatusCode, body);
        }
    }

    // Throws OZeroApiException with the server's code for 4xx and 5xx.
    private static JsonElement Ok((int Status, JsonElement Body) r)
    {
        if (r.Status < 400) return r.Body;
        string code = $"HTTP_{r.Status}", message = "";
        if (r.Body.ValueKind == JsonValueKind.Object)
        {
            if (r.Body.TryGetProperty("code", out var c)) code = c.GetString() ?? code;
            if (r.Body.TryGetProperty("message", out var m)) message = m.GetString() ?? "";
        }
        throw new OZeroApiException(r.Status, code, message);
    }

    // 1) validate: (true, payload) allows the sign-in, (false, reason) refuses it.
    public async Task<(bool Ok, JsonElement Result)> ValidateSignIn(
        string audience, string challenge, string sessionId, string attestToken)
    {
        var r = await Send(() => _validate.PostAsJsonAsync("validate", new
        {
            attestToken, licenseKey = _licenseKey, audience, challenge, sessionId, enforceVersionWhitelist = false,
        }));
        if (r.Body.ValueKind == JsonValueKind.Object && r.Body.TryGetProperty("valid", out var valid))
            return valid.GetBoolean() ? (true, r.Body.GetProperty("payload")) : (false, r.Body.GetProperty("reason"));
        Ok(r); // no "valid": a key or setup error such as SERVER_API_KEY_REQUIRED
        throw new OZeroApiException(r.Status, $"HTTP_{r.Status}", "unexpected response");
    }

    // 2) read
    public async Task<JsonElement> LookUpUser(string uuid) =>
        Ok(await Send(() => _ops.GetAsync($"customer-api/users/{ExtUserHash(_salt, uuid)}/devices")));

    // 3) block and lift
    public async Task<string> BlockUser(string uuid, string action, string reason, int? days = null)
    {
        var body = Ok(await Send(() => _ops.PostAsJsonAsync("customer-api/user-blocks", new
        {
            h1 = ExtUserHash(_salt, uuid), action, reason, expiresInDays = days,
        }, Json)));
        return body.GetProperty("block").GetProperty("id").GetString()!;
    }

    public async Task LiftBlock(string ruleId) =>
        Ok(await Send(() => _ops.DeleteAsync($"customer-api/user-blocks/{ruleId}")));

    // Branch on the error code, for example in your operations tool.
    public async Task<string?> BlockFromTool(string uuid)
    {
        try
        {
            return await BlockUser(uuid, "terminate", "Cheating", 30);
        }
        catch (OZeroApiException e) when (e.Code == "SCOPE_REQUIRED")
        {
            Console.Error.WriteLine("This key has no block scope: issue a read + block key.");
            return null;
        }
    }
}

# Python 3 + requests: the same flow
import hashlib
import os
import secrets
import time
import uuid as uuidlib

import requests

API = "https://api.ozerosecurity.com/v1"
VALIDATE_KEY = os.environ["OZERO_VALIDATE_API_KEY"]  # scope: validate
OPS_KEY = os.environ["OZERO_SERVER_API_KEY"]         # scopes: read + block
LICENSE_KEY = os.environ["OZERO_LICENSE_KEY"]
SALT = os.environ["OZERO_EXTUID_SALT"]


def ext_user_hash(salt: str, uuid: str) -> str:
    uid = uuid.strip(" \t\n\v\f\r")
    return hashlib.sha256(f"OZERO-EXTUID-V1|{salt}|{uid}".encode("utf-8")).hexdigest()


assert ext_user_hash(bytes(range(32)).hex(), "player-123") == \
    "2d5a23607064e6dbc02dc32dc96af8cf54862d2f51d778596cfbe9d6ba8f8a3a"


class OZeroApiError(Exception):
    """4xx and 5xx responses carry a JSON body with "code" (for example SCOPE_REQUIRED)."""

    def __init__(self, status, data):
        self.status = status
        self.code = data.get("code") or f"HTTP_{status}"
        super().__init__(f"OZero API {status}: {self.code} {data.get('message', '')}".strip())


def call(key, method, path, body=None):
    """Reads the JSON body for every status; retries 429 and 503 with exponential backoff."""
    for attempt in range(5):
        res = requests.request(method, API + path, json=body, timeout=10,
                               headers={"Authorization": f"Bearer {key}"})
        if res.status_code not in (429, 503) or attempt == 4:
            try:
                data = res.json()
            except ValueError:
                data = {}
            return res.status_code, data
        time.sleep(0.5 * 2 ** attempt)


def call_ok(key, method, path, body=None):
    status, data = call(key, method, path, body)
    if status >= 400:
        raise OZeroApiError(status, data)
    return data


# 1) validate
def new_sign_in_binding():
    return {"audience": "my-game-login", "challenge": secrets.token_hex(32), "sessionId": str(uuidlib.uuid4())}


def validate_sign_in(binding, attest_token):
    status, data = call(VALIDATE_KEY, "POST", "/validate", {
        "attestToken": attest_token, "licenseKey": LICENSE_KEY, **binding, "enforceVersionWhitelist": False})
    if "valid" not in data:
        raise OZeroApiError(status, data)  # e.g. SERVER_API_KEY_REQUIRED
    return data["valid"], data.get("payload") if data["valid"] else data.get("reason")


# 2) read
def look_up_user(uuid):
    return call_ok(OPS_KEY, "GET", f"/customer-api/users/{ext_user_hash(SALT, uuid)}/devices")


# 3) block and lift
def block_user(uuid, action, reason, days=None):
    body = {"h1": ext_user_hash(SALT, uuid), "action": action, "reason": reason}
    if days:
        body["expiresInDays"] = days
    return call_ok(OPS_KEY, "POST", "/customer-api/user-blocks", body)["block"]["id"]


def lift_block(rule_id):
    call_ok(OPS_KEY, "DELETE", f"/customer-api/user-blocks/{rule_id}")


# Branch on the error code, for example in your operations tool:
def block_from_tool(uuid):
    try:
        return block_user(uuid, "terminate", "Cheating", 30)
    except OZeroApiError as e:
        if e.code == "SCOPE_REQUIRED":
            raise RuntimeError("This key has no block scope: issue a read + block key.") from e
        raise

6. 运维建议

• 按用途拆分密钥：登录服务器使用 validate 密钥，只在运营工具中使用 read + block 密钥。这样即使登录密钥泄露，也无法封禁用户。
• 为 CI 单独签发只有 config 范围的密钥。这样即使 CI 密钥泄露，也无法查询或封禁用户。
• 无停机轮换密钥：签发新密钥并部署到服务器，然后在 Customer Portal 中吊销旧密钥。
• 注意限制：客户 API 每个密钥每分钟 120 次请求。请合并客服查询，并在收到 429 时退避。
• 不要把服务器 API 密钥、salt、h1 或原始 UUID 写入日志或分析数据。请把 h1 视为化名的个人标识。

OZeroAbortCode 和事件消息

当 OZero 确认安全威胁时，会创建 OZeroSecurityEvent，并传递给 SDK 内置响应流程以及项目注册的回调。事件包含 ModulationType、稳定的公共 OZeroAbortCode、MessageKey、安全英文 Message 和 WillAbort。

Abort Code和消息表

创建日志或多语言 UI 时，请使用 OZeroAbortCode 和 MessageKey 作为参考值。 Message 使用开发人员可以理解的安全表达式，因此可以直接显示在开发人员屏幕或 QA 日志上而没有问题。

处理运行时的安全事件

默认情况下，OZero 会根据 Config Dashboard 的 Response 设置关闭应用，或只留下日志。如果需要显示自己的警告画面、发送服务器日志，或在关闭前保存少量数据，请使用 OZeroSecurityManager.RegisterUserCallback 注册处理程序。

如果 evt.WillAbort 为 true，当前响应策略会在回调流程结束后关闭应用。请只执行 analytics flush 或最终保存这类短操作。回调是事件上报和清理处理的连接点，不是取消 OZero 安全响应的方式。

using OZeroSDK.Security;

void OnEnable()
{
    OZeroSecurityManager.Instance.RegisterUserCallback(OnHack);
}

void OnHack(OZeroSecurityEvent evt)
{
    Debug.LogWarning(
        $"OZero: {evt.Type} {evt.AbortCodeHex} {evt.MessageKey} - {evt.Message}");

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

    Analytics.FlushSync();
}

Injection Detector API OZeroSDK.Security

用于把模块注册为 Injection 检查中的可信模块的 API。适用于随游戏一起分发的 overlay、录制工具、运营插件或合作伙伴模块等正常模块，但这些模块可能会被检测命中。HashHex 是该模块文件的 SHA-256 hash，SignerHex 是模块签名证书的 SHA-256 hash。不要猜测这些值，只注册从实际分发文件或诊断结果中确认的值。

数据结构 — OZeroInjectionWhitelistEntry

[Serializable]
public class OZeroInjectionWhitelistEntry
{
    // SHA-256 of the matched module file. Lowercase 64-char hex. Required.
    public string HashHex { get; set; }

    // SHA-256 of the module's signing certificate. Lowercase 64-char hex.
    // Empty ("") means "match by hash only" (only mode for Android .so / Linux ELF).
    public string SignerHex { get; set; }

    // Module file format hint — "pe" | "macho" | "so". Defaults to "so".
    public string Type { get; set; }

    // Optional human-readable note (UI / audit only — never sent to native).
    public string Comment { get; set; }
}

在 Unity 中注册本地可信模块条目时使用的数据结构。HashHex 是必填的 64 字符 SHA-256 文件 hash，SignerHex 是可选的 64 字符 signer fingerprint。Type 是 pe、macho 或 so 之一，用于表示模块格式；Comment 是给运营人员看的备注。

运行时 API — OZeroDispatch

// Returns true when trusted-module policy support is available.
public static bool HasInjectionV3 { get; }

// Replace trusted module entries atomically. Pass null/empty to clear.
// Returns false when the runtime support is unavailable.
public static bool RegisterInjectionWhitelistHash(OZeroInjectionWhitelistEntry[] entries);

// Trusted-module aware scan. Returns true when a relevant runtime signal is observed.
// Output fields are diagnostic context for your review and may be empty.
public static bool DetectAssemblyInjectionV3(
    out bool   silencedByWhitelist,
    out string hashHex,
    out string signerHex,
    out string matchedModulePath);

用于在运行时将可信模块列表传递给原生检查器，或确认当前平台是否支持此功能。多数项目只需要 Config Dashboard 中的 Injection 设置。如果必须从代码直接调用，请在分发文件确定后只注册必要条目，并在 QA 日志中确认注册前后的结果。

配置 — OZeroSecurityConfig.InjectionSettings

// Preferred local trusted-module surface in the Injection settings.
public OZeroInjectionWhitelistEntry[] InjectionWhitelistEntries { get; }
public bool EnableWindowsSystemModuleScan { get; }

InjectionWhitelistEntries 是 Injection 设置中的本地可信模块列表。它不是为了大范围允许客户 PC 上偶然安装的程序，而是用于注册开发商随游戏一起分发并确认正常工作的模块。这个本地列表所有 tier 都可以使用；Pro 客户可以通过客户门户的服务器管理 whitelist 在运营中更新同类策略。

返回 Injection 设置中 enableWindowsSystemModuleScan 的当前值。此属性为只读。若需更改，请调整 Unity 中的 Injection 设置，或应用 Low、Standard、Strict 安全预设。

发现不熟悉的系统模块时，不会立即关闭游戏，而是先记录以供查看。重复出现或文件没有嵌入式签名，都不会单独触发拦截。现有允许规则仍然有效；通过文件哈希明确禁止的模块仍会按策略拦截。请在 Unity 的 Injection 设置中调整此选项，Pro 门户不支持远程修改。此选项不影响其他平台。