This topic describes how to integrate the Anti-Bot SDK into iOS applications.

SDK files for iOS applications

Contact Alibaba Cloud technical support to obtain the SDK package, and decompress it on your local machine. The following table describes the files contained in the sdk-iOS folder.

File name Description
SGMain.framework The main framework.
SecurityGuardSDK.framework The basic security plug-in.
SGSecurityBody.framework The bot recognition plug-in.
SGAVMP.framework The virtual machine engine plug-in.
yw_1222_0335_mwua.jpg Configuration files.

Configure an iOS project

  1. Import the SDK dependency files. Import the following four .framework files extracted from the SDK package to the dependency library in an iOS project. The dependency library locates in the Link Binary With Libraries menu on the Build Phases tab.
    • SGMain.framework
    • SecurityGuardSDK.framework
    • SGSecurityBody.framework
    • SGAVMP.framework
    The dependency library
  2. Add link options. On the Build Settings tab, choose Linking > Other Linker Flags to set the value to -ObjC.Link options
  3. Import system dependency files. Import these files to the dependency library of an iOS project:
    • CoreFoundation.framework
    • CoreLocation.framework
    • AdSupport.framework
    • CoreTelephony.framework
    • CoreMotion.framework
    • SystemConfiguration.framework
    The system dependency library
  4. Import the configuration file. Add the yw_1222_0335_mwua.jpg configuration file in the SDK package to the mainbundle directory.
    Notice When the application integrates multiple targets, make sure to add the yw_1222_0335_mwua.jpg configuration file to the correct target membership.

Call the SDK

Step 1: Initialize the SDK

Endpoint: + (BOOL) initialize;

Function: Initializes the SDK.

Parameters: None.

Responses: Boolean. YES is returned if the initialization is successful. NO is returned if the initialization fails.

Call methods: [JAQAVMPSignature initialize];

Sample code
static BOOL avmpInit = NO;
- (BOOL) initAVMP{
  @synchronized(self) { // just initialize once
    if(avmpInit == YES){
      return YES; 
    }
    avmpInit = [JAQAVMPSignature initialize];
    return avmpInit; 
  }
}

Step 2: Sign the request

Endpoints: + (NSData*) avmpSign: (NSInteger) signType input: (NSData*) input;

Function: Signs the input data by using the AVMP technique, and returns a signature string.
Warning The signed request body must be the same as the request body that is sent by the client. That is, the string coding format, spaces, special characters, and parameter sequence of the signed request body must be the same as those of the request body sent by the client. Otherwise, signature verification may fail.
Request parameters
Parameter Type Required Description
signType NSInteger Yes The algorithm used to sign the request. Set the value to 3.
input NSData* No The data to be signed, which is typically the entire request body.
Note If the request body is empty, for example, an empty POST or GET request body, enter null or the value of the Bytes parameter.

Responses: A signature string is returned.

Call methods: [JAQAVMPSignature avmpSign: 3 input: request_body];

Sample code
Note When the client sends data to the server, you must call the avmpSign operation to sign the entire request body. Then, you will obtain a wToken signature string.
# define VMP_SIGN_WITH_GENERAL_WUA2 (3)
- (NSString*) avmpSign{
  @synchronized(self) {
    NSString* request_body = @"i am the request body, encrypted or not!" ;
    if(![ self initAVMP]){
      [self toast:@"Error: init failed"];
        return nil;
    }
    NSString* wToken = null;
    NSData* data = [request_body dataUsingEncoding:NSUTF8StringEncoding];
    NSData* sign = [JAQAVMPSignature avmpSign: VMP_SIGN_WITH_GENERAL_WUA2 input:data];
    if(sign == nil || sign.length <= 0){
      return nil;
    }else{
      wToken = [[NSString alloc] initWithData:sign encoding: NSUTF8StringEncoding];
      return wToken;
    }
  }
}
If the request body is empty, you must call the avmpSign operation to generate the wToken signature string. When you call this operation, set the value of the second parameter to null. Examples:
NSData* sign = [JAQAVMPSignature avmpSign: VMP_SIGN_WITH_GENERAL_WUA2 input:null];

Step 3: Add wToken to the protocol header

Sample code
#define VMP_SIGN_WITH_GENERAL_WUA2 (3)
-(void)setHeader
{ NSString* request_body = @"i am the request body, encrypted or not!" ;
  NSData* body_data = [request_body dataUsingEncoding:NSUTF8StringEncoding];
  NSString* wToken = nil;
  NSData* sign = [JAQAVMPSignature avmpSign: VMP_SIGN_WITH_GENERAL_WUA2 input:body_data];
  wToken = [[NSString alloc] initWithData:sign encoding: NSUTF8StringEncoding];
  NSString *strUrl = [NSString stringWithFormat:@"http://www.aliyundoc.com/login"];
  NSURL *url = [NSURL URLWithString:strUrl];
  NSMutableURLRequest *request =
    [[NSMutableURLRequest alloc]initWithURL:url cachePolicy:NSURLRequestReloadIgnoringCacheData timeoutInterval:20];
  [request setHTTPMethod:@"POST"];
  // set request body info
  [request setHTTPBody:body_data];
  // set wToken info to header
  [request setValue:wToken forHTTPHeaderField:@"wToken"];
  NSURLConnection *mConn = [[NSURLConnection alloc]initWithRequest:request delegate:self startImmediately:true];
  [mConn start]; 
  // ...
}

Step 4: Send data to the server

Send the data with the modified protocol header to Alibaba Cloud Security, which analyzes the wToken for risk identification and malicious request interception, and then forwards valid requests to the origin server.

Error code

Errors may occur when you call the initialize and avmpSign operations. If the system fails to generate a valid signature string, see the information about security guard errors in the console.

The following table lists the common error codes and their descriptions.

Error code Description
1901 The error code returned because the parameters are invalid. Check the parameters.
1902 The error code returned because the image file is invalid. The image may not match the bundle ID.
1903 The error code returned because the format of the image file is invalid.
1904 Upgrade the image version. The AVMP signature function only supports v5 images.
1905 The error code returned because the specified image file cannot be found. Make sure that the yw_1222_0335_mwua.jpg image file has been correctly added to the project.
1906 The error code returned because the AVMP signature of the image does not have the required bytecode. Check whether the image is invalid.
1907 The error code returned because the initialization of AVMP failed. Try again later.
1910 The error code returned because the AVMP instance is invalid. Possible causes include:
  • The AVMP instance is destroyed before InvokeAVMP is called.
  • The version of the bytecode of the image does not match the SDK.
1911 The byteCode of the encrypted image does not have the corresponding export function.
1912 The error code returned because the system failed to call AVMP. Contact Alibaba Cloud technical support.
1913 The error code returned because the InvokeAVMP method was called after the AVMP instance had been destroyed.
1915 The error code returned because the memory resources of the AVMP instance are insufficient. Try again later.
1999 The error code returned because an unknown error occurred. Try again later.