主要 API说明

AppGuard SDK iOS API Reference

---

文件概要

该文件是说明 nProtect AppGuard iOS SDK 的 API 使用方法的文件。

提供的 API 列表

---

API 名称	说明
void APPGUARD_INIT(APPGUARDAPPCALLBACK)	启动AppGuard 驱动的函数。
void APPGUARD_SET_USER_ID(const char* userId)	检测到违反策略时设置记录在log server上的用户ID的函数。
void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)	用于服务器认证的用户识别键和设置服务器认证重试时间的函数。
void APPGUARD_SET_RESERVED1(int value, int option)	执行AppGuard 追加专用功能的函数。
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 函数是初始化 AppGuard的函数。因此，建议您在应用程序运行时最先调用它。

参数	说明
PAPPGUARDAPPCALLBACK	从 AppGuard SDK接收结果的回调函数

APPGUARD_INIT 函数如下例所示为AppDelegate.m 或 AppDelegate.mm 文件的 application:didFinishLaunchingWithOptions: 建议函数内部调用。

AppDelegate.m 或 AppDelegate.mm

#import <AppGuardCore/AppGuard.h>
#import <AppGuardCore/AppGuardDefine.h>

//. 如下定义从AppGuard SDK 接收结果的回调函数。
static void APPGUARDAPPCALLBACK(int type, int code, const char* desc)
{
   . . .
}

// App开始的节点
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOption:(NSDictionary *) launchOptions {
   APPGUARD_INIT(APPGUARDAPPCALLBACK);
}

提示

如果APPGUARDAPPCALLBACK 回调函数已正常注册， AppGuard SDK执行的检测明细可通过已注册的回调函数进行确认。

APPGUARDAPPCALLBACK

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

APPGUARDAPPCALLBACK 函数是客户公司必须实现的函数。 是接收AppGuard 安全服务的运行过程及违反安全事件的回调函数。 应将该函数作为参数发送给APPGUARD_INIT 函数。

参数	说明
int type	安全服务的类型- Event, Report, Kill
int code	安全服务的策略类型
const char* desc	违反安全行为的相关详细信息

警告

APPGUARDAPPCALLBACK 函数必须由客户公司实现，并在调用 APPGUARD_INIT 时作为参数发送。

如下例所示，应用 APPGUARDAPPCALLBACK 函数时，可通过相应参数从AppGuard 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_SUCESS ) {
         /**
          * 服务器认证操作成功。
          * 请使用通过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 option，将予以通知，并要求强制退出。
       * 如果检测到该消息通知，必须强制退出APP。
       * 建议采用通过信息窗通知后再退出App的方式。
       */
   }
}

APPGUARD_SET_USER_ID

void APPGUARD_SET_USER_ID(const char* userId)

APPGUARD_SET_USER_ID 函数可设置在检测违反AppGuard 策略时写入log server 的用户ID。

参数	说明
const char*	记录到log server的用户 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 key格式的游戏服务器中生成的用户识别值
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位4的时间
LicenseKey	string	在相应 Application上发布的AppGuard License Key

如下例所示， APPGUARD_SET_CERTIFICATION_ID函数的参数，可以根据 Formatted-Unique-Client-ID 格式 设置用于服务器认证的用户识别值和允许服务器认证重试的时间值。

#import <AppGuardCore/AppGuard.h>

// 作为参数发送UniqueClientID 
APPGUARD_SET_CERTIFICATION_ID("UniqueID:TimeStamp:LicenseKey", 180);

信息

如果输入 UniqueClientID 值为 null，则在 AppGuard 内部生成随机UniqueClientID。 生成的 UniqueClientID 可通过 APPGUARD_INIT 调用时注册的 APPGUARDAPPCALLBACK 函数接收。

重试服务器认证retryTimeout 时间值的设置范围为0 ~ 180秒， 设置为0 时不重试。
将时间值的设定范围值设置为180时，在3min内进行约15次认证重试。

APPGUARD_SET_RESERVED1

void APPGUARD_SET_RESERVED1(int value, int option)

APPGUARD_SET_RESERVED1 函数是目前可设定 AppGuard 附加功能执行的函数。 如下表所示，存在三种功能，功能提供因设定值而异。

项目	值	说明
FUNCTION_MACRO_RESTART	0x10000000	重置宏检测并重新启动。 即使已经被诊断为宏检测,再次诊断时也会发生探测活动。
FUNCTION_PROXY_DETECTION	0x20000000	提供检测当前设备是否使用Proxy Host服务器的功能。每次调用该功能时都会进行1次检查（可多重调用）。
FUNCTION_AUTH_REGION	0x30000000	您可以设置用于服务器验证的验证服务器国家。 目前支持的国家有韩国和中国两个国家,可以设定以该方法的Option值支持的国家。 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 函数参数认证的服务器认证(Server-Side Authentication) 的地址可以根据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()

Macro 检测策略功能

APPGUARD_START_CUSTOMMACROMODE 函数执行应用Custom Macro 规则的宏检测功能。

如下例所示应用APPGUARD_START_CUSTOMMACROMODE 函数时，用Custom Macro 规则进行Macro 策略检测。

#import <AppGuardCore/AppGuard.h>

APPGUARD_START_CUSTOMMACROMODE();

APPGUARD_STOP_CUSTOMMACROMODE

void APPGUARD_STOP_CUSTOMMACROMODE()

APPGUARD_STOP_CUSTOMMACROMODE 函数将 Macro 检测功能应用于Default Macro 规则而不是 Custom 规则，从而开始检测。

如下例所示，应用 APPGUARD_STOP_CUSTOMMACROMODE 函数时，用 Default Macro 规则进行 Macro 策略检测。

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();

注意

如需进一步了解CustomMacroMode，请咨询appguard@inca.co.kr 或相关负责人。