Version: 1.10.x

Unity

Basic Description of Unity Plugin

This document is written to provide a method to apply in the Unity development environment more easily using a plugin approach compared to the existing SDK application method.

iOS Requirements

Xcode 15.4 or later
Minimum OS 12.0 or later
AppGuard for iOS SDK v1.10.1.3 or later
AppGuard for Unity Plugin v1.1.1 or later

info

There is a Minimum OS bug in Xcode versions below 15.4. This bug has been resolved starting from Xcode version 15.4.
AppGuard SDK v1.10.1.3 and later do not currently support the Simulator. This feature will be added in future versions.

AppGuard Unity Plugin Components

The components of AppGuard for Unity Plugin v1.1.1 or later are as follows:

Assets/AppGuard/ folder structure

Item	File Name	Description	Platform
Editor	`Assets/AppGuard/Editor/AppGuardPostProcessBuild.cs`	Required environment settings when creating an Xcode Project for iOS in Unity	Only iOS
Plugins	`Assets/AppGuard/Plugins/iOS/AppGuardClientUnityBride.mm`	iOS Native Module	Only iOS
Script	`Assets/AppGuard/Script/AppGuardUnityManager.cs` `Assets/AppGuard/Script/AppGuardSecureStream.cs`	Manages communication between Unity and AppGuard Native	iOS/AOS

tip

Customers using AppGuard for Unity Plugin versions below v1.1.1 should back up the previously used Unity Plugins files (AppGuardPostProcessBuild.cs, AppGuardSecureStream.cs, AppGuardClientUnityBride.mm) before applying Migration. After backing up, please delete these files from the Unity project and proceed.

Description of AppGuard Unity Plugin Components

AppGuardPostProcessBuild.cs

Using the PostProcessBuild feature provided by the Unity Editor, the following functions are performed on the Xcode Project created in Unity:

Setting build environment files required for running AppGuard SDK
Setting environment files required for running AppGuard SDK

caution

Be sure to check the AppGuardPostProcessBuild.cs file, and modifications may be necessary if it differs from the customer’s environment.

AppGuardUnityManager.cs

Located in Assets/AppGuard/Scripts/, AppGuardUnityManager.cs is a module that manages communication with the AppGuard Native Module. The class name and method names in this file must remain unchanged, and the main methods are as follows:

Set Methods

Method	Description
`public void setUserId(string userid)`	Sets the user identifier (UserID) to be sent to the log server upon detecting a security policy violation.
`public void setUniqueClientId(string uniqueId, long retryTimeSec = 180)`	Sets the session unique identifier to be used for server authentication.

Callback Methods

Method	Description
`public void setAppGuardS2AuthCallback(Action<int, string> callback)`	Sets the `callback method` to receive the server authentication results performed by the AppGuard Native Module.
`public void setAppGuardDetectCallback(Action<string> callback)`	Sets the `callback method` to receive the security policy violation detection results performed by the AppGuard Native Module.

Unity Project Application Details

Download and Setup of AppGuard for Unity Plugin

To install AppGuard for Unity Plugin v1.1.1 or later and configure the project in Unity, follow these steps:

1. Access the AppGuard manager server, select Download > Unity Plugins, and download the latest version.
2. Extract the downloaded AppGuardUnityPlugin.zip file, which contains the Assets folder inside.
3. Copy the AppGuard/ folder inside the extracted Assets folder to the Unity Project/Asset/ path.

Application of AppGuard SDK

1. Access the AppGuard manager server, select Download > AppGuard Module, and download the latest version of the iOS SDK.
2. Extract the downloaded AppGuard_for_iOS.zip file.
3. If it is AppGuard SDK v1.10.1.3, the extracted contents include AppGuardCore.framework, which should be copied.

info
AppGuard for iOS SDK v1.10.2.0 or later is made as a static framework according to Apple's requirements and is distributed under the name AppGuardCore.xcframework.
Therefore, if it is AppGuard SDK v1.10.2.0 or later, the extracted contents include AppGuardCore.xcframework, and you should proceed by copying AppGuardCore.xcframework/ios-arm64/ AppGuardCore.framework.
4. Copy the AppGuardCore.framework to the following path:
Copy To: Project/Assets/AppGuard/Plugins/iOS/

