版本：1.10.x

Unity

Unity 插件基本说明

本文档旨在提供一种使用插件方式在 Unity 开发环境中比传统 SDK 应用方式更容易的应用方法。

iOS 要求

Xcode 15.4 及以上
最低 OS 12.0 及以上
AppGuard for iOS SDK v1.10.1.3 及以上
AppGuard for Unity Plugin v1.1.1 及以上

信息

Xcode 15.4 以下版本存在最低 OS 的错误。 此错误已在 Xcode 15.4 版本中修复。
AppGuard SDK v1.10.1.3 及以上版本目前不支持模拟器。 此功能将在未来版本中添加。

AppGuard Unity 插件组件

AppGuard for Unity Plugin v1.1.1 及以上版本的组件如下：

Assets/AppGuard/ 文件夹结构

项目	文件名	说明	平台
Editor	`Assets/AppGuard/Editor/AppGuardPostProcessBuild.cs`	在 Unity 中生成 iOS 用 Xcode 项目时的必要环境设置	仅 iOS
Plugins	`Assets/AppGuard/Plugins/iOS/AppGuardClientUnityBride.mm`	iOS 原生模块	仅 iOS
Script	`Assets/AppGuard/Script/AppGuardUnityManager.cs` `Assets/AppGuard/Script/AppGuardSecureStream.cs`	管理 Unity 和 AppGuard 原生之间的通信	iOS/AOS

提示

使用 AppGuard for Unity Plugin v1.1.1 以下版本的客户在迁移应用前，请提前备份之前使用的 Unity Plugins 文件（AppGuardPostProcessBuild.cs、AppGuardSecureStream.cs、AppGuardClientUnityBride.mm）。
备份后，请从 Unity 项目中删除这些文件后继续进行。

AppGuard Unity 插件组件说明

AppGuardPostProcessBuild.cs

使用 Unity Editor 提供的 PostProcessBuild 功能，在 Unity 生成的 Xcode 项目中执行以下功能：

设置 AppGuard SDK 运行所需的构建环境文件
设置 AppGuard SDK 运行所需的环境文件

警告

请务必检查 AppGuardPostProcessBuild.cs 文件，如果与客户的环境不同，可能需要进行修改。

AppGuardUnityManager.cs

位于 Assets/AppGuard/Scripts/ 的 AppGuardUnityManager.cs 是管理与 AppGuard 原生模块通信的模块。
此文件的类名和方法名必须保持不变，主要方法如下：

Set 方法

方法	说明
`public void setUserId(string userid)`	设置在检测到安全策略违规时发送到日志服务器的用户标识符（UserID）。
`public void setUniqueClientId(string uniqueId, long retryTimeSec = 180)`	设置用于服务器认证的会话唯一标识符。

Callback 方法

方法	说明
`public void setAppGuardS2AuthCallback(Action<int, string> callback)`	设置接收 AppGuard 原生模块执行的服务器认证结果的 `callback method`。
`public void setAppGuardDetectCallback(Action<string> callback)`	设置接收 AppGuard 原生模块执行的安全策略违规检测结果的 `callback method`。

Unity 项目应用事项

AppGuard for Unity 插件下载及设置

安装 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 配置文件下载及设置

1. 访问 AppGuard 管理服务器，选择 Applying Security > 下载 > CHAPTER 2. nProtect AppGuard CONFIG 文件下载 > CONFIG FILE DOWNLOAD 并下载。
2. 解压下载的配置文件，AppGuard 配置文件由 appguard、appguard.crt、appguard.mf、appguard106000 四个文件组成。
3. 将这四个文件复制到以下路径：
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 项目的第一个场景类的 Awake() 方法中按照以下示例代码进行操作。
在通过 AppGuard 管理网页服务完成应用签名后，应用启动时如果发生安全策略违规，将通过注册在 setAppGuardDetectCallback() 函数中的 AppGuardDetectCallback() 回调函数传递事件。

提示

对于使用 AppGuard for Unity Plugin v1.1.1 以下版本的客户，请将之前在 AppGuardUnityManager 的 onViolationCallback() 方法中添加的代码移至新编写的客户回调方法。

用户应首先实现用于 AppGuard 安全检测及注册的 AppGuardDetectCallback() 函数，如以下示例代码所示。在该 AppGuardDetectCallback() 回调函数中，可以根据安全检测结果进行处理。

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. 设置用于安全策略违规检测相关事件通信的回调方法。
        AppGuardUnityManager.Instance.setAppGuardDetectCallback((data) => {
            bool killed = (int.Parse(data) > 0);
            
            if(killed) {
                //. 如果接收到的安全策略违规检测值为正数，则处理应用退出。
                int code = Mathf.Abs(int.Parse(data));
                //. 在此处添加用于处理退出消息的代码。
            }
        });
    }
}

或者可以像下面这样，单独实现安全策略检测相关事件的回调方法并注册。

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. 设置用于接收安全策略检测结果的回调方法。
        //. 在调用 AppGuard 初始化函数之前，最好先注册安全策略检测结果回调函数。
        AppGuardUnityManager.Instance.setAppGuardDetectCallback(AppGuardDetectCallback);
    }

    //. 编写用于接收安全策略检测结果的回调方法。
    //. 回调方法的名称可以自由编写，只要保持参数值不变即可。    
    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-"); 代码。

