Web Application Firewall:Integrate the SDK for iOS apps

1. Add the header file

• For the IDFA version, use the following configuration:

  #import <AliTigerTally_IDFA/AliTigerTally.h>

• For the non-IDFA version, use the following configuration:

  #import <AliTigerTally_NOIDFA/AliTigerTally.h> 

2. Set the data signature

1. You can set a custom end-user identity for your business. This lets you configure WAF mitigation policies with greater flexibility.

   /**
   * Sets the user account.
   *
   * @param account   The account information.
   */
   - (void)setAccount:(NSString *)account;

   • Parameters

     • account: A string that identifies a user. Use a desensitized format. Type: NSString.

   • Return value: None.

   • Example

     // For guest users, you can skip setAccount and proceed with initialization. After a user logs on, call setAccount and re-initialize.
     [[AliTigerTally sharedInstance] setAccount:@"testAccount"];

2. Initialize the SDK to perform the initial data collection.

   Each initialization collects device information once. You can call the init function again to re-initialize data collection for different business scenarios.

   Initialization supports three data collection modes: full, custom privacy, and non-privacy. The non-privacy mode does not collect fields that involve end-user privacy, such as IDFA and IDFV.

   Note

   To comply with your internal requirements, select a suitable data collection mode that ensures data integrity. Complete data helps detect potential threats more effectively.

   // Initialization callback. The callback returns the status code of the interface call.
   typedef void (^TTInitListener)(int);
   
   /**
    * Initializes the SDK.
    *
    * @param appkey        The key.
    * @param options       Optional parameters.
    * @param onInitFinish  The callback for when initialization is complete.
    * @return Indicates whether the initialization was successful.
    */
   - (int)init:(NSString *)appkey collectType:(TTCollectType)type options:(NSMutableDictionary *_Nullable)options listener:(TTInitListener _Nullable)onInitFinish;

   • Parameters

     • appkey: Your SDK authentication key. Type: NSString.

     • collectType: The data collection mode. Type: TTCollectType. Valid values:

       Field	Description	Example
       TT_DEFAULT	Collects full data.	TT_DEFAULT
       TT_NO_BASIC_DATA	Does not collect basic device data. This includes the device name, system version number, and screen resolution.	TT_NO_X | TT_NO_Y (Indicates that neither X nor Y is collected. X and Y represent the field type names of specific collection items.)
       TT_NO_UNIQUE_DATA	Does not collect unique identifier data. This includes IDFV and IDFA.
       TT_NO_EXTRA_DATA	Does not collect extended device data. This includes connected Wi-Fi information (SSID, BSSID) and the list of nearby Wi-Fi networks.
       TT_NOT_GRANTED	Does not collect any of the preceding privacy data.	TT_NOT_GRANTED

     • options: Optional parameters for data collection. The default value is nil. Type: NSMutableDictionary. The following parameters are available:

       Field	Description	Example
       IPv6	Specifies whether to use an IPv6 domain name to report device information. 0 (default): Uses an IPv4 domain name. 1: Uses an IPv6 domain name.	1
       Intl	Specifies whether to use a domain name outside the Chinese mainland to report device information. 0 (default): Reports from the Chinese mainland. 1: Reports from outside the Chinese mainland.	1
       CustomUrl	The domain name of the data reporting server.	https://cloudauth-device.us-west-1.aliyuncs.com
       CustomHost	The host of the data reporting server.	cloudauth-device.us-west-1.aliyuncs.com

       Note

       For most international regions, you only need to set the Intl parameter. You can set CustomUrl and CustomHost only when you need to report data to a specific region, such as the US (Silicon Valley) region: https://cloudauth-device.us-west-1.aliyuncs.com.

     • listener: The SDK initialization callback interface. You can use this callback to determine the status of the initialization. The default value is nil. Type: TTInitListener.

       TTCode	Code	Description
       TT_SUCCESS	0	The SDK is initialized.
       TT_NOT_INIT	-1	The SDK initialization is not called.
       TT_NOT_PERMISSION	-2	The basic iOS permissions required by the SDK are not fully granted.
       TT_UNKNOWN_ERROR	-3	An unknown system error occurred.
       TT_NETWORK_ERROR	-4	A network error occurred.
       TT_NETWORK_ERROR_EMPTY	-5	A network error occurred. The returned content is an empty string.
       TT_NETWORK_ERROR_INVALID	-6	The format of the network response is invalid.
       TT_PARSE_SRV_CFG_ERROR	-7	Failed to parse the server configuration.
       TT_NETWORK_RET_CODE_ERROR	-8	The gateway returned a failure response.
       TT_APPKEY_EMPTY	-9	The AppKey is empty.
       TT_PARAMS_ERROR	-10	Other parameter errors occurred.
       TT_FGKEY_ERROR	-11	A key calculation error occurred.
       TT_APPKEY_ERROR	-12	The SDK version does not match the AppKey version.

   • Return value: An error code. 0 indicates success. A negative number indicates failure. Type: int.

   • Example:

     // The appkey is the authentication key assigned on the Alibaba Cloud platform.
     NSString *appKey = @"xxxxxxxxxxxxxxxxxxxxx";
     // Optional parameters. You can configure IPv6 and international reporting.
     NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
     [options setValue:@"0" forKey:@"IPv6"];     // Configure for IPv4.
     [options setValue:@"0" forKey:@"Intl"];     // Configure for reporting from the Chinese mainland.
     // [options setValue:@"1" forKey:@"Intl"];  // Configure for reporting from outside the Chinese mainland.
     // Report to the US (West) site.
     // [options setValue:@"https://cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomUrl"];
     // [options setValue:@"cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomHost"];
     
     // One initialization call represents one device information collection. You can call the init function again to re-initialize collection for different business scenarios.
     // Full data collection.
     if (0 == [[AliTigerTally sharedInstance] init:appkey collectType:TT_DEFAULT options:options listener:nil]) {
         NSLog(@"Initialization successful");
     } else {
         NSLog(@"Initialization failed");
     }
     
     // Specify privacy data to collect. You can use "|" to concatenate different privacy data types.
     TTCollectType collectPrivacy = TT_NO_BASIC_DATA | TT_NO_EXTRA_DATA;
     int ret = [[AliTigerTally sharedInstance] init:appkey collectType:collectPrivacy options:options listener:nil];
     
     // Do not collect privacy fields.
     int ret = [[AliTigerTally sharedInstance] init:appkey collectType:TT_NOT_GRANTED options:options listener:nil];

