Skip to main content
Version: 1.10.x

API Reference

AppGuard SDK iOS API Reference​

Document Overview​

This document explains how to use the APIs provided by the nProtect AppGuard iOS SDK.

List of APIs​

API NameDescription
void APPGUARD_INIT(APPGUARDAPPCALLBACK)Function to initialize AppGuard.
void APPGUARD_SET_USER_ID(const char* userId)Function to set the user ID that is logged on the server in case of policy violations.
void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)Function to set the user identification key and server authentication retry timeout used for server authentication.
void APPGUARD_SET_RESERVED1(int value, int option)Function to perform additional dedicated features of AppGuard.
void APPGUARD_SET_RESERVED2(const char* url)Function to set the URL of the server for server-side authentication.
void APPGUARD_START_CUSTOMMACROMODEFunction to start detection by applying Custom Macro rules.
void APPGUARD_STOP_CUSTOMMACROMODEFunction to start detection by applying Default Macro rules.

APPGUARD_INIT​

void APPGUARD_INIT(PAPPGUARDAPPCALLBACK)

The APPGUARD_INIT function is used to initialize AppGuard and is recommended to be called at the beginning when the app starts.

ParameterDescription
PAPPGUARDAPPCALLBACKCallback function that receives results from the AppGuard SDK

This function should be called in the application:didFinishLaunchingWithOptions: method in the AppDelegate.m or AppDelegate.mm file as shown in the following example.

AppDelegate.m or AppDelegate.mm
#import <AppGuardCore/AppGuard.h>
#import <AppGuardCore/AppGuardDefine.h>

// Define the callback function to receive results from the AppGuard SDK
static void APPGUARDAPPCALLBACK(int type, int code, const char* desc)
{
   // ...
}

// When the app starts
- (Bool)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   APPGUARD_INIT(APPGUARDAPPCALLBACK);
}
tip

Once the APPGUARDAPPCALLBACK function is successfully registered, detection details from the AppGuard SDK can be checked through the callback function.

APPGUARDAPPCALLBACK​

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

The APPGUARDAPPCALLBACK function must be implemented by the customer to receive events related to the operation of the AppGuard security service and security violations. This function must be passed as a parameter to the APPGUARD_INIT function.

ParameterDescription
int typeType of security service (Event, Report, Kill)
int codeType of security policy
const char* descDetailed information about the security violation
caution

The APPGUARDAPPCALLBACK function must be implemented and passed as a parameter to the APPGUARD_INIT function.

You can handle the results received from the AppGuard SDK in the APPGUARDAPPCALLBACK function as shown below.

static void APPGUARDAPPCALLBACK(int type, int code, const char* desc) {
   if (type == APPGUARD_TYPE_EVENT) {
      if (code == APPGUARD_EVENT_INITIALIZED) {
         // Engine initialization is complete.
      } else if (code == APPGUARD_EVENT_STOP) {
         // Engine has stopped.
      }
   } else if (type == APPGUARD_TYPE_DETECT) {
      if (code == DETECT_IOS_INVALID_EXECUTION_FILE) {
         /**
          * Tampering with the original execution file has been detected.
          * desc: Detected information
          */
      } else if (code == DETECT_IOS_DEVELOPMENT_BUILD) {
         /**
          * Execution not distributed via the App Store has been detected.
          * desc: Detected information
          */
      }
   } else if (type == APPGUARD_TYPE_ERROR) {
      if (code == APPGUARD_ERROR_APPGUARD_INIT) {
         /**
          * Failed to initialize the engine.
          */
      }
   } else if (type == APPGUARD_TYPE_S2AUTH_CALLBACK) {
      if (code == APPGUARD_TYPE_CSAUTH_SUCCESS) {
         /**
          * Server authentication was successful.
          * Use the server authentication ID passed in the desc parameter to verify again on the game server.
          *
          * desc: Server authentication ID (UniqueClientID)
          */
      } else if (code == APPGUARD_TYPE_CSAUTH_RETRY) {
         /**
          * Server authentication is in progress.
          * This can be ignored.
          */
      } else if (code == APPGUARD_TYPE_CSAUTH_FALSE) {
         /**
          * Server authentication failed.
          * Use the server authentication ID passed in the desc parameter to verify again on the game server.
          * The failure could be due to network issues on the client side, so be sure to verify again through the game server.
          */
      }
   } else if (type == APPGUARD_TYPE_KILL) {
      /**
       * If the detected content is set with a kill option by policy, it notifies and requests forced termination.
       * When this message is detected, the app must be forcibly terminated.
       * It is recommended to notify through a message and then terminate the app.
       */
   }
}

