主要 API 说明

AppGuard SDK iOS API 参考

---

文档概述

本文档说明了如何使用 nProtect AppGuard iOS SDK 的 API。

提供的 API 列表

---

API 名称	说明
void APPGUARD_INIT(APPGUARDAPPCALLBACK)	启动 AppGuard 的函数。
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)	执行 AppGuard 额外专用功能的函数。
void APPGUARD_SET_RESERVED2(const char* url)	设置服务器认证（Server-Side Authentication）服务器地址的函数。
void APPGUARD_START_CUSTOMMACROMODE	应用自定义宏规则开始检测的函数。
void APPGUARD_STOP_CUSTOMMACROMODE	应用默认宏规则开始检测的函数。

APPGUARD_INIT

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

APPGUARD_INIT 函数是初始化 AppGuard 的函数，建议在应用程序启动时最先调用。

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

建议在 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)
{
   // ...
}

// 应用程序启动时
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOptions:(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_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 函数可以在 AppGuard 策略违规检测时设置记录到日志服务器的用户 ID。

参数	说明
const char*	记录到日志服务器的用户 ID

如下例所示，可以将要记录的用户 ID 作为字符串设置为 APPGUARD_SET_USER_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	发给该应用程序的 AppGuard License Key

如下例所示，可以将符合 Formatted-Unique-Client-ID 格式的用于服务器认证的用户识别值和服务器认证重试允许时间值设置为 APPGUARD_SET_CERTIFICATION_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 时将在 3 分钟内进行约 15 次认证重试。

APPGUARD_SET_RESERVED1

void APPGUARD_SET_RESERVED1(int value, int option)

APPGUARD_SET_RESERVED1 函数是设置 AppGuard 额外功能执行的函数。如下表所示，有 3 种功能，根据设置值提供不同的功能。

项目	值	说明
FUNCTION_MACRO_RESTART	0x10000000	重新启动宏检测。即使已经通过宏检测诊断，也会在重新诊断时触发检测事件。
FUNCTION_PROXY_DETECTION	0x20000000	提供检测当前设备是否正在使用代理主机服务器的功能。该功能在每次调用时执行一次检查。（可多次调用）
FUNCTION_AUTH_REGION	0x30000000	可以设置用于服务器认证的认证服务器的国家。目前支持的国家有韩国和中国，可以通过此方法的选项值设置国家。 option = 0 : 韩国认证服务器 option = 2 : 中国认证服务器

如下例所示，可以根据 APPGUARD_SET_RESERVED1 函数内的参数值初始化并重新启动宏检测，提供代理主机检测功能，或设置服务器认证的国家。

#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）服务器的地址

如下例所示，可以将服务器认证地址按 URL 格式添加并设置为 APPGUARD_SET_RESERVED2 函数的参数。

#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 函数根据 Default Macro 规则而不是 Custom 规则开始宏检测功能。

如下例所示，应用 APPGUARD_STOP_CUSTOMMACROMODE 函数后，将根据 Default Macro 规则进行宏策略检测。

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();

注意

如果需要有关 CustomMacroMode 的更多详细信息，请联系 appguard@inca.co.kr 或相关负责人。