バージョン: 1.10.x

主要API説明

GameGuard for Mobile SDK iOS APIリファレンス

ドキュメント概要

このドキュメントはnProtect GameGuard for Mobile iOS SDKのAPI使用方法を説明します。

提供するAPIリスト

API名	説明
void APPGUARD_INIT(APPGUARDAPPCALLBACK)	GameGuard for Mobileの起動を開始する関数です。
void APPGUARD_SET_USER_ID(const char* userId)	ポリシー違反検出時にログサーバーに記録されるユーザーのIDを設定する関数です。
void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)	サーバー認証に使用されるユーザー識別キーとサーバー認証再試行時間を設定する関数です。
void APPGUARD_SET_RESERVED1(int value, int option)	GameGuard for Mobileの追加専用機能を実行する関数です。
void APPGUARD_SET_RESERVED2(const char* url)	サーバー認証(Server-Side Authentication)サーバーのアドレスを設定する関数です。
void APPGUARD_START_CUSTOMMACROMODE	Custom Macroルールを適用して検出を開始する関数です。
void APPGUARD_STOP_CUSTOMMACROMODE	Default Macroルールを適用して検出を開始する関数です。

APPGUARD_INIT

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

APPGUARD_INIT関数はGameGuard for Mobileを初期化する関数で、アプリが実行されるときに最初に呼び出すことを推奨します。

パラメータ	説明
`PAPPGUARDAPPCALLBACK`	GameGuard for Mobile SDKから結果を受け取るコールバック関数

この関数は次の例のようにAppDelegate.mまたはAppDelegate.mmファイルのapplication:didFinishLaunchingWithOptions:関数内で呼び出すのが良いです。

AppDelegate.mまたはAppDelegate.mm
#import <AppGuardCore/AppGuard.h>
#import <AppGuardCore/AppGuardDefine.h>

// GameGuard for Mobile SDKから結果を受け取るコールバック関数定義
static void APPGUARDAPPCALLBACK(int type, int code, const char* desc)
{
   // ...
}

// アプリが開始される時点
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   APPGUARD_INIT(APPGUARDAPPCALLBACK);
}

ヒント

APPGUARDAPPCALLBACK関数が正常に登録されると、GameGuard for Mobile SDKが実行した検出内容をコールバック関数を通じて確認できます。

APPGUARDAPPCALLBACK

typedef void (*PAPPGUARDAPPCALLBACK)(int type, int code, const char *pData);

APPGUARDAPPCALLBACK関数は顧客側で必ず実装しなければならないコールバック関数で、GameGuard for Mobileセキュリティサービスの動作過程およびセキュリティ違反に関するイベントを受信します。この関数はAPPGUARD_INIT関数のパラメータとして渡されなければなりません。

パラメータ	説明
`int type`	セキュリティサービスの種類 (`Event`, `Report`, `Kill`)
`int code`	セキュリティサービスのポリシー種類
`const char* desc`	セキュリティ違反行為に関する詳細情報

注意

APPGUARDAPPCALLBACK関数は必ず実装し、APPGUARD_INIT呼び出し時にパラメータとして渡す必要があります。

以下の例のように適用すると、APPGUARDAPPCALLBACK関数でGameGuard for Mobile SDKから受け取った結果を処理できます。

