Unity
Unity Plugin 기본 설명
해당 문서는 플러그인 방식을 사용하여 Unity 개발 환경에서 기존 SDK 적용 방식보다 보다 손쉽게 적용하는 방법을 제공하기 위하여 작성되었습니다.
Plugin 다운로드 및 설치하기
Unity Plugin을 설치하고, Unity에서 프로젝트를 구성하는 방법은 다음과 같습니다.
-
AppGuard 매니저 서버에 접속하여 Download > Unity Pluings 를 선택하여 최신 버전으로 다운로드합니다.
-
다운로드된
AppGuardUnityPlugin.zip파일을 압축해제 시 내부의 Assets 폴더가 존재하며,
내부의AppGuardPostProcessBuild.cs,AppGuardUnityManager.cs파일과 /Plugins 폴더를 Project/Asset/ 경로 내에 복사합니다.
만약 컴파일 시 Assets/ AppGuardUnityManager.cs 만 존재하고 /Assets/Plugins * 폴더가 복사되지 않을 경우
오류("Error: Symbol(s) not found for a architecture arm64")가 발생할 수 있음을 주의해야 합니다.
AppGuard Config 파일 다운로드 및 설정하기
-
AppGuard 매니저 서버에 접속하여 Applying Security > 다운로드 > CHAPTER 2. nProtect AppGuard CONFIG 파일 다운로드 > CONFIG FILE DOWNLOAD 를 선택하여 다운로드합니다.
-
다운로드된 Config 파일을 압축 해제 시 AppGuard Config 파일은
appguard,appguard.crt,appguard.mf,appguard1060004개의 파일로 구성되어있습니다. -
위 4개의 파일을 아래의 경로에 복사합니다.
Copy To : Project/Assets/
AppGuardPostProcessBuild.cs 설명
AppGuardPostProcessBuild.cs는 Unity Editor에서 제공하는 PostProcessBuild 기능을 사용하여 Unity에서 생성하는 Xcode Project 에 아래의 기능을 수행합니다.
- AppGuard SDK 구동에 필요한 빌드 환경파일 설정 작업
- AppGuard SDK 구동에 필요한 환경파일 설정 작업
- Unity에서 선택한 Target SDK별
AppGuardCore.xcframework링크 설정 작업
하지만, Unity에서 생성되는 Xcode Project의 경우 xcframewrok 포맷을 정상적으로 인식하지 못하는 상태입니다. 이는 Unity 자체에서 미지원되는 부분으로 판단됩니다.
이에 대한 대응 방안으로 잉카인터넷에서는 AppGuardPostProcessBuild.cs 파일을 통해 Unity에서 선택한 Target SDK에 따라 필요한 framework를 링크하는 기능을 제공하고 있습니다.
AppGuard for iOS SDK v1.8.6 부터는 iOS용 SDK의 배포 방식이 기존 단일 framework 방식에서 다중 framework를 지원하는
xcframework 포맷으로 배포됩니다.
따라서, AppGuard for iOS SDK의 명칭이 AppGuardCore.framework에서 AppGuardCore.xcframework로 변경되었으며,
AppGuardCore.xcframework는 Unity의 Device SDK와 Simulator SDK 빌드 및 실행을 모두 지원합니다.
xcframework는 다중 플랫폼 지원을 위한 framework 배포를 위해 애플에서 권장하는 포맷입니다.
AppGuard 1.8.6 버전 미만 및 Xcode 13.3.3 버전 미만 환경을 사용하는 고객사의 경우
AppGuardCore.xcframework/ios-arm64_armv7/ AppGuardCore.framework를
Project/Assets/Plugins/AppGuardCore.xcframework/ios-arm64/ 폴더로 복사하여 사용하시면 기존과 같은 방식으로 사용하실수 있습니다.
AppGuard 1.8.6 버전 이상 및 Xcode 13.3.3 버전 이상 환경을 사용하는 고객사의 경우
AppGuardCore.xcframework/ios-arm64/ AppGuardCore.framework를 사용하시면 기존과 같은 방식으로 사용하실수 있습니다.
AppGuardPostProcessBuild.cs 파일을 꼭 확인하시고, 고객사의 환경과 다른 경우 수정이 필요할 수 있습니다.
AppGuardUnityManager.cs 설명
구성 파일인 Assets/ 폴더의 AppGuardUnityManager.cs는 서버인증을 위한 Unity Plugin 샘플로,
해당 *.cs 파일 내의 존재하는 클래스명 및 메서드 명은 유지되어야 하며,
아래 나열된 메서드를 사용하거나 수정하여 사용하실 수 있습니다.
Set 메서드
| 메서드 | 설명 |
|---|---|
public void setUserId(string userid) | 보안 정책 위반 탐지 시 로그 서버로 전송함 사용자 식별자 (UserID)를 설정합니다 |
public void setUniqueClientId(string uniqueId, long retryTimeSec = 180) | 서버 인증에 사용할 세션 유일 식별자를 설정합니다. |
Callback 메서드
| 구성 파일 및 폴더 | 설명 |
|---|---|
public void onViolationCallback(string data) | 보안 정책 위반 탐지 관련 이벤트 Callback을 수신 받는 메서드로 보안 정책 위반이 탐지 시 AppGuard 는 해당 메소드를 호출하며 상태정보를 전달합니다. |
public void onS2AuthTryCallback(string data) | 서버 인증 관련 이벤트 Callback을 수신 받는 메서드로 서버 인증이 진행되면 AppGuard는 해당 메소드를 호출하며 상태 정보를 전달합니다. |
AppGuardUnityManager.cs은 함께 추가로 배포되는 SDK 또는 Framework를 사용하는 방법에 대한 샘플을 제공합니다.
AppGuard SDK Unity Plugin 적용
AppGuard 초기화 함수 호출하기
AppGuard와 통신을 위한 앱의 콜백 함수를 AppGuard에 등록하기 위한 start() 메소드를 제공합니다.
해당 함수의 호출 시점은 앱 실행 시 가장 먼저 실행되는 시점에 적용하기 위하여
Unity 프로젝트의 첫번째 장면(Scene) 클래스의 Awake() 메서드에서 호출되어야 합니다.
아래 샘플 코드와 같이 Awake() 함수 내 AppGuardUnityManager.Instance.start()를 호출하여 적용할 수 있습니다.
void Awake() {
AppGuardUnityManager.Instance.start();
}
onViolationCallback 콜백 수정하기
해당 *.cs 파일이 적용되고, 빌드된 IPA를 AppGuard 매니저 웹 서비스를 통하여 앱서명을 수행한 상태일 경우
App 실행 시 보안 정책 위반 행위가 탐지될 때 아래 언급된 Callback 메서드를 통하여 이벤트가 전달됩니다.
따라서, 콜백 메서드를 수정하여 이벤트 상태에 따른 행동을 정의할 수 있습니다.
하지만 기본적으로 보안 정책 위반에 따른 조치 사항을 AppGuard에 위임한 경우 해당 메서드를 아래와 같이 빈(Empty) 루틴으로 처리하시면 됩니다.
아래 샘플 코드와 같이 해당 data 인자 값이 양수를 가지면 설정된 정책 설정값에 따라 AppGuard는 약 30초 후 강제 종료를 수행하며,
사용자에게 앱이 종료될 것이라는 메시지를 해당 위치에서 노출하는 코드가 onViolationCallback() 메서드 내에 구현하여 사용할 수 있습니다.
public void onViolationCallback(string data) {
bool killed = (int.Parse(data) > 0);
if (killed) {
int code = Mathf.Abs(int.Parse(data));
switch (code) {
case AppGuardEventType.Detect.DETECT_RUNNING_BAD_APPLICATION:
Debug.Log("DETECT_RUNNING_BAD_APPLICATION");
break;
default:
Debug.Log ("ViolationCallback: " + data);
break;
}
}
}
실제 서비스 Release 시 샘플에 포함된 Debug.Log(“-Debug Message-“); 코드를 반드시 제거해 주시기 바랍니다.
UserID 설정하기
AppGuardUnityManager.cs 샘플에는 AppGuard에서 정책 위반 탐지 시 로그 서버에 User ID를 함께 등록하기 위한 setUserId() 메소드를 제공합니다.
아래 샘플 코드와 같이 "userID" 부분에 실재 해당 세션의 사용자 ID를 string 형태의 데이터로 함께 호출하여 사용할 수 있습니다.
AppGuardUnityManager.Instance.setUserId("userID");
서버인증 적용(선택)
본 내용은 서버인증 사용시 필요한 내용이며, 서버인증 미사용 시에는 아래의 내용을 무시하셔도 됩니다.
onS2AuthTryCallback 콜백 수정하기
해당 *.cs 파일이 적용되고, 빌드된 IPA를 AppGuard 매니저 웹 서비스를 통하여 앱서명을 수행한 상태일 경우
아래 언급된 Callback 메서드를 통하여 서버인증 동작 이벤트가 전달됩니다.
따라서, 콜백 메서드를 수정하여 이벤트 상태에 따른 행동을 정의할 수 있습니다.
아래 샘플 코드와 같이 서버인증 상태 결과를 onS2AuthTryCallback() 콜백 메서드를 통해 확인할 수 있습니다.
public void onS2AuthTryCallback(string data) {
// 서버인증 상태에 따른 특별한 조치 사항
string[] args = data.Split(',');
switch (int.Parse(args[0])) {
case AppGuardEventType.S2Auth.S2AUTH_RESULT_SUCCESS:
/*
서버 인증이 성공하였으며, 정상적으로 인증이 완료되었습니다.
*/
Debug.Log ("S2AUTH_RESULT_SUCCESS(UniqueID: " + args[1] + ")");
break;
case AppGuardEventType.S2Auth.S2AUTH_RESULT_RETRY:
/*
서버 인증이 실패하였으며, 재인증을 시도합니다.
일시적인 클라이언트 네트워크 장애 또는 서버 장애일 수 있으며,
해당 재시도는 내부 메커니즘에 따라 최대 3분 동안 수행될 수 있습니다.
*/
Debug.Log ("S2AUTH_RESULT_RETRY");
break;
case AppGuardEventType.S2Auth.S2AUTH_RESULT_FAIL:
/*
서버 인증이 완전히 실패하였으며, 더 이상 서버 인증을 시도하지 않습니다.
*/
Debug.Log ("S2AUTH_RESULT_FAIL");
break;
}
}
서버인증 상태에 따른 특별한 조치 사항이 없을 경우 해당 메서드를 아래와 같이 빈(Empty) 루틴으로 처리하시면 됩니다.
아래의 [AppGuardUnityManager.cs 의 서버인증 시작하기] 설명과 같이 AppGuardUnityManager.Instance() 호출을 통하여 생성된 객체에서
setUniqueClientId() 메서드를 호출하면 해당 시점부터 AppGuard 보안 모듈이 서버 인증을 시도하며, 위 샘플 코드에 예시된 것과 같이 3가지의 서버인증 상태를 콜백 메서드로 전달합니다.
실제 서비스 Release 시 샘플에 포함된 Debug.Log(“-Debug Message-“); 코드를 반드시 제거해 주시기 바랍니다.
서버 인증 시작하기
클라이언트에서 서버 인증을 시작하기 위해서는 아래 샘플 코드와 같이 서버에서 수신한 해당 사용자의 세션에 대한 Unique Client ID를 아래와 같은 메서드를 호출하여 사용할 수 있습니다.
AppGuardUnityManager.Instance.setUniqueClientId("Formatted-Unique-Client-Id", 180);
위 함수의 첫번째 인자로 주어진 Formatted-Unique-Client-Id의 규칙 및 생성 방법은 [서버인증] 를 참고하여 주시기 바랍니다.