Download and Setup of AppGuard Config File

1. Access the AppGuard manager server, select Applying Security > Download > CHAPTER 2. nProtect AppGuard CONFIG FILE DOWNLOAD > CONFIG FILE DOWNLOAD, and download the file.
2. Extract the downloaded Config file, which consists of four files: appguard, appguard.crt, appguard.mf, appguard106000.
3. Copy these four files to the following path:
Copy To: Project/Assets/AppGuard/Plugins/iOS/

tip

For customers using AppGuard for Unity Plugin versions below v1.1.1, the existing appguard, appguard106000, appguard.mf, appguard.crt files should be moved to the Assets/AppGuard/Plugins/iOS/ location.

Registration and Use of Callback Functions for Security Policy Violation Detection Events (Required)

To set up the app's callback function for communication related to security policy violation detection events, perform the following tasks in the Awake() method of the first Scene class in the Unity project as shown in the sample code below.
After completing the app signature through the AppGuard manager web service with the built IPA, if a security policy violation occurs when running the app, the event is delivered to the AppGuardDetectCallback() callback function registered in the setAppGuardDetectCallback() function.

tip

For customers using AppGuard for Unity Plugin versions below v1.1.1, the code that was added to the existing onViolationCallback() method of AppGuardUnityManager should be moved to the newly written customer’s callback method.

As shown in the sample code below, users should first implement the AppGuardDetectCallback() function for AppGuard security detection and registration. In the AppGuardDetectCallback() callback function, processing according to the security detection result can be performed.

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. Set the Callback Method for communication related to security policy violation detection events.
        AppGuardUnityManager.Instance.setAppGuardDetectCallback((data) => {
            bool killed = (int.Parse(data) > 0);
            
            if(killed) {
                //. If the received security policy violation detection value is positive, terminate the app.
                int code = Mathf.Abs(int.Parse(data));
                //. Add code here for handling termination messages.
            }
        });
    }
}

Alternatively, you can implement and register the callback method for security policy detection-related events separately as shown below.

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. Set the Callback Method to receive the security policy detection results.
        //. It is recommended to register the security policy detection result Callback function before calling the AppGuard initialization function.
        AppGuardUnityManager.Instance.setAppGuardDetectCallback(AppGuardDetectCallback);
    }

    //. Write the Callback Method to receive the security policy detection results as shown below.
    //. The name of the Callback Method can be freely written as long as the parameter values are maintained.    
    void AppGuardDetectCallback(string data) {
        bool killed = (int.Parse(data) > 0);
        
        if(killed) {
            //. If the killed value is true, terminate the app.
            int code = Mathf.Abs(int.Parse(data));
            //. Add code here for handling termination messages.
        }
    }
}

caution

Please ensure to remove the Debug.Log("-Debug Message-"); code included in the sample when releasing the service.

Registration and Use of Callback Functions for Server Authentication Events (Optional)

This content is necessary when using server authentication, and if server authentication is not used, the following content does not apply.

After completing the app signature through the AppGuard manager web service with the built IPA, when the app runs, the server authentication result is delivered to the AppGuardS2AuthCallback() callback function registered in the setAppGuardS2AuthCallback() function.

tip

For customers using AppGuard for Unity Plugin versions below v1.1.1, the code that was added to the existing onS2AuthTryCallback() method of AppGuardUnityManager should be moved to the newly written customer’s callback method.

As shown in the sample code below, users should implement the AppGuardS2AuthCallback() function for AppGuard server authentication and registration.
In the AppGuardS2AuthCallback() callback function, processing according to the server authentication status result can be performed.