static void APPGUARDAPPCALLBACK(int type, int code, const char* desc) {
   if (type == APPGUARD_TYPE_EVENT) {
      if (code == APPGUARD_EVENT_INITIALIZED) {
         // エンジンの初期化が完了しました。
      } else if (code == APPGUARD_EVENT_STOP) {
         // エンジンが停止しました。
      }
   } else if (type == APPGUARD_TYPE_DETECT) {
      if (code == DETECT_IOS_INVALID_EXECUTION_FILE) {
         /**
          * 元の実行ファイルの改ざんが検出されました。
          * desc : 検出された情報
          */
      } else if (code == DETECT_IOS_DEVELOPMENT_BUILD) {
         /**
          * AppStoreで配布されていない実行状態が検出されました。
          * desc : 検出された情報
          */
      }
   } else if (type == APPGUARD_TYPE_ERROR) {
      if (code == APPGUARD_ERROR_APPGUARD_INIT) {
         /**
          * エンジンの初期化に失敗しました。
          */
      }
   } else if (type == APPGUARD_TYPE_S2AUTH_CALLBACK) {
      if (code == APPGUARD_TYPE_CSAUTH_SUCCESS) {
         /**
          * サーバー認証作業が成功しました。
          * descパラメータで渡されるサーバー認証用IDを使用してゲームサーバーで再検証作業を
          * 行ってください。
          *
          * desc : サーバー認証用ID (UniqueClientID)
          */
      } else if (code == APPGUARD_TYPE_CSAUTH_RETRY) {
         /**
          * サーバー認証作業を進行中です。
          * 無視しても構いません。
          */
      } else if (code == APPGUARD_TYPE_CSAUTH_FALSE) {
         /**
          * サーバー認証作業が失敗しました。
          * descパラメータで渡されるサーバー認証用IDを使用してゲームサーバーで再検証作業を
          * 行ってください。
          * サーバー認証作業が失敗した理由がクライアントのネットワーク問題である可能性があるため
          * ゲームサーバーを通じた再検証作業を必ず行ってください。
          */
      }
   } else if (type == APPGUARD_TYPE_KILL) {
      /**
       * 検出内容がポリシーによりkillオプションで設定されている場合通知し、強制終了を要求します。
       * 該当メッセージが検出されるとアプリを強制終了しなければなりません。
       * 終了方法はメッセージウィンドウを通じた通知後アプリを終了することを推奨します。
       */
   }
}

APPGUARD_SET_USER_ID

void APPGUARD_SET_USER_ID(const char* userId)

APPGUARD_SET_USER_ID関数はGameGuard for Mobileポリシー違反検出時にログサーバーに記録するユーザーのIDを設定できます。

パラメータ	説明
`const char*`	ログサーバーに記録するユーザーのID

以下の例のようにAPPGUARD_SET_USER_ID関数のパラメータとして記録するユーザーIDを文字列で設定できます。

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_USER_ID("user_id");

APPGUARD_SET_CERTIFICATION_ID

void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)

APPGUARD_SET_CERTIFICATION_ID関数はサーバー認証に使用されるユーザー識別キーとサーバー認証再試行時間を設定できます。

パラメータ	説明
`clientId`	UniqueClientIDキー形式を遵守するゲームサーバーで生成されたユーザー識別値
`retryTimeout`	サーバー認証再試行許容時間(秒)

クライアントで認証を試みたUniqueClientIDはセッション区分のためにサーバーで認証確認要求時に同じIDを使用しなければなりません。 UniqueClientIDは必ずFormatted-Unique-Client-IDルールを遵守しなければなりません。
Formatted-Unique-Client-IDの形式はUniqueID:TimeStamp:LicenseKeyです。

項目	タイプ	説明
`UniqueID`	char(40)	ユーザー別SHA1または40文字で構成されたクライアント唯一識別値
`TimeStamp`	char(13)	UTC基準の13桁で構成されたセッション生成時間
`LicenseKey`	string	該当アプリケーションに発行されたGameGuard for Mobileライセンスキー

以下の例のようにAPPGUARD_SET_CERTIFICATION_ID関数のパラメータとしてFormatted-Unique-Client-ID形式に合わせてサーバー認証に使用されるユーザー識別値とサーバー認証再試行許容時間値を設定できます。

#import <AppGuardCore/AppGuard.h>

// UniqueClientIDを引数として渡す
APPGUARD_SET_CERTIFICATION_ID("UniqueID:TimeStamp:LicenseKey", 180

);

備考

もしUniqueClientID値をnullで入力した場合、GameGuard for Mobile内部でランダムなUniqueClientIDを生成します。生成されたUniqueClientIDはAPPGUARD_INIT呼び出し時に登録したAPPGUARDAPPCALLBACK関数を通じて受け取ることができます。

