API 레퍼런스

OZeroSecurityManager OZeroSDK.Security

활성화된 보안 모듈과 보안 이벤트를 관리하는 전역 관리자입니다. 씬이 바뀌어도 유지되며, Instance 프로퍼티로 접근할 수 있습니다. SDK가 앱 시작 시 자동으로 생성하므로 직접 인스턴스를 만들 필요는 없습니다.

프로퍼티

메서드

보안 이벤트를 프로젝트 코드에서 받아보고 싶을 때 콜백을 등록합니다. OZero의 기본 대응은 별도 흐름에서 계속 실행되므로, 이 콜백을 등록하거나 해제해도 SDK 보호 동작이 꺼지지 않습니다. 콜백에는 탐지 영역, 공개 중단 코드, 메시지 키, 진단 메시지, 앱 종료 예정 여부가 담긴 OZeroSecurityEvent가 전달됩니다.

이전에 등록한 유저 콜백을 제거합니다. 메모리 누수 방지를 위해 OnDisable 또는 OnDestroy에서 반드시 호출하세요.

Pro 기기 정책 heartbeat를 통해 서버에서 내려온 정책 액션을 받을 콜백을 등록합니다. 포털에서 Callback 대응 정책을 사용할 때 게임 코드가 후속 처리를 하도록 연결하는 용도이며, 로컬 보안 탐지 콜백과는 별도로 동작합니다.

이전에 등록한 정책 액션 콜백을 제거합니다. 씬 오브젝트에서 사용할 때는 OnEnable에서 등록하고 OnDisable에서 해제하세요.

사용자에게 보여 줄 활성화 또는 DRM 상태 변화를 받을 콜백을 등록합니다. OZero Managed Steam DRM과 기본 Managed Verification UI를 함께 쓰면 SDK가 온라인 필요, 재시도, timeout, 차단 상태를 이미 표시합니다. 커스텀 UI, telemetry, 게임 전용 session gate가 필요할 때만 등록하세요.

이전에 등록한 활성화 상태 콜백을 제거합니다. 씬 오브젝트에서 사용할 때는 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는 필요한 retry 흐름을 SDK 안에서 호출합니다. 기본 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

RegisterUserPolicyActionCallback으로 전달되는 서버 정책 콜백 페이로드입니다. 고객 포털 정책 시스템에서 발행되며, Pro 기기 정책 heartbeat를 통해 Unity 메인 스레드에서 전달됩니다.

정책 콜백 예시

고객 포털 보안 정책의 대응을 Callback으로 설정했을 때 사용합니다. SDK는 정책 액션을 게임으로 전달하고, 게임은 사용자 안내, 기능 제한, 화면 이동을 직접 결정합니다.

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

RegisterUserActivationStateCallback으로 전달되는 사용자 표시용 활성화 또는 DRM 상태 페이로드입니다. Steam Activation / DRM은 캐시된 오프라인 실행이 아직 허용되는지, 온라인 재검증이 필요한지를 이 이벤트로 게임에 알려줍니다.

활성화 상태 콜백 사용 기준

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 페이로드입니다. Build Integrity와 Steam DRM이 모두 이 이벤트를 사용하지만, 기본 Managed Verification UI를 쓰면 SDK가 자동으로 소비합니다. 게임 코드에서는 커스텀 UI, 별도 telemetry, 게임 전용 session gate가 필요할 때만 처리하세요.

Managed verification 콜백 사용 기준

managedVerificationUiPolicy가 OZero 기본 다이얼로그를 사용하면 SDK가 Build Integrity와 Steam DRM의 managed-verification UI, 재시도, timeout 상태를 이미 처리합니다. RegisterUserManagedVerificationStateCallback은 Custom UI / Callback Only, 별도 telemetry, 게임 전용 session gate에만 등록하세요. 커스텀 UI 모드에서는 Provider에 맞는 retry 메서드를 호출하고, 고객 게임 서버 모드에서는 SDK retry가 아니라 자체 로그인/세션 요청을 다시 보내세요.

OZeroManagedVerificationUiPolicy enum