3. Data hashing.

   This is a custom signing interface that calculates the input data to generate a whash string as the custom signature data. For POST, PUT, and PATCH requests, you must pass the request body. For GET and DELETE requests, you must pass the full URL. The whash string must also be added to the ali_sign_whash field in the HTTP request header.

   // Request type:
   typedef NS_ENUM(NSInteger, TTRequestType) {
       TT_GET=0, TT_POST, TT_PUT, TT_PATCH, TT_DELETE
   };
   
   /**
    * Hashes the custom signature data.
    * @param type  The data type.
    * @param input The data to be signed.
    * @return The whash string.
    */
   - (NSString *)vmpHash:(TTRequestType)type input:(NSData *)input;

   • Parameters:

     • type: The data type. Type: TTTypeRequest. Valid values:

       • GET

       • POST

       • PUT

       • PATCH

       • DELETE

     • input: The data to be signed. Pass the body or URL based on the type. Type: NSData.

   • Return value: The whash string. Type: NSString.

   • Example:

     // GET request
     NSString *url = @"https://tigertally.aliyun.com/apptest";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@", whash);
     
     // POST request
     NSString *body = @"hello world";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@", whash);

   Note

   You do not need to call this interface if you configure the default signature in the console and the custom signing option is not selected. If you select the custom signing option, call this interface for hash verification before data signing.