Main.cs
public class testMain : MonoBehaviour
{
    void ExampleServerAuthRequest(string uniqueId) {
        //. Set the Callback Method to receive the server authentication results.
        AppGuardUnityManager.Instance.setAppGuardS2AuthCallback((result, uniqueClientId) => {
            switch (result) {
                case AppGuardEventType.S2Auth.S2AUTH_RESULT_SUCCESS:
                    //. Server authentication was successful, and authentication was completed normally.
                    Debug.Log ("[TESTMAIN] S2AUTH_RESULT_SUCCESS (UniqueID: " + uniqueClientId + ")");
                    break;

                case AppGuardEventType.S2Auth.S2AUTH_RESULT_RETRY:
                    //. Server authentication failed, and re-authentication will be attempted. 
                    //. It may be a temporary client network failure or server failure, 
                    //. and the retry may be performed for up to 3 minutes according to the internal mechanism.
                    Debug.Log ("[TESTMAIN] S2AUTH_RESULT_RETRY");
                    break;

                case AppGuardEventType.S2Auth.S2AUTH_RESULT_FAIL:
                    //. Server authentication completely failed, and server authentication will no longer be attempted.
                    Debug.Log ("[TESTMAIN] S2AUTH_RESULT_FAIL");
                    break;
            }
        });
        //. Perform server authentication using the customer’s server authentication ID.
        AppGuardUnityManager.Instance.setUniqueClientId(uniqueId,180);
    }
}

Alternatively, you can implement and register the callback method for server authentication result-related events separately as shown below.

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. Set the Callback Method to receive the server authentication status results.
        //. It is recommended to register the server authentication Callback function before calling the AppGuard initialization function.
        AppGuardUnityManager.Instance.setAppGuardS2AuthCallback(AppGuardS2AuthCallback);
    }

    void AppGuardS2AuthCallback(int type, string id) {
        switch (type) {
            case AppGuardEventType.S2Auth.S2AUTH_RESULT_SUCCESS:
                //. Server authentication was successful, and authentication was completed normally.
                Debug.Log ("[TESTMAIN] S2AUTH_RESULT_SUCCESS (UniqueID: " + id + ")");
                break;

            case AppGuardEventType.S2Auth.S2AUTH_RESULT_RETRY:
                //. Server authentication failed, and re-authentication will be attempted. 
                //. It may be a temporary client network failure or server failure, 
                //. and the retry may be performed for up to 3 minutes according to the internal mechanism.
                Debug.Log ("[TESTMAIN] S2AUTH_RESULT_RETRY");
                break;

            case AppGuardEventType.S2Auth.S2AUTH_RESULT_FAIL:
                //. Server authentication completely failed, and server authentication will no longer be attempted.
                Debug.Log ("[TESTMAIN] S2AUTH_RESULT_FAIL");
                break;
        }
    }

    void OnGUI () {
        if (GUI.Button (new Rect (10,550,200,80), "Server Auth Test")) {
            //. Set the Callback Method to receive the server authentication results.
            AppGuardUnityManager.Instance.setAppGuardS2AuthCallback(AppGuardS2AuthCallback);
            
            //. Receive the server authentication ID from the customer’s game server.
            //. The getReciveUniqueIdFromGameServer() method is written for the example and is not an actual method.
            string uniqueId = getReciveUniqueIdFromGameServer();
            
            //. Call the server authentication method of AppGuard for Unity Plugin to perform server authentication.
            AppGuardUnityManager.Instance.setUniqueClientId(uniqueId, 180);
        }
    }
}

caution

Please ensure to remove the Debug.Log("-Debug Message-"); code included in the sample when releasing the service.

Starting Server Authentication

To start server authentication from the client, you can call the following method using the Unique Client ID for the user's session received from the server, as shown in the sample code below.

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

tip

For the rules and generation method of Formatted-Unique-Client-Id given as the first argument of the setUniqueClientId() function, please refer to [Server Authentication].

info

If you have completed the application work up to this point, please proceed with the iOS platform build.

Xcode Project Application Details

Check AppGuard SDK
- Open the Xcode Project and ensure that the AppGuardCore.framework property is set to Do not Embed in Xcode Project > TARGETS:UnityFramework > General > Frameworks and Libraries.
info
If AppGuardCore.framework is properly added to the Xcode Project, please refer to the following [AppGuard SDK Privacy Manifests Application] section for recent Apple policies, Xcode 15.x compatibility, and Privacy Manifests application.

AppGuard SDK Privacy Manifests Application