Build Integrity와 Steam DRM에서 발생하는 managed verification 상태를 SDK가 플레이어에게 어떻게 표시할지 결정합니다. 두 Built-In 정책에는 TextMeshPro, TMP Essential Resources, optional OZero Built-In TMP Dialog package가 필요합니다. 이 조건 없이 Built-In 정책을 선택하면 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은 동등 연산자만 지원합니다. String은 ==, !=, +를 지원합니다. Buffer는 인덱스 연산자를 통해 바이트 배열에 직접 접근할 수 있습니다.

OZeroSafePlayerPrefs OZeroSDK.Security

Unity PlayerPrefs와 비슷한 방식으로 사용할 수 있는 암호화 저장소입니다. 키 이름과 값이 보호되어 Windows 레지스트리나 iOS 설정 파일을 직접 열어도 원래 값을 읽기 어렵습니다.

메서드

자주 쓰는 PlayerPrefs 스타일 메서드에 더해 Int64, Double, Bool, IncrementInt 헬퍼를 제공합니다. 기존 plain PlayerPrefs 값이 자동으로 이전되지는 않으므로, 앞으로 보호할 key부터 OZeroSafePlayerPrefs로 저장하세요.

OZeroSV_File OZeroSDK.Security

내부 암호화 로직으로 파일 읽기와 쓰기를 보호합니다. 기기 바인딩 키를 사용하지 않으므로 스팀 클라우드 세이브처럼 여러 기기에서 같은 세이브 파일을 읽어야 하는 경우에도 사용할 수 있습니다. 파일을 고의로 변조하면 읽는 시점에 무결성 검사가 실패하고 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 서버 검증을 처리하는 검증기입니다. Build Integrity가 OZeroSecurityConfig에서 활성화되면 SDK가 자동으로 생성합니다.

검사 항목

공개 속성

이벤트 및 메서드

활성화된 모든 로컬 검사가 통과하면 호출됩니다.

활성화된 로컬 검사 또는 Pro attestation이 빌드를 거부하면 호출됩니다.

Pro 서버 attestation이 성공하고 AttestationToken에 유효한 토큰이 들어오면 호출됩니다.

수동 검증을 시작합니다. 일반 프로젝트는 대시보드의 시작 시/주기적 검증 설정을 사용하는 편이 좋습니다.

OZeroBuildAttestationToken

Pro attestation 결과입니다. AttestToken을 게임 서버로 전달하고, 로그인, PvP, 랭킹, 재화 처리 같은 흐름에 사용하기 전에는 IsValid(nowMillis)로 유효성을 확인하세요.

서버가 발급한 만료 시간이 지난 경우 true를 반환합니다.

토큰 발급이 성공했고 아직 만료되지 않은 경우 true를 반환합니다.

OZeroSpeedHackDetector OZeroSDK.Security

5가지 독립적인 감지 신호를 사용하여 스피드핵과 시간 조작을 감지합니다. 신호들이 서로 확인할 때만 위협을 보고하여 오탐을 줄입니다.

감지 신호

감지는 ModulationType.SpeedHack 또는 ModulationType.TimeHack으로 OZeroSecurityManager 콜백을 통해 발생합니다. OZeroSecurityConfig에서 설정합니다.

OZeroWatchdog OZeroSDK.Security

신뢰할 수 있는 장시간 로딩 작업을 위한 public helper입니다. 릴리스 deadline보다 오래 Unity 메인 스레드를 막을 수 있는 동기 작업 구간에서 native Watchdog heartbeat deadline을 제한적으로 유예합니다.

메서드

제한된 loading grace scope를 시작합니다. 신뢰할 수 있는 로딩 작업이 끝나는 즉시 반환된 scope의 End()를 호출하거나 dispose하세요. 중첩 scope를 지원하며, 마지막 scope가 끝나면 정상 Watchdog 타이밍으로 돌아갑니다.

이 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에서 설정하면 충분합니다. 게임 안에 운영자용 메뉴나 QA용 스위치를 직접 제공하는 경우에만 사용하세요.

OZeroSteamDetectionAction

메서드

실행 중 Steam Anti-Piracy의 감지 후 동작을 바꿉니다. QA 빌드에서 임시로 Observe로 낮추거나, 운영자용 메뉴에서 특정 동작을 선택하게 만들 때 사용합니다.

실행 중 바꾼 Steam Anti-Piracy 동작을 해제하고 Config Dashboard 또는 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이 켜져 있으면 검증기는 자동으로 시작됩니다. 클라우드 세이브, 계정 세이브 슬롯 같은 데이터를 현재 기기와 묶고 싶을 때만 아래 토큰 메서드를 직접 호출하세요.

