본문으로 건너뛰기
버전: Next

Unity

Unity Plugin 기본 설명​

이 문서는 플러그인 방식을 사용하여 Unity 개발 환경에서 기존 SDK 적용 방식보다 더 쉽게 적용하는 방법을 제공하기 위해 작성되었습니다.

iOS 요구 사항​

  • Xcode 15.4 이상
  • Minimum OS 12.0 이상
  • AppGuard for iOS SDK v1.10.1.3 이상
  • AppGuard for Unity Plugin v1.1.1 이상
정보
  • Xcode 15.4 미만 버전에서 Minimum OS 버그가 존재합니다. 이 버그는 Xcode 15.4 버전부터 해결되었습니다.
  • AppGuard SDK v1.10.1.3 버전이상은 현재 Simulator를 지원하지 않습니다. 이 기능은 미래 버전에 추가될 예정입니다.

AppGuard Unity Plugin 구성 요소​

AppGuard for Unity Plugin v1.1.1 버전 이상의 구성 요소는 아래와 같습니다.

  • Assets/AppGuard/ 폴더 구성

    항목파일명설명플랫폼
    EditorAssets/AppGuard/Editor/AppGuardPostProcessBuild.csUnity에서 iOS용 Xcode Project 생성 시 필수 환경 설정Only iOS
    PluginsAssets/AppGuard/Plugins/iOS/AppGuardClientUnityBride.mmiOS Native ModuleOnly iOS
    ScriptAssets/AppGuard/Script/AppGuardUnityManager.cs
    Assets/AppGuard/Script/AppGuardSecureStream.cs    		Unity와 AppGuard Native 간의 통신 관리iOS/AOS
팁

AppGuard for Unity Plugin v1.1.1 버전 미만을 사용 중인 고객은 Migration 적용 전 기존에 사용한 Unity Plugins 파일(AppGuardPostProcessBuild.cs, AppGuardSecureStream.cs, AppGuardClientUnityBride.mm)을 미리 백업하시기 바랍니다.
백업 후, 해당 파일들을 Unity 프로젝트에서 삭제한 후 진행해주시기 바랍니다.

AppGuard Unity Plugin 구성 설명​

AppGuardPostProcessBuild.cs​

Unity Editor에서 제공하는 PostProcessBuild 기능을 사용하여 Unity에서 생성한 Xcode Project에 다음 기능을 수행합니다:

  • AppGuard SDK 구동에 필요한 빌드 환경 파일 설정
  • AppGuard SDK 구동에 필요한 환경 파일 설정

주의

AppGuardPostProcessBuild.cs 파일을 반드시 확인하고, 고객사의 환경과 다른 경우 수정이 필요할 수 있습니다.

AppGuardUnityManager.cs​

Assets/AppGuard/Scripts/ 에 위치한 AppGuardUnityManager.cs는 AppGuard Native Module과의 통신을 관리하는 모듈입니다.
이 파일의 클래스명 및 메서드명은 그대로 유지해야 하며, 주요 메서드는 다음과 같습니다:

  • Set 메서드

    메서드설명
    public void setUserId(string userid)보안 정책 위반 탐지 시 로그 서버로 전송할 사용자 식별자(UserID)를 설정합니다.
    public void setUniqueClientId(string uniqueId, long retryTimeSec = 180)서버 인증에 사용할 세션 유일 식별자를 설정합니다.

  • Callback 메서드

    메서드설명
    public void setAppGuardS2AuthCallback(Action<int, string> callback)AppGuard Native Module에서 수행한 서버 인증 결과를 수신할 callback method를 설정합니다.
    public void setAppGuardDetectCallback(Action<string> callback)AppGuard Native Module에서 수행한 보안 정책 위반 탐지 결과를 수신할 callback method를 설정합니다.

Unity Project 적용 사항​

AppGuard for Unity Plugin 다운로드 및 설정​

AppGuard for Unity Plugin v1.1.1 버전 이상을 설치하고, Unity에서 프로젝트를 구성하는 방법은 다음과 같습니다:

  • 1. AppGuard 매니저 서버에 접속하여 Download > Unity Plugins 를 선택하고 최신 버전을 다운로드합니다.

  • 2. 다운로드된 AppGuardUnityPlugin.zip 파일을 압축 해제하면 내부에 Assets 폴더가 있습니다.

  • 3. 압축 해제된 Assets 폴더 내 AppGuard/ 폴더를 Unity Project/Asset/ 경로에 복사합니다.