注册及使用服务器认证事件的回调函数（可选）

此内容适用于使用服务器认证的情况，如果不使用服务器认证，则以下内容不适用。

在通过 AppGuard 管理网页服务完成应用签名后，应用启动时服务器认证结果将通过注册在 setAppGuardS2AuthCallback() 函数中的 AppGuardS2AuthCallback() 回调函数传递。

提示

对于使用 AppGuard for Unity Plugin v1.1.1 以下版本的客户，请将之前在 AppGuardUnityManager 的 onS2AuthTryCallback() 方法中添加的代码移至新编写的客户回调方法。

用户应实现用于 AppGuard 服务器认证及注册的 AppGuardS2AuthCallback() 函数，如以下示例代码所示。
在该 AppGuardS2AuthCallback() 回调函数中，可以根据服务器认证状态结果进行处理。

Main.cs
public class testMain : MonoBehaviour
{
    void ExampleServerAuthRequest(string uniqueId) {
        //. 设置用于接收服务器认证结果的回调方法。
        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);
    }
}

或者可以像下面这样，单独实现服务器认证结果相关事件的回调方法并注册。

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. 设置用于接收服务器认证状态结果的回调方法。
        //. 在调用 AppGuard 初始化函数之前，最好先注册服务器认证回调函数。
        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")) {
            //. 设置用于接收服务器认证结果的回调方法。
            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 项目应用事项

检查 AppGuard SDK
- 打开 Xcode 项目，确认 Xcode Project > TARGETS:UnityFramework > General > Frameworks and Libraries 中 AppGuardCore.framework 属性设置为 Do not Embed。
信息
如果 AppGuardCore.framework 已正确添加到 Xcode 项目中，请根据最近的 Apple 政策及 Xcode 15.x 兼容性和 Privacy Manifests 应用，参考以下 [AppGuard SDK Privacy Manifests 应用] 进行操作。

AppGuard SDK Privacy Manifests 应用

此指南适用于使用 AppGuard SDK v1.10.1.3 及以上版本进行 Privacy Manifests 应用。

AppGuardCore.framework 模块将 合并并分发到链接 AppGuardCore.framework 的 TARGETS。

与 Apple Privacy Manifests 相关的 PrivacyInfo.xcprivacy 必须在 链接 AppGuard SDK 的 TARGETS 的 PrivacyInfo.xcprivacy 中明确标明 AppGuardCore.framework 的 PrivacyInfo.xcprivacy 内容。

信息

[Unity 引擎 & Privacy Manifests]

Apple 的 Unity 应用程序可以包含多个框架（例如广告或社交 SDK）。每个框架可以包含一个 Privacy Manifest 文件。开箱即用，Unity 应用程序有一个用于 Unity 项目的框架，称为 UnityFramework。来自不同插件、集成到 Unity 项目的包或第一方（您的 Unity 项目）的多个 Privacy Manifest 文件必须合并到 Unity Framework 内的一个 Privacy Manifest 文件中。未来的 Unity 版本将自动执行此操作，但项目停留在旧版 Unity 的 Unity 开发人员将不得不手动执行此操作。

Unity 引擎 & Privacy Manifests 参考链接 : Unity 引擎 & Privacy Manifests

即，根据 Unity 引擎 & Privacy Manifests 指南，Unity 的情况下 UnityFramework.framework 将添加其自身的 PrivacyInfo.xcprivacy 文件， AppGuard SDK 的 PrivacyInfo.xcprivacy 内容必须合并到 UnityFramework.framework 内部的 PrivacyInfo.xcprivacy。

请参考以下指南进行合并操作，以在 PrivacyInfo.xcprivacy 中明确标明 AppGuardCore.framework 相关内容。

如果链接 AppGuard SDK 的 TARGETS（例如：UnityFramework）中已经存在使用中的 PrivacyInfo.xcprivacy 文件
- 比较 AppGuardCore.framework 内部的 PrivacyInfo.xcprivacy 文件内容与现有使用中的 PrivacyInfo.xcprivacy，确认缺失部分。
- 如果发现缺失部分，请在 TARGETS 中已经使用的 PrivacyInfo.xcprivacy 文件中添加并合并。
如果链接 AppGuard SDK 的 TARGETS（例如：UnityFramework）中不存在 PrivacyInfo.xcprivacy 文件
- 复制 AppGuardCore.framework 内部的 PrivacyInfo.xcprivacy 文件并添加到 Xcode 项目中。
- 打开项目，依次选择 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，请参考。

链接的第三方 SDK 作为 static framework 也可能需要像 AppGuard SDK 一样 在客户的 PrivacyInfo.xcprivacy 中进行合并操作。

信息

完成到此为止的应用后，AppGuard SDK 应用完成。

Unity 插件基本说明​

iOS 要求​

AppGuard Unity 插件组件​

AppGuard Unity 插件组件说明​

AppGuardPostProcessBuild.cs​

AppGuardUnityManager.cs​

Unity 项目应用事项​

AppGuard for Unity 插件下载及设置​

AppGuard SDK 应用​

AppGuard 配置文件下载及设置​

注册及使用安全策略违规检测相关事件的回调函数（必需）​

注册及使用服务器认证事件的回调函数（可选）​

开始服务器认证​

Xcode 项目应用事项​

AppGuard SDK Privacy Manifests 应用​