4. Data signing.

   This method uses VMP technology to sign the input data and returns a wtoken string for request authentication.

   /**
    * Signs the data.
    * @param input The data to be signed.
    * @return The wtoken string.
    */
   - (NSString *)vmpSign:(NSData *)input;

   • Parameters:

     • input: The data to be signed. This is typically the entire request body or the whash from custom signing. Type: NSData.

   • Return value: The wtoken string. Type: NSString.

   • Example:

     // Default signature configured in the console (custom signing is not selected).
     NSString *body = @"hello world";
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"wtoken: %@", wtoken);
     
     // Custom signing configured in the console.
     // Custom signing for a POST request.
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@, wtoken: %@", whash, wtoken);
     
     // Custom signing for a GET request.
     NSString *url = @"https://tigertally.aliyun.com/apptest";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@, wtoken: %@", whash, wtoken);

     Note

     • When you call vmpHash for custom signing, the input parameter for the vmpSign interface is the generated whash string. When you configure a scenario-based policy for app protection, you must set the Custom Signing Field to ali_sign_whash.

     • When you call vmpHash to generate a whash for a GET request, make sure that the input URL is identical to the final network request URL. Pay close attention to URL encoding because some frameworks automatically encode Chinese characters or parameters.

     • The input parameter of the vmpHash interface does not support bytes or empty strings. If the input is a URL, it must contain a path or a parameter.

     • When you call vmpSign, if the request body is empty, such as the body of a POST or GET request, pass a null object (nil) or the NSData value of an empty string. For example, [@"\"\" dataUsingEncoding:NSUTF8StringEncoding].

     • If whash or wtoken is one of the following strings, an exception occurred during initialization:

       • you must call init first: The init function was not called.

       • you must input correct data: The input data is incorrect.

       • you must input correct type: The input type is incorrect.

3. Secondary verification

1. Determine the result.

   You can determine whether to perform secondary verification based on the cookie and body fields in the response. The header may contain multiple Set-Cookie fields. You must merge them into the cookie format before you call this interface.

   /**
    * Checks whether to perform secondary verification.
    *
    * @param cookie  The response cookie.
    * @param body    The response body.
    * @return 0: Pass, 1: Secondary verification required.
    */
   - (int)cptCheck:(NSString *)cookie body:(NSData *)body;

   • Parameters:

     • cookie: All cookies in the request response. Type: NSString.

     • body: The entire body of the request response. Type: NSData.

   • Return value: The decision result. 0 indicates pass, and 1 indicates that secondary verification is required. Type: int.

   • • Example:

     NSString *cookie = @"key1=value1;key2=value2;";
     NSData *body = xxx;
     int recheck = [[AliTigerTally sharedInstance] cptCheck:cookie body:body];
     NSLog(@"recheck: %d", recheck);

2. Create a slider.

   Based on the result that is returned by cptCheck, you can decide whether to create a slider object. The TTCaptcha object provides the show and dismiss methods to display and hide the slider window. TTOption encapsulates the configurable parameters for the slider. TTListener includes callbacks for two slider statuses. To customize the slider window, you must pass the address of the custom page. You can use local HTML files or remote pages.

   /**
    * Displays the slider for verification.
    *
    * @param view      The parent component.
    * @param option    The parameters.
    * @param detegate  The callback protocol.
    */
   - (TTCaptcha *)cptCreate:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)detegate;
   
   
   @protocol TTDelegate <NSObject>
   @required
   // Slider verification is successful.
   - (void)success:(TTCaptcha *)captcha data:(NSString *)data;
   
   // Slider verification failed.
   - (void)failed:(TTCaptcha *)captcha code:(NSString *)code;
   @end
   
   
   @interface TTOption : NSObject
   // Click to cancel.
   @property (nonatomic, assign) BOOL cancelable;
   
   // Custom page.
   @property (nonatomic, strong) NSString *customUri;
   
   // Language.
   @property (nonatomic, strong) NSString *language;
   @end
   
   
   @interface TTCaptcha : NSObject
   
   - (instancetype)init:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)delegate;
   
   // Obtains the slider traceId for data statistics.
   - (NSString *)getTraceId;
   
   // Displays the slider.
   - (void)show;
   
   // Cancels the slider.
   - (void)dismiss;
   
   @end

   • Parameters:

     • view: The current page view. Type: View.

     • option: The slider configuration parameters. Type: TTOption.

     • listener: The slider status callback. Type: TTDelegate.

   • Return value: The slider object. Type: TTCaptcha.

   • Example:

     #pragma mark - TTDelegate
     - (void)failed:(TTCaptcha *)captcha code:(nonnull NSString *)code {
         NSLog(@"captcha failed: %@", code);
     }
     
     - (void)success:(TTCaptcha *)captcha data:(nonnull NSString *)data {
         NSLog(@"captcha success: %@", data);
     }
     
     TTOption *option = [[TTOption alloc] init];
     // option.customUri = @"ali-tt-captcha-demo-ios";
     option.language   = @"cn";
     option.cancelable = true;
     
     TTCaptcha *captcha = [[AliTigerTally sharedInstance] cptCreate:[self view] option:option delegate:self];
     [captcha show];

     Note

     A Verification failed error indicates that an exception was detected while or after the user moves the slider.

     The detailed error codes are listed below:

     • 1001: Verification failed.

     • 1002: System exception.

     • 1003: Parameter error.

     • 1005: Verification canceled.

     • 8001: Failed to invoke the slider.

     • 8002: The slider verification data is abnormal.

     • 8003: Internal exception during slider verification.

     • 8004: Network error.