AppGuard SDK 적용​

  • 1. AppGuard 매니저 서버에 접속하여 Download > AppGuard Module 를 선택하고 iOS SDK 최신 버전을 다운로드합니다.

  • 2. 다운로드된 AppGuard_for_iOS.zip 파일을 압축 해제합니다.

  • 3. AppGuard SDK v1.10.1.3 버전인 경우 압축 해제하면 내부에 AppGuardCore.framework 존재하며, 이를 복사합니다.

    정보

    AppGuard for iOS SDK v1.10.2.0 버전 이상은 애플(Apple)측 요구사항에 맞게 static framework로 제작되었으며, AppGuardCore.xcframework 명칭으로 배포됩니다.
    따라서, AppGuard SDK v1.10.2.0 버전 이상인 경우 압축 해제하면 내부에 AppGuardCore.xcframework가 존재하며, AppGuardCore.xcframework/ios-arm64/ AppGuardCore.framework를 복사하여 진행합니다.

  • 4. 복사한 AppGuardCore.framework을 아래 경로에 복사합니다:
    Copy To : Project/Assets/AppGuard/Plugins/iOS/

AppGuard Config 파일 다운로드 및 설정​

  • 1. AppGuard 매니저 서버에 접속하여 Applying Security > 다운로드 > CHAPTER 2. nProtect AppGuard CONFIG 파일 다운로드 > CONFIG FILE DOWNLOAD를 선택하여 다운로드합니다.

  • 2. 다운로드된 Config 파일을 압축 해제하면 AppGuard Config 파일은 appguard, appguard.crt, appguard.mf, appguard106000 4개의 파일로 구성됩니다.

  • 3. 이 4개의 파일을 아래 경로에 복사합니다:
    Copy To : Project/Assets/AppGuard/Plugins/iOS/

팁

AppGuard for Unity Plugin v1.1.1 버전 미만을 사용하던 고객의 경우, 기존 appguard, appguard106000, appguard.mf, appguard.crt 파일을 Assets/AppGuard/Plugins/iOS/ 위치로 이동해야 합니다.

보안 정책 위반 탐지 관련 이벤트용 콜백 함수 등록 및 사용(필수)​

보안 정책 위반 탐지 관련 이벤트 통신을 위한 앱의 콜백 함수를 설정하기 위해 Unity 프로젝트의 첫 번째 장면(Scene) 클래스의 Awake() 메서드에서 아래 샘플 코드와 같이 작업합니다.
빌드된 IPA를 AppGuard 매니저 웹 서비스를 통해 앱 서명을 완료한 후, 앱 실행 시 보안 정책 위반이 발생하면 setAppGuardDetectCallback() 함수에 등록된 AppGuardDetectCallback() 콜백 함수로 이벤트가 전달됩니다.

팁

AppGuard for Unity Plugin v1.1.1 버전 미만을 사용하던 고객은, 기존 AppGuardUnityManager의 onViolationCallback() 메소드에 추가하여 사용하던 코드를 새로 작성한 고객사의 callback method로 이동해야 합니다.

아래 샘플 코드와 같이 사용자는 우선적으로 AppGuard 보안 탐지 및 등록을 위한 AppGuardDetectCallback() 함수를 구현해야 합니다. 해당 AppGuardDetectCallback() 콜백 함수에서 보안 탐지 결과에 따른 처리를 할 수 있습니다.

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. AppGuard 보안 정책 위반 탐지 관련 이벤트 통신을 위한 Callback Method를 설정합니다.
        AppGuardUnityManager.Instance.setAppGuardDetectCallback((data) => {
            bool killed = (int.Parse(data) > 0);
            
            if(killed) {
                //. 수신한 보안 정책 위반 탐지 값이 양수인 경우 앱을 종료 처리합니다.
                int code = Mathf.Abs(int.Parse(data));
                //. 이곳에 종료 메시지 처리를 위한 코드를 추가합니다.
            }
        });
    }
}