APPGUARD_SET_USER_ID​

void APPGUARD_SET_USER_ID(const char* userId)

The APPGUARD_SET_USER_ID function allows you to set the user ID that will be logged on the server when a policy violation is detected by AppGuard.

ParameterDescription
const char*The user ID to be logged on the server

You can set the user ID as a string, as shown in the following example.

#import <AppGuardCore/AppGuard.h>

APPGUARD_SET_USER_ID("user_id");

APPGUARD_SET_CERTIFICATION_ID​

void APPGUARD_SET_CERTIFICATION_ID(const char* clientId, int retryTimeout)

The APPGUARD_SET_CERTIFICATION_ID function allows you to set the user identification key and the server authentication retry timeout.

ParameterDescription
clientIdUser identification value generated by the game server following the UniqueClientID key format
retryTimeoutServer authentication retry timeout (seconds)

The UniqueClientID attempted for authentication on the client must use the same ID when requesting authentication confirmation on the server for session distinction.
The UniqueClientID must follow the Formatted-Unique-Client-ID rule.
The format of Formatted-Unique-Client-ID is UniqueID:TimeStamp:LicenseKey.

ItemTypeDescription
UniqueIDchar(40)SHA1 or 40-character unique client identification value
TimeStampchar(13)13-digit session creation time based on UTC
LicenseKeystringAppGuard License Key issued for the application

As shown in the example below, you can set the user identification value used for server authentication and the server authentication retry allowed time value according to the Formatted-Unique-Client-ID format in the parameters of the APPGUARD_SET_CERTIFICATION_ID function.

Example of how to set the UniqueClientID for server authentication:

#import <AppGuardCore/AppGuard.h>

// Pass the UniqueClientID as a parameter
APPGUARD_SET_CERTIFICATION_ID("UniqueID:TimeStamp:LicenseKey", 180);
info

If the UniqueClientID is set to null, AppGuard will generate a random UniqueClientID. The generated UniqueClientID will be passed via the APPGUARDAPPCALLBACK function registered during the APPGUARD_INIT call.

The retryTimeout can range from 0 to 180 seconds. Setting it to 0 disables retries, while setting it to 180 allows about 15 retries over 3 minutes.

APPGUARD_SET_RESERVED1​

void APPGUARD_SET_RESERVED1(int value, int option)

The APPGUARD_SET_RESERVED1 function sets additional features of AppGuard. Depending on the value, it can perform various functions, as shown below.

ItemValueDescription
FUNCTION_MACRO_RESTART0x10000000Initializes and restarts macro detection. Even if a macro has already been detected, a re-diagnosis will trigger the detection event again.
FUNCTION_PROXY_DETECTION0x20000000Detects whether the current device is using a Proxy Host server. This feature performs a check with each call. (Can be called multiple times)
FUNCTION_AUTH_REGION0x30000000Sets the country of the authentication server. Currently, Korea and China are supported. Use the option parameter to set the country:
option = 0 : Korean authentication server
option = 2 : Chinese authentication server

As shown in the example below, depending on the parameter values within the APPGUARD_SET_RESERVED1 function, you can initialize and restart macro detection, receive the Proxy Host detection feature, or set the country for server authentication.

Example:

#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)

The APPGUARD_SET_RESERVED2 function sets the URL for server-side authentication.

ParameterDescription
urlThe server authentication URL

Example:

#import <AppGuardCore/AppGuard.h>

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

The server URL can only be changed before calling the APPGUARD_SET_CERTIFICATION_ID method for server authentication.

APPGUARD_START_CUSTOMMACROMODE​

void APPGUARD_START_CUSTOMMACROMODE()

The APPGUARD_START_CUSTOMMACROMODE function starts macro detection using Custom Macro rules.

Example:

#import <AppGuardCore/AppGuard.h>

APPGUARD_START_CUSTOMMACROMODE();

APPGUARD_STOP_CUSTOMMACROMODE​

void APPGUARD_STOP_CUSTOMMACROMODE()

The APPGUARD_STOP_CUSTOMMACROMODE function switches from Custom rules to Default Macro rules for macro detection.

As shown in the example below, applying the APPGUARD_STOP_CUSTOMMACROMODE function will start macro policy detection according to Default Macro rules.

Example:

#import <AppGuardCore/AppGuard.h>

APPGUARD_STOP_CUSTOMMACROMODE();
warning

For more information about CustomMacroMode, please contact appguard@inca.co.kr or your designated representative.