Unity

Unity Plugin Description

---

This document provides a more easily applicable approach than traditional SDK applications in a Unity development environment using a plug-in approach.

Plugin Download and Installation

Install Unity Plugin and configure a project in Unity follows these steps:

1. Access the AppGuard Manager server and select Download > Unity Plugings to download to the latest version.

2. When unzipping the downloaded AppGuardUnityPlugin.zip file, Assets exists inside the folder. Copy the AppGuardPostProcessBuild.cs, AppGuardUnityManager.cs files and /Plugins folder to Project/Asset/ path.

caution

If only Assets/ AppGuardUnityManager.cs exists at compilation and the /Assets/Plugins/ * folder is not copied, be aware that error("Error: Symbol(s) not found for a architecture arm64") may occur.

AppGuard Config file Download and Setting

1. Access the AppGuard Manager server and select Applying Security > Download > CHAPTER 2. nProtect AppGuard CONFIG file download > CONFIG FILE DOWNLOAD to download.

2. When unzipping the downloaded config file, the AppGuard Config file consists of four files: appguard, appguard.crt, appguard.mf, and appguard106000.

3. Copy the above four files to the path below:
   Copy To : Project/Assets/

AppGuardPostProcessBuild.cs Description

AppGuardPostProcessBuild.cs performs the following functions on the Xcode Project created by Unity using the PostProcessBuild function provided by Unity Editor.

• Setting up the build environment file required to run the AppGuard SDK
• Setting up environment files required to run the AppGuard SDK
• Setting up the AppGuardCore.xcframework link setting for each target SDK selected by Unity

However, for the Xcode Project generated by Unity, the xcframewrok format is not recognized properly. This is considered to be an unsupported part of Unity itself.

As a countermeasure, the INCA INTERNET provides a function to link the necessary framework according to the target SDK selected by Unity through the AppGuardPostProcessBuild.cs file.

note

Starting with AppGuard for iOS SDK v1.8.6, the SDK for iOS deployment method will be xcframework format that supports multiple frameworks from the existing single framework method.

Therefore, the AppGuard for iOS SDK has been renamed from AppGuardCore.framework to AppGuardCore.xcframework, and AppGuardCore.xcframework supports both Unity's Device SDK and Simulator SDK build and execution.

tip

xcframework is the format recommended by Apple for framework deployment for multi-platform support.

For customer company who uses lower than AppGuard 1.8.6 version and Xcode 13.3.3 version, if you copy AppGuardCore.xcframework/ios-arm64_armv7/ AppGuardCore.framework to Project/Assets/Plugins/AppGuardCore.xcframework/ios-arm64/ folder, it can be used in the same way as before.

For customer company who uses upper than AppGuard 1.8.6 version and Xcode 13.3.3 version, if you use AppGuardCore.xcframework/ios-arm64/ AppGuardCore.framework, it can be used in the same way as before.

caution

Please be sure to check the AppGuardPostProcessBuild.cs file and may need to be modified if it is different from the customer company's environment.

AppGuardUnityManager.cs Description

The configuration file, the AppGuardUnityManager.cs, in the Assets/ folder, is a Unity Plugin sample for server authentication, and the class name and method name existing in the *.cs file must be maintained, and the methods listed below can be used or modified.

Set Method

Method	Description
public void setUserId(string userid)	Send security policy violations to the log server. Set the user identifier (UserID).
public void setUniqueClientId(string uniqueId, long retryTimeSec = 180)	Set the session unique identifier to use for server authentication.

Callback Method

Config File and Folder	Description
public void onViolationCallback(string data)	When a security policy violation is detected by a method that receives an event Callback related to security policy violation detection, AppGuard calls the method and sends status information.
public void onS2AuthTryCallback(string data)	When server authentication proceeds with a method that receives a server authentication-related event Callback, AppGuard calls the method and sends status information.

caution

AppGuardUnityManager.cs provides samples on how to use additional SDKs or frameworks that are additionally provided.