또는 아래와 같이 보안 정책 탐지 관련 이벤트 Callback 메서드를 따로 구현 후 등록하는 방법도 가능합니다.

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. 보안 정책 탐지 결과를 수신할 Callback Method를 설정합니다.
        //. AppGuard 초기화 함수 호출 전 보안 정책 탐지 결과 Callback 함수를 우선적으로 등록하는 것이 좋습니다.
        AppGuardUnityManager.Instance.setAppGuardDetectCallback(AppGuardDetectCallback);
    }

    //. 보안 정책 탐지 결과를 수신할 Callback Method를 아래와 같이 작성합니다.
    //. Callback Method의 명칭은 parameter 값을 유지한다면 자유롭게 작성하셔도 무방합니다.    
    void AppGuardDetectCallback(string data) {
        bool killed = (int.Parse(data) > 0);
        
        if(killed) {
            //. killed 값이 true인 경우 앱을 종료 처리합니다.
            int code = Mathf.Abs(int.Parse(data));
            //. 이곳에 종료 메시지 처리를 위한 코드를 추가합니다.
        }
    }
}
주의

서비스 릴리스 시 샘플에 포함된 Debug.Log("-Debug Message-"); 코드를 반드시 제거해 주시기 바랍니다.

서버 인증 이벤트용 콜백 함수 등록 및 사용 (선택)​

이 내용은 서버 인증 사용 시 필요한 내용이며, 서버 인증을 사용하지 않을 경우 아래 내용은 해당되지 않습니다.

빌드된 IPA를 AppGuard 매니저 웹 서비스를 통해 앱 서명을 완료한 후, 앱 실행 시 서버 인증 결과가 setAppGuardS2AuthCallback() 함수에 등록된 AppGuardS2AuthCallback() 콜백 함수로 전달됩니다.

팁

AppGuard for Unity Plugin v1.1.1 버전 미만을 사용하던 고객의 경우, 기존 AppGuardUnityManager의 onS2AuthTryCallback() 메소드에 추가하여 사용하던 코드를 새로 작성한 고객사의 callback method로 이동해야 합니다.

아래 샘플 코드와 같이 사용자는 AppGuard 서버 인증 및 등록을 위한 AppGuardS2AuthCallback() 함수를 구현해야 합니다.
해당 AppGuardS2AuthCallback() 콜백 함수에서 서버 인증 상태 결과에 따른 처리를 할 수 있습니다.

Main.cs
public class testMain : MonoBehaviour
{
    void ExampleServerAuthRequest(string uniqueId) {
        //. 서버 인증 결과를 수신하기 위한 Callback Method를 설정합니다.
        AppGuardUnityManager.Instance.setAppGuardS2AuthCallback((result, uniqueClientId) => {
            switch (result) {
                case AppGuardEventType.S2Auth.S2AUTH_RESULT_SUCCESS:
                    //. 서버 인증이 성공하였으며, 정상적으로 인증이 완료되었습니다.
                    Debug.Log ("[TESTMAIN] S2AUTH_RESULT_SUCCESS (UniqueID: " + uniqueClientId + ")");
                    break;

                case AppGuardEventType.S2Auth.S2AUTH_RESULT_RETRY:
                    //. 서버 인증이 실패하였으며, 재인증을 시도할 것입니다. 
                    //. 일시적인 클라이언트 네트워크 장애 또는 서버 장애일 수 있으며, 
                    //. 해당 재시도는 내부 메커니즘에 따라 최대 3분 동안 수행될 수 있습니다.
                    Debug.Log ("[TESTMAIN] S2AUTH_RESULT_RETRY");
                    break;

                case AppGuardEventType.S2Auth.S2AUTH_RESULT_FAIL:
                    //. 서버 인증이 완전히 실패하였으며, 더 이상 서버 인증을 시도하지 않습니다.
                    Debug.Log ("[TESTMAIN] S2AUTH_RESULT_FAIL");
                    break;
            }
        });
        //. 고객사의 서버 인증용 ID를 사용하여 서버 인증을 수행합니다.
        AppGuardUnityManager.Instance.setUniqueClientId(uniqueId,180);
    }
}

