バージョン: 1.10.x

Unity

Unity Plugin 基本説明

このドキュメントは、プラグイン方式を使用してUnity開発環境で既存のSDK適用方式よりも簡単に適用する方法を提供するために作成されました。

iOS 要件

Xcode 15.4 以上
Minimum OS 12.0 以上
GameGuard for Mobile for iOS SDK v1.10.1.3 以上
GameGuard for Mobile Unity Plugin v1.1.1 以上

備考

Xcode 15.4 未満のバージョンではMinimum OSのバグが存在します。 このバグはXcode 15.4バージョンから解決されました。
GameGuard for Mobile SDK v1.10.1.3 以上は現在Simulatorをサポートしていません。 この機能は将来のバージョンで追加される予定です。

GameGuard for Mobile Unity Plugin 構成要素

GameGuard for Mobile Unity Plugin v1.1.1 以上の構成要素は以下の通りです。

Assets/AppGuard/ フォルダ構成

項目	ファイル名	説明	プラットフォーム
Editor	`Assets/AppGuard/Editor/AppGuardPostProcessBuild.cs`	UnityでiOS用Xcode Project生成時に必要な環境設定	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`	UnityとGameGuard Native間の通信管理	iOS/AOS

ヒント

GameGuard for Mobile Unity Plugin v1.1.1 未満を使用中の顧客はMigration適用前に既存のUnity Pluginsファイル(AppGuardPostProcessBuild.cs, AppGuardSecureStream.cs, AppGuardClientUnityBride.mm)を事前にバックアップしてください。
バックアップ後、該当ファイルをUnityプロジェクトから削除して進行してください。

GameGuard for Mobile Unity Plugin 構成説明

AppGuardPostProcessBuild.cs

Unity Editorが提供するPostProcessBuild機能を使用してUnityで生成したXcode Projectに次の機能を実行します:

GameGuard SDK駆動に必要なビルド環境ファイル設定
GameGuard SDK駆動に必要な環境ファイル設定

注意

AppGuardPostProcessBuild.cs ファイルを必ず確認し、顧客の環境と異なる場合は修正が必要な場合があります。

AppGuardUnityManager.cs

Assets/Appuard/Scripts/ に位置する AppGuardUnityManager.cs はGameGuard Native Moduleとの通信を管理するモジュールです。
このファイルのクラス名およびメソッド名はそのまま維持する必要があり、主要なメソッドは次の通りです:

Set メソッド

メソッド	説明
`public void setUserId(string userid)`	セキュリティポリシー違反検出時にログサーバーに送信するユーザー識別子(UserID)を設定します。
`public void setUniqueClientId(string uniqueId, long retryTimeSec = 180)`	サーバー認証に使用するセッションユニーク識別子を設定します。

Callback メソッド

メソッド	説明
`public void setAppGuardS2AuthCallback(Action<int, string> callback)`	GameGuard Native Moduleで実行したサーバー認証結果を受信する `callback method` を設定します。
`public void setAppGuardDetectCallback(Action<string> callback)`	GameGuard Native Moduleで実行したセキュリティポリシー違反検出結果を受信する `callback method` を設定します。

Unity Project 適用事項

GameGuard for Mobile Unity Plugin ダウンロードおよび設定

GameGuard for Mobile Unity Plugin v1.1.1 以上をインストールし、Unityでプロジェクトを構成する方法は次の通りです:

1. GameGuardマネージャーサーバーに接続し、Download > Unity Plugins を選択して最新バージョンをダウンロードします。
2. ダウンロードされた AppGuardUnityPlugin.zip ファイルを解凍すると内部に Assets フォルダがあります。
3. 解凍された Assets フォルダ内の AppGuard/ フォルダを Unity Project/Asset/ パスにコピーします。

GameGuard SDK 適用

1. GameGuardマネージャーサーバーに接続し、Download > GameGuard Module を選択してiOS SDKの最新バージョンをダウンロードします。
2. ダウンロードされた AppGuard_for_iOS.zip ファイルを解凍します。
3. GameGuard SDK v1.10.1.3 バージョンの場合 解凍すると内部に AppGuardCore.framework が存在し、これをコピーします。

備考
GameGuard for iOS SDK v1.10.2.0 バージョン以上はApple側の要件に合わせてstatic frameworkとして作成され、AppGuardCore.xcframework の名称で配布されます。
したがって、GameGuard SDK v1.10.2.0 バージョン以上の場合 解凍すると内部に AppGuardCore.xcframework が存在し、AppGuardCore.xcframework/ios-arm64/ の AppGuardCore.framework をコピーして進行します。
4. コピーした AppGuardCore.framework を以下のパスにコピーします:
Copy To : Project/Assets/AppGuard/Plugins/iOS/

GameGuard Config ファイルダウンロードおよび設定

1. GameGuardマネージャーサーバーに接続し、Applying Security > ダウンロード > CHAPTER 2. nProtect GameGuard CONFIG ファイルダウンロード > CONFIG FILE DOWNLOAD を選択してダウンロードします。
2. ダウンロードされたConfigファイルを解凍するとGameGuard Configファイルは appguard, appguard.crt, appguard.mf, appguard106000 の4つのファイルで構成されます。
3. この4つのファイルを以下のパスにコピーします:
Copy To : Project/Assets/AppGuard/Plugins/iOS/

ヒント

GameGuard for Mobile Unity Plugin v1.1.1 未満を使用していた顧客の場合、既存の appguard, appguard106000, appguard.mf, appguard.crt ファイルを Assets/AppGuard/Plugins/iOS/ に移動する必要があります。

セキュリティポリシー違反検出関連イベント用コールバック関数登録および使用(必須)

セキュリティポリシー違反検出関連イベント通信のためのアプリのコールバック関数を設定するために Unityプロジェクトの最初のシーン(Scene)クラスの Awake() メソッド で以下のサンプルコードのように作業します。
ビルドされたIPAをGameGuardマネージャーWebサービスを通じてアプリ署名を完了した後、アプリ実行時にセキュリティポリシー違反が発生すると setAppGuardDetectCallback() 関数に登録された AppGuardDetectCallback() コールバック関数にイベントが伝達されます。

ヒント

GameGuard for Mobile Unity Plugin v1.1.1 未満を使用していた顧客は、既存のAppGuardUnityManagerの onViolationCallback() メソッドに追加して使用していたコードを新しく作成した顧客のcallback methodに移動する必要があります。

以下のサンプルコードのようにユーザーはまずGameGuardセキュリティ検出および登録のための AppGuardDetectCallback() 関数を実装する必要があります。該当 AppGuardDetectCallback() コールバック関数でセキュリティ検出結果に応じた処理を行うことができます。

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. AppGuardセキュリティポリシー違反検出関連イベント通信のためのCallback Methodを設定します。
        AppGuardUnityManager.Instance.setAppGuardDetectCallback((data) => {
            bool killed = (int.Parse(data) > 0);
            
            if(killed) {
                //. 受信したセキュリティポリシー違反検出値が正の数の場合、アプリを終了処理します。
                int code = Mathf.Abs(int.Parse(data));
                //. ここに終了メッセージ処理のためのコードを追加します。
            }
        });
    }
}

または以下のようにセキュリティポリシー検出関連イベントCallbackメソッドを別途実装後に登録する方法も可能です。

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. セキュリティポリシー検出結果を受信するCallback Methodを設定します。
        //. AppGuard初期化関数呼び出し前にセキュリティポリシー検出結果Callback関数を優先的に登録することが望ましいです。
        AppGuardUnityManager.Instance.setAppGuardDetectCallback(AppGuardDetectCallback);
    }

    //. セキュリティポリシー検出結果を受信するCallback Methodを以下のように作成します。
    //. Callback Methodの名称はparameter値を維持する限り自由に作成しても問題ありません。    
    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-"); コードを必ず削除してください。

サーバー認証イベント用コールバック関数登録および使用 (選択)

この内容はサーバー認証使用時に必要な内容であり、サーバー認証を使用しない場合は以下の内容は該当しません。

ビルドされたIPAをGameGuardマネージャーWebサービスを通じてアプリ署名を完了した後、アプリ実行時にサーバー認証結果が setAppGuardS2AuthCallback() 関数に登録された AppGuardS2AuthCallback() コールバック関数に伝達されます。

ヒント

GameGuard for Mobile Unity Plugin v1.1.1 未満を使用していた顧客の場合、既存のAppGuardUnityManagerの onS2AuthTryCallback() メソッドに追加して使用していたコードを新しく作成した顧客のcallback methodに移動する必要があります。

以下のサンプルコードのようにユーザーはGameGuardサーバー認証および登録のための AppGuardS2AuthCallback() 関数を実装する必要があります。
該当 AppGuardS2AuthCallback() コールバック関数でサーバー認証状態結果に応じた処理を行うことができます。

Main.cs
public class testMain : MonoBehaviour
{
    void ExampleServerAuthRequest(string uniqueId) {
        //. サーバー認証結果を受信するためのCallback Methodを設定します。
        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);
    }
}

または以下のようにサーバー認証結果関連イベントCallbackメソッドを別途実装後に登録する方法も可能です。

Main.cs
public class testMain : MonoBehaviour
{
    void Awake() {
        //. サーバー認証状態結果を受信するCallback Methodを設定します。
        //. AppGuard初期化関数呼び出し前にサーバー認証Callback関数を優先的に登録することが望ましいです。
        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")) {
            //. サーバー認証結果を受信するCallback Methodを設定します。
            AppGuardUnityManager.Instance.setAppGuardS2AuthCallback(AppGuardS2AuthCallback);
            
            //. 顧客のゲームサーバーからサーバー認証用IDを受信します。
            //. getReciveUniqueIdFromGameServer() メソッドは例のために作成されたメソッドであり、実際に存在するメソッドではありません。
            string uniqueId = getReciveUniqueIdFromGameServer();
            
            //. GameGuard for Mobile 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 Project 適用事項

GameGuard SDK 確認
- Xcode Projectを開き、Xcode Project > TARGETS:UnityFramework > General > Frameworks and Libraries 内の AppGuardCore.framework 属性が Do not Embed に設定されているか確認してください。
備考
Xcode Projectに AppGuardCore.framework が正常に追加された場合、最近のAppleポリシーおよびXcode 15.x互換とPrivacy Manifests適用のために以下の [AppGuard SDK Privacy Manifests 適用] 項目を参照して進行してください。

GameGuard SDK Privacy Manifests 適用

このガイドはPrivacy Manifests適用のために GameGuard SDK v1.10.1.3 以上 を使用する必要があります。

AppGuardCore.frameworkモジュールは AppGuardCore.frameworkをLinkするTARGETSに統合されて配布されます。

Apple Privacy Manifestsに関連する PrivacyInfo.xcprivacy は GameGuard SDKをLinkしたTARGETSの PrivacyInfo.xcprivacy に AppGuardCore.frameworkの PrivacyInfo.xcprivacy 内容が明示される必要があります。

備考

[Unity Engine & Privacy Manifests]

AppleのUnityアプリケーションには複数のフレームワーク（例：広告やソーシャルSDK）が含まれることがあります。各フレームワークには単一のPrivacy Manifestファイルが含まれることがあります。デフォルトでは、UnityアプリケーションにはUnityプロジェクト用の単一のフレームワーク、UnityFrameworkがあります。Unityプロジェクトに統合された異なるプラグイン、パッケージからの複数のPrivacy Manifestファイル、またはファーストパーティ（あなたのUnityプロジェクト）をUnity Framework内の単一のPrivacy Manifestファイルに統合する必要があります。将来のUnityバージョンではこれが自動的に行われますが、古いUnityバージョンに固定されたUnityプロジェクトを持つUnity開発者はこれを手動で行う必要があります。

Unity Engine & Privacy Manifests 参考リンク : Unity Engine & Privacy Manifests

つまり、Unity Engine & Privacy Manifestsの案内に従ってUnityの場合 UnityFramework.frameworkで独自の PrivacyInfo.xcprivacy ファイルが追加され、 GameGuard SDKの PrivacyInfo.xcprivacy 内容が UnityFramework.framework 内部の PrivacyInfo.xcprivacy に統合される必要があります。

PrivacyInfo.xcprivacy にAppGuardCore.framework関連の内容を明示するために以下のガイドを参考にして統合作業を行ってください。

GameGuard SDKをLinkしたTARGETS（例：UnityFramework）で既に使用中の PrivacyInfo.xcprivacy ファイルが存在する場合
- AppGuardCore.framework内部の PrivacyInfo.xcprivacy ファイル内容と既に使用中の PrivacyInfo.xcprivacy を比較して欠落部分を確認します。
- 欠落部分が発見された場合、TARGETSで既に使用中の PrivacyInfo.xcprivacy ファイルに追加および統合してください。
GameGuard SDKをLinkしたTARGETS（例：UnityFramework）で PrivacyInfo.xcprivacy ファイルが存在しない場合
- AppGuardCore.framework内部の PrivacyInfo.xcprivacy ファイルをコピーしてXcode Project内に追加します。
- プロジェクトを開き 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 ファイルが追加されたか確認します。

ヒント

GameGuard for iOS SDK v1.10.1.3 以上 は AppGuardCore.framework という名前で配布され、該当SDKは static framework として作成および配布されます。

GameGuard for iOS SDK v1.10.1.3 以上 はAppleが要求するPrivacy Manifestで明示された Required reason API項目 のうち NSPrivacyAccessedAPICategoryUserDefaults 以外の他のAPIは使用していないことを参考にしてください。

Static frameworkとしてリンクされる他社SDK もGameGuard SDKと同様に 顧客の PrivacyInfo.xcprivacy に統合作業が必要 になる場合があります。

備考

ここまで適用を完了した場合、GameGuard SDK適用が完了します。

Unity Plugin 基本説明​

iOS 要件​

GameGuard for Mobile Unity Plugin 構成要素​

GameGuard for Mobile Unity Plugin 構成説明​

AppGuardPostProcessBuild.cs​

AppGuardUnityManager.cs​

Unity Project 適用事項​

GameGuard for Mobile Unity Plugin ダウンロードおよび設定​

GameGuard SDK 適用​

GameGuard Config ファイルダウンロードおよび設定​

セキュリティポリシー違反検出関連イベント用コールバック関数登録および使用(必須)​

サーバー認証イベント用コールバック関数登録および使用 (選択)​

サーバー認証開始​

Xcode Project 適用事項​

GameGuard SDK Privacy Manifests 適用​