AppGuard SDK Unity Plugin Application

---

Calling the AppGuard initialization function

A start() method is provided for registering the app's callback function for communication with AppGuard in AppGuard. The function must be called from Awake() method of the first scene of the Unity Project since it is needed to be applied at the first time point when the app is executed.

It can be called and applied to AppGuardUnityManager.Instance.start() in Awake() function as shown in the sample code below.

Main.cs

void Awake() {
    AppGuardUnityManager.Instance.start();
}

Modifying onViolationCallback Callback

If the *.cs file is applied and the built IPA has been signed through the AppGuard Manager web service, the event will be sent through the Callback method mentioned below when the Application is executed and a security policy violation is detected. Therefore, callback method can be modified to define the behavior according to the event status. When delegating special actions for security policy violations to AppGuard, you can change the method as an empty routine as shown below.

If the data parameter value has a positive number, as in the sample code below, AppGuard performs a forced shutdown after about 30 seconds according to the setted policy. Threfore, the code in onViolationCallback() method should be implemented at that location that exposes a message to the user that the app will be closing.

AppGuardUnityManager.cs

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

caution

Please make sure to remove the Debug.Log(“-Debug Message-“); code included in the sample when service release in live.

Setting UserID

The AppGuardUnityManager.cs sample provides a setUserId() method for registering UserID with the log server when AppGuard detects a policy violation.

As shown in the sample code below, the actual user ID of the session can be called together as data in the form of string in "userID" part.

Main.cs

AppGuardUnityManager.Instance.setUserId("userID");

Applying Server-Side Authentication (optional)

---

This content is required when using server authentication. If you do not use server authentication, you can ignore the following contents.

Modifying the onS2AuthTryCallback Callback

If the *.cs file is applied and the built IPA has been signed through the AppGuard Manager web service, the server authentication event will be sent through the Callback method mentioned below. Therefore, callback method can be modified to define the behavior according to the event status.

As shown in the sample code below, the server authentication status results can be checked through onS2AuthTryCallback() callback method.

AppGuardUnityManager.cs

public void onS2AuthTryCallback(string data) {
    // Special actions based on server authentication status
    string[] args = data.Split(',');

    switch (int.Parse(args[0])) {
        case AppGuardEventType.S2Auth.S2AUTH_RESULT_SUCCESS:
            /*
            Server authentication succeeded, and authentication completed normally.
            */
            Debug.Log ("S2AUTH_RESULT_SUCCESS(UniqueID: " + args[1] + ")");
            break;

        case AppGuardEventType.S2Auth.S2AUTH_RESULT_RETRY:
            /*
            Server authentication failed, and reauthentication will be attempted.
            It can be a temporary client network failure or server failure, 
            and the corresponding retry can take up to 3 minutes depending on the internal mechanism.
            */
            Debug.Log ("S2AUTH_RESULT_RETRY");
            break;

        case AppGuardEventType.S2Auth.S2AUTH_RESULT_FAIL:
            /*
            Server authentication has completely failed, and server authentication is no longer attempted.
            */
            Debug.Log ("S2AUTH_RESULT_FAIL");
            break;
    }
}

tip

If there is no special action based on the server-side authentication status, you can process the method as an Empty routine as shown below. As described in [Starting server-side authentication in AppGuardUnityManager.cs] below, when the setUniqueClientId() method is called from an object created through the AppGuardUnityManager.Instance() call, the AppGuard security module attempts to server-side authenticate from that point on, and sends three server-side authentication states to the callback method as illustrated in the sample code above.

caution

Please be sure to remove the Debug.Log(“-Debug Message-“); code included in the sample at actual release.

Starting Server-Side Authentication

In order to start server-side authentication on the client, Unique Client ID for the user's session received from the server can be used by calling the following method, as shown in the sample code below.

AppGuardUnityManager.cs

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

tip

For the rule and creation method of Formatted-Unique-Client-Id given as the first argument of the above function, please refer to the [Server-Side Authentication] related document.