API 参考

OZeroSecurityManager OZeroSDK.Security

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

特性

方法

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

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

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/OZeroSDK/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}");
}

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 回调使用条件

当 managedVerificationUiPolicy 使用 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 进行修复。

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 证明拒绝构建时调用。

当 Pro 服务器证明成功并且在 AttestationToken 中收到有效令牌时调用。

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

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 回调进行。

OZeroSteamAntiPiracy OZeroSDK.Security

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

OZeroSteamDetectionAction

方法

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

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

示例

using OZeroSDK.Security;

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

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

最近验证结果

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

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 的调试/演示用辅助方法。不要在正式游戏代码中显示、上传或保存这个值。

清除保存在此设备上的指纹。在非 Editor 构建中，需要传入服务器发放的 Reset Token，并且只应在合法的客服重置流程中使用。

示例

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);

OZeroSecurityConfig ScriptableObject

包含 OZero 安全模块默认设置的 Unity ScriptableObject 资产。当您在 Config Dashboard 或 Inspector 中更改值时，构建时它将被包含作为玩家的保护设置。当需要在代码中检查当前设置时，请使用 OZeroSecurityConfig.Instance。

字段

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

WebTimeUnavailablePolicy

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

OZeroLicenseConfig OZeroSDK.Security.License

从 Resources/OZeroLicenseConfig 加载的 ScriptableObject。选择许可证层级，并保存 Plus/Pro 许可证密钥与 Pro 运行时服务器设置。如果资产不存在或密钥为空，则其运行方式与 Standard 相同。

字段

OZeroDeclaredSecurityLevel

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

OZeroOfflineProPolicyMode

这个 enum 决定 Pro 门户下发设备、版本、国家等阻止策略后，玩家临时离线时 SDK 如何处理。第一次使用时建议保持默认值 ApplyCachedBlockPolicies。

特性

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

对于 Standard、Plus 或空许可证密钥，它为 true。仅当需要 Pro 激活时才为 false。

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

OZeroLicenseRuntime OZeroSDK.Security.License

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

特性

方法

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

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

许可证服务器运行时调用

Pro 功能使用 /v1 下的 HTTPS JSON API。大多数调用由 SDK 自动执行。拥有自己游戏服务器的团队可以通过 /v1/validate 验证 OZA 令牌，并在结账或发放货币等重要操作中使用 consumeToken=true 来防止重复使用相同的令牌。没有自己服务器的团队可以使用 OZero 服务器的允许/警告/阻断结果。

POST /v1/activate contract

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

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; }

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