This guide requires the use of AppGuard SDK v1.10.1.3 or later for Privacy Manifests application.

The AppGuardCore.framework module is merged and distributed with the TARGETS that link AppGuardCore.framework.

The PrivacyInfo.xcprivacy related to Apple Privacy Manifests must have the contents of PrivacyInfo.xcprivacy of AppGuardCore.framework specified in the PrivacyInfo.xcprivacy of the TARGETS linking AppGuard SDK.

info

[Unity Engine & Privacy Manifests]

An Apple Unity application can contain multiple frameworks (e.g., 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 Reference Link: Unity Engine & Privacy Manifests

In other words, according to the Unity Engine & Privacy Manifests guide, in the case of Unity, a separate PrivacyInfo.xcprivacy file is added in UnityFramework.framework, and the contents of PrivacyInfo.xcprivacy of AppGuard SDK must be merged into the PrivacyInfo.xcprivacy inside UnityFramework.framework.

To specify the contents related to AppGuardCore.framework in PrivacyInfo.xcprivacy, refer to the guide below to perform the merge work.

If a PrivacyInfo.xcprivacy file already exists in the TARGETS (e.g., UnityFramework) linking AppGuard SDK
- Compare the contents of the PrivacyInfo.xcprivacy file inside AppGuardCore.framework with the existing PrivacyInfo.xcprivacy in use to identify any missing parts.
- If any missing parts are found, add and merge them into the PrivacyInfo.xcprivacy file already in use in the TARGETS.
If a PrivacyInfo.xcprivacy file does not exist in the TARGETS (e.g., UnityFramework) linking AppGuard SDK
- Copy the PrivacyInfo.xcprivacy file inside AppGuardCore.framework and add it to the Xcode Project.
- Open the project, select Project > TARGETS:UnityFramework > Build Phases > Copy Bundle Resources in order, and click the Add[+] button at the bottom.
- In the [Choose items to add:] window, click the [Add Other] button at the bottom.
- Select the PrivacyInfo.xcprivacy file copied into the project and click the [Open] button.
- In the [Choose options for adding these files:] window, check [Destination:Copy items if needed], set [Added folders:Create groups], and click the [Finish] button at the bottom right.
- Confirm that the PrivacyInfo.xcprivacy file has been added to [Copy Bundle Resources] in the project.

tip

AppGuard for iOS SDK v1.10.1.3 or later is distributed under the name AppGuardCore.framework, and the SDK is made and distributed as a static framework.

AppGuard for iOS SDK v1.10.1.3 or later does not use APIs other than NSPrivacyAccessedAPICategoryUserDefaults specified in the Privacy Manifest required by Apple.

Third-party SDKs linked as static frameworks may also require merge work into the customer’s PrivacyInfo.xcprivacy, similar to AppGuard SDK.

info

Once you have completed the application up to this point, the application of AppGuard SDK is complete.

Basic Description of Unity Plugin​

iOS Requirements​

AppGuard Unity Plugin Components​

Description of AppGuard Unity Plugin Components​

AppGuardPostProcessBuild.cs​

AppGuardUnityManager.cs​

Unity Project Application Details​

Download and Setup of AppGuard for Unity Plugin​

Application of AppGuard SDK​

Download and Setup of AppGuard Config File​

Registration and Use of Callback Functions for Security Policy Violation Detection Events (Required)​

Registration and Use of Callback Functions for Server Authentication Events (Optional)​

Starting Server Authentication​

Xcode Project Application Details​

AppGuard SDK Privacy Manifests Application​

Basic Description of Unity Plugin

iOS Requirements

AppGuard Unity Plugin Components

Description of AppGuard Unity Plugin Components

AppGuardPostProcessBuild.cs

AppGuardUnityManager.cs

Unity Project Application Details

Download and Setup of AppGuard for Unity Plugin

Application of AppGuard SDK

Download and Setup of AppGuard Config File

Registration and Use of Callback Functions for Security Policy Violation Detection Events (Required)

Registration and Use of Callback Functions for Server Authentication Events (Optional)

Starting Server Authentication

Xcode Project Application Details

AppGuard SDK Privacy Manifests Application