サーバー認証再試行retryTimeout時間値の設定範囲は0〜180秒であり、
0に設定すると再試行しません。
180に設定すると3分間で約15回の認証再試行を行います。

APPGUARD_SET_RESERVED1

void APPGUARD_SET_RESERVED1(int value, int option)

APPGUARD_SET_RESERVED1関数はGameGuard for Mobileの追加機能実行を設定する関数です。以下の表のように3つの機能があり、設定値に応じて提供される機能が異なります。

項目	値	説明
`FUNCTION_MACRO_RESTART`	0x10000000	マクロ検出を初期化して再開始します。すでにマクロ検出で診断された場合でも、再診断時に検出イベントを発生させます。
`FUNCTION_PROXY_DETECTION`	0x20000000	現在のデバイスでProxy Hostサーバーを使用中かどうかを検出する機能を提供します。該当機能は呼び出すたびに1回検査を行います。（複数回呼び出し可能）
`FUNCTION_AUTH_REGION`	0x30000000	サーバー認証に使用する認証サーバーの国を設定できます。現在サポートされている国は韓国と中国の2か国であり、このメソッドのオプション値で国を設定できます。 `option = 0` : 韓国認証サーバー `option = 2` : 中国認証サーバー

以下の例のようにAPPGUARD_SET_RESERVED1関数内のパラメータ値に応じてマクロ検出を初期化して再開始したり、Proxy Host検出機能を提供されたり、サーバー認証する国を設定できます。

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_RESERVED1(FUNCTION_MACRO_RESTART);
...
APPGUARD_SET_RESERVED1(FUNCTION_AUTH_REGION, 0);

APPGUARD_SET_RESERVED2

void APPGUARD_SET_RESERVED2(const char* url)

APPGUARD_SET_RESERVED2関数はサーバー認証(Server-Side Authentication)を実行するためのサーバー認証のアドレスを設定します。

パラメータ	説明
`url`	認証を試みるサーバー認証(Server-Side Authentication)サーバーのアドレス

以下の例のようにAPPGUARD_SET_RESERVED2関数のパラメータとしてサーバー認証アドレスをURL形式に合わせて追加して設定できます。

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_RESERVED2("https://c4-auth.appguard.co.kr");

注意

サーバー認証を実行するAPPGUARD_SET_CERTIFICATION_IDメソッドを呼び出す前にのみこのメソッドでサーバーのアドレスを変更できます。

APPGUARD_START_CUSTOMMACROMODE

void APPGUARD_START_CUSTOMMACROMODE()

APPGUARD_START_CUSTOMMACROMODE関数はCustom Macroルールが適用されたマクロ検出機能を実行します。

以下の例のようにAPPGUARD_START_CUSTOMMACROMODE関数を適用するとCustom Macroルールに従ってマクロポリシー検出が進行されます。

#import <AppGuardCore/AppGuard.h>

APPGUARD_START_CUSTOMMACROMODE();

APPGUARD_STOP_CUSTOMMACROMODE

void APPGUARD_STOP_CUSTOMMACROMODE()

APPGUARD_STOP_CUSTOMMACROMODE関数はマクロ検出機能がCustomルールではなくDefault Macroルールに従って検出を開始します。

以下の例のようにAPPGUARD_STOP_CUSTOMMACROMODE関数を適用するとDefault Macroルールに従ってマクロポリシー検出が進行されます。

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();

警告

CustomMacroModeについてさらに詳しい内容が必要な場合は、appguard@inca.co.krまたは担当者にお問い合わせください。

GameGuard for Mobile SDK iOS APIリファレンス​

ドキュメント概要​

提供するAPIリスト​

APPGUARD_INIT​

APPGUARDAPPCALLBACK​

APPGUARD_SET_USER_ID​

APPGUARD_SET_CERTIFICATION_ID​

APPGUARD_SET_RESERVED1​

APPGUARD_SET_RESERVED2​

APPGUARD_START_CUSTOMMACROMODE​

APPGUARD_STOP_CUSTOMMACROMODE​