메서드

로컬 기기 지문을 준비한 뒤 등록하거나 검증합니다. 일반 프로젝트에서는 SDK 시작 시 자동으로 호출됩니다.

세이브 슬롯 키를 현재 기기에 연결하는 토큰을 만듭니다. 토큰은 세이브 메타데이터나 서버 기록에 저장하고, 플레이어가 직접 수정할 수 있는 세이브 본문에는 넣지 마세요.

저장된 세이브 슬롯 토큰이 현재 기기와 맞는지 확인합니다. 맞지 않으면 설정된 Device Binding 위반 응답이 발생합니다.

현재 기기 지문 해시를 반환하는 디버그/데모용 헬퍼입니다. 운영 게임 코드에서 화면에 보여주거나, 업로드하거나, 저장하지 마세요.

이 기기에 저장된 지문을 지웁니다. 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

디바이스가 서버에 연결할 수 없을 때, 서명된 Pro 포털 차단 정책을 어떻게 처리할지 정하는 enum입니다.

프로퍼티

Resources에서 런타임 설정을 로드합니다. null이면 Standard와 같은 방식으로 처리하세요.

Standard, Plus 또는 빈 라이선스 키이면 true입니다. Pro 활성화가 필요한 경우에만 false입니다.

Plus와 Pro에서 true입니다. Native Variant 검증 대상 등급을 식별하며, private Variant 존재 여부는 가져온 서명 manifest에서 자동 판별합니다.

OZeroLicenseRuntime OZeroSDK.Security.License

현재 라이선스 상태를 읽는 실행 중 API입니다. 앱 시작 시 자동 초기화되므로 대부분의 프로젝트는 상태를 읽거나 HasCapability만 호출하면 됩니다.

프로퍼티

메서드

여러 번 호출해도 안전한 시작 메서드입니다. 보통 SDK가 자동 호출하며, 커스텀 부트스트랩에서는 라이선스 상태를 읽기 전에 await할 수 있습니다.

현재 활성화 정보에 telemetry, signed_time, attestation 같은 기능 권한이 있는지 반환합니다. Standard에서는 false입니다.

라이선스 서버 런타임 호출

Pro 기능은 /v1 아래의 HTTPS JSON API를 사용합니다. 대부분의 호출은 SDK가 자동으로 수행합니다. 자체 게임 서버가 있는 팀은 /v1/validate로 OZA 토큰을 검증하고, 결제나 재화 지급처럼 중요한 액션에는 consumeToken=true를 사용해 같은 토큰 재사용을 막을 수 있습니다. 자체 서버가 없는 팀은 OZero 서버의 허용/경고/차단 결과를 사용할 수 있습니다.

POST /v1/activate 계약

Unity SDK가 Pro 라이선스를 활성화할 때 보내는 기본 요청 계약입니다. 서버 스키마는 네이티브 검증용 필드를 추가로 받을 수 있지만, 현재 SDK의 기본 활성화 요청은 아래 필드를 보냅니다.

OZeroAbortCode 및 이벤트 메시지

OZero가 보안 위협을 확정하면 OZeroSecurityEvent를 만들고, SDK 기본 대응 흐름과 프로젝트에서 등록한 콜백에 전달합니다. 이벤트에는 ModulationType, 안정적인 공개 OZeroAbortCode, MessageKey, 안전한 영문 Message, WillAbort가 포함됩니다.

중단 코드 및 메시지 표

로그나 다국어 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, 녹화 도구, 운영용 플러그인처럼 정상 동작하지만 Injection 검사에 잡힐 수 있는 모듈을 예외로 둘 때 사용합니다. 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 로그로 확인하세요.

Config — OZeroSecurityConfig.InjectionSettings

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

InjectionWhitelistEntries는 Injection 설정에 포함되는 로컬 신뢰 모듈 목록입니다. 고객 PC에 우연히 설치된 프로그램을 넓게 허용하기 위한 설정이 아니라, 개발사가 함께 배포하고 정상 동작을 확인한 모듈만 등록하는 곳입니다. 이 로컬 목록은 모든 티어에서 사용할 수 있고, Pro 고객은 고객 포털의 서버 관리 whitelist로 운영 중 같은 성격의 정책을 갱신할 수 있습니다.