또는 아래와 같이 서버 인증 결과 관련 이벤트 Callback 메서드를 따로 구현 후 등록하는 방법도 가능합니다.

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. 서버 인증 상태 결과를 수신할 Callback Method를 설정합니다.
        //. AppGuard 초기화 함수 호출 전 서버 인증 Callback 함수를 우선적으로 등록하는 것이 좋습니다.
        AppGuardUnityManager.Instance.setAppGuardS2AuthCallback(AppGuardS2AuthCallback);
    }

    void AppGuardS2AuthCallback(int type, string id) {
        switch (type) {
            case AppGuardEventType.S2Auth.S2AUTH_RESULT_SUCCESS:
                //. 서버 인증이 성공하였으며, 정상적으로 인증이 완료되었습니다.
                Debug.Log ("[TESTMAIN] S2AUTH_RESULT_SUCCESS (UniqueID: " + id + ")");
                break;

            case AppGuardEventType.S2Auth.S2AUTH_RESULT_RETRY:
                //. 서버 인증이 실패하였으며, 재인증을 시도할 것입니다. 
                //. 일시적인 클라이언트 네트워크 장애 또는 서버 장애일 수 있으며, 
                //. 해당 재시도는 내부 메커니즘에 따라 최대 3분 동안 수행될 수 있습니다.
                Debug.Log ("[TESTMAIN] S2AUTH_RESULT_RETRY");
                break;

            case AppGuardEventType.S2Auth.S2AUTH_RESULT_FAIL:
                //. 서버 인증이 완전히 실패하였으며, 더 이상 서버 인증을 시도하지 않습니다.
                Debug.Log ("[TESTMAIN] S2AUTH_RESULT_FAIL");
                break;
        }
    }

    void OnGUI () {
        if (GUI.Button (new Rect (10,550,200,80), "Server Auth Test")) {
            //. 서버 인증 결과를 수신할 Callback Method를 설정합니다.
            AppGuardUnityManager.Instance.setAppGuardS2AuthCallback(AppGuardS2AuthCallback);
            
            //. 고객사의 게임 서버에서 서버 인증용 ID를 수신합니다.
            //. getReciveUniqueIdFromGameServer() 메서드는 예제를 위해 작성된 메서드이며, 실제 존재하는 메서드가 아닙니다.
            string uniqueId = getReciveUniqueIdFromGameServer();
            
            //. AppGuard for Unity Plugin의 서버 인증 메서드를 호출하여 서버 인증을 수행합니다.
            AppGuardUnityManager.Instance.setUniqueClientId(uniqueId, 180);
        }
    }
}
주의

서비스 릴리스 시 샘플에 포함된 Debug.Log("-Debug Message-"); 코드를 반드시 제거해 주시기 바랍니다.

서버 인증 시작하기​

클라이언트에서 서버 인증을 시작하려면 아래 샘플 코드와 같이 서버에서 수신한 사용자의 세션에 대한 Unique Client ID를 사용하여 다음 메서드를 호출할 수 있습니다.

AppGuardUnityManager.cs
AppGuardUnityManager.Instance.setUniqueClientId("Formatted-Unique-Client-Id", 180);
팁

setUniqueClientId() 함수의 첫 번째 인자로 주어진 Formatted-Unique-Client-Id의 규칙 및 생성 방법은 [서버 인증] 을 참고하시기 바랍니다.

정보

여기까지 적용 작업을 완료한 경우 iOS 플랫폼 빌드를 진행해주시기 바랍니다.

Xcode Project 적용 사항​

  • AppGuard SDK 확인
    • Xcode Project를 열고, Xcode Project > TARGETS:UnityFramework > General > Frameworks and Libraries 내 AppGuardCore.framework 속성이 Do not Embed 로 설정되었는지 확인해주시기 바랍니다.

    정보

    Xcode Project에 AppGuardCore.framework가 정상적으로 추가된 경우, 최근 Apple 정책 및 Xcode 15.x 호환과 Privacy Manifests 적용을 위해 아래 [AppGuard SDK Privacy Manifests 적용] 사항을 참고하여 진행해주시기 바랍니다.

AppGuard SDK Privacy Manifests 적용​

해당 가이드는 Privacy Manifests 적용을 위해 AppGuard SDK v1.10.1.3 버전 이상을 사용해야 합니다.

