Unity Plugin

Unity Plugin 基本說明

---

該文件是在Unity開發環境下安裝AppGuard時提供的適應Unity的插件，比現有SDK安裝方式更容易適用。

Plugin 下載和安裝

安裝Unity Plugin，在Unity中構建項目的方法如下。

1. 在AppGuard manager 管理平臺中 選擇Download > Unity Pluings 下載最新版本。

2. 將下載的 AppGuardUnityPlugin.zip文件解壓文件夾，將內部的AppGuardPostProcessBuild.cs, AppGuardUnityManager.cs文件和 /Plugins 文件夾複製到 Project/Asset/ 路徑內。

警告

如果編譯時 **Assets/**中只有 AppGuardUnityManager.cs 文件， /Assets/Plugins/ *文件夾未複製時到Project/Asset/ 路徑內， 需要注意，可能會出現錯誤("Error: Symbol(s) not found for a architecture arm64")。

AppGuard Config 文件下載和設置

1. 登錄AppGuard manager 管理平臺，選擇 Applying Security > 下載 > CHAPTER 2. nProtect AppGuard CONFIG 文件下載파 >選擇 CONFIG FILE DOWNLOAD 下載。

2. 下載的 Config 文件解壓後得到 AppGuard Config 文件。 AppGuard Config 文件由 appguard, appguard.crt, appguard.mf, appguard106000 四個文件構成。

3. 3. 上面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本身不支持該部分。

作爲應對方案,Inca Internet通過 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 文件中存在的類名及method需要保留， 可使用下列method或修改後使用。

Set method

method	說明
public void setUserId(string userid)	設置在檢測到違反安全策略時發送到日誌服務器的用戶標識符 (UserID)。
public void setUniqueClientId(string uniqueId, long retryTimeSec = 180)	設置用於服務器認證的會話唯一標識符。

Callback method

配置文件及文件夾	說明
public void onViolationCallback(string data)	作爲接收安全政策違規檢測相關事件Callback的method，當發現違反安全策略時 AppGuard會調用相關method併發送狀態信息。
public void onS2AuthTryCallback(string data)	服務器認證是通過接收服務器認證相關事件Callback的method進行服務器認證後， AppGuard會調用相應的method併發送狀態信息。

警告

AppGuardUnityManager.cs提供對於同時附加分發的SDK或Framework的示例代碼的使用方法。

設置 UserID

AppGuardUnityManager.cs 示例中包含的 AppGuard中檢測違反策略時，在log server上同時提供登記註冊User ID的setUserId() method。

如下示例代碼所示，"userID" 部分中實際存在會話的用戶 ID可以用任意 string 形式的數據一起調用。

Main.cs

AppGuardUnityManager.Instance.setUserId("userID");

服務器認證應用(選擇)

---

本內容爲使用服務器認證時需要的內容，未使用服務器認證時可忽略以下內容。

修改onS2AuthTryCallback 回調

相關 *.cs 文件，通過構建的 IPA，將 AppGuard manager web 服務進行App簽名的狀態時 通過下面提到的 Callback method發送傳達服務器認證動作事件。 因此，可以通過修改回調method來定義事件狀態下的行爲。

如以下示例代碼所示，可通過 onS2AuthTryCallback() 回調 method確認服務器認證狀態結果。

AppGuardUnityManager.cs

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() method時， AppGuard 安全模塊從該時間點開始嘗試服務器認證,如上述示例代碼所示,將3種服務器認證狀態傳達給回調method。

警告

構建 Release 版本時，請務必刪除**示例代碼中包含的 **Debug.Log(“-Debug Message-“); 代碼。

開始服務器認證

客戶端爲了開始服務器認證，如下面的示例代碼，對於從服務器接收的相應用戶會話的 Unique Client ID，可以調用如下method使用。

AppGuardUnityManager.cs

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

提示

以上函數的第一個參數 Formatted-Unique-Client-Id 的規則及生成方法請參考 [服務器認證] 。