AppGuardCore.framework 모듈은 AppGuardCore.framework를 Link하는 TARGETS에 병합되고 배포됩니다.

Apple Privacy Manifests와 관련된 PrivacyInfo.xcprivacy는 AppGuard SDK를 Link한 TARGETS의 PrivacyInfo.xcprivacy에 AppGuardCore.framework의 PrivacyInfo.xcprivacy 내용이 명시되어야 합니다.

정보

[Unity Engine & Privacy Manifests]

An Apple Unity application can contain multiple frameworks (eg Ads or Social SDKs). Each framework can contain a single Privacy Manifest file. Out of the box, Unity applications have a single framework for the Unity project, called UnityFramework. Multiple Privacy Manifest files coming from different plugins, packages integrated into your Unity project, or first-party (your Unity project) will have to be combined into a single Privacy Manifest file inside of Unity Framework. Future Unity versions will do this automatically, but Unity developers with projects stuck on older Unity versions will have to do this manually.

Unity Engine & Privacy Manifests 참고 링크 : Unity Engine & Privacy Manifests

즉, Unity Engine & Privacy Manifests 안내에 따라 Unity의 경우 UnityFramework.framework에서 자체적인 PrivacyInfo.xcprivacy 파일이 추가되고, AppGuard SDK의 PrivacyInfo.xcprivacy 내용이 UnityFramework.framework 내부의 PrivacyInfo.xcprivacy 에 병합되어야 합니다.

PrivacyInfo.xcprivacy에 AppGuardCore.framework 관련 내용을 명시하기 위해 아래 가이드를 참고하여 병합 작업을 수행하시기 바랍니다.

  • AppGuard SDK를 Link한 TARGETS(예: UnityFramework)에서 이미 사용 중인 PrivacyInfo.xcprivacy 파일이 존재하는 경우

    • AppGuardCore.framework 내부의 PrivacyInfo.xcprivacy 파일 내용과 기존에 사용 중인 PrivacyInfo.xcprivacy를 비교하여 누락된 부분을 확인합니다.
    • 누락된 부분이 발견되면 TARGETS에서 이미 사용 중인 PrivacyInfo.xcprivacy 파일에 추가 및 병합해주시기 바랍니다.

  • AppGuard SDK를 Link한 TARGETS(예: UnityFramework)에서 PrivacyInfo.xcprivacy 파일이 존재하지 않는 경우

    • AppGuardCore.framework 내부의 PrivacyInfo.xcprivacy 파일을 복사하여 Xcode Project 내에 추가합니다.

    • 프로젝트를 열고 Project > TARGETS:UnityFramework > Build Phases > Copy Bundle Resources를 차례로 선택하고, 하단의 추가[+] 버튼을 클릭합니다.

    • [Choose items to add:] 창에서 하단의 [Add Other] 버튼을 클릭합니다.

    • 프로젝트 내에 복사한 PrivacyInfo.xcprivacy 파일을 선택하고, [Open] 버튼을 클릭합니다.

    • [Choose options for adding these files:] 창에서 [Destination:Copy items if needed] 을 체크하고, [Added folders:Create groups] 으로 체크한 후, 우측 하단의 [Finish] 버튼을 클릭합니다.

    • 프로젝트 내 [Copy Bundle Resources] 에 PrivacyInfo.xcprivacy 파일이 추가되었는지 확인합니다.

팁

AppGuard for iOS SDK v1.10.1.3 버전 이상은 AppGuardCore.framework라는 이름으로 배포되며, 해당 SDK는 static framework로 제작 및 배포됩니다.

AppGuard for iOS SDK v1.10.1.3 버전 이상은 Apple이 요구하는 Privacy Manifest에서 명시된 Required reason API 항목 중 NSPrivacyAccessedAPICategoryUserDefaults 외에 다른 API는 사용하지 않음을 참고하시기 바랍니다.

Static framework로 링크되는 타사 SDK도 AppGuard SDK와 마찬가지로 고객사의 PrivacyInfo.xcprivacy에 병합 작업이 필요할 수 있습니다.

정보

여기까지 적용을 완료하면 AppGuard SDK 적용이 완료됩니다.