Web Application Firewall:iOS app SDK integration

Prerequisites

Before you begin, ensure that you have:

• An iOS app running iOS 9.0 or later (earlier versions are not supported)

• The WAF App Protection SDK for iOS — submit a ticket to get it from a product technical expert

• The SDK authentication key (AppKey) — after you enable Bot Management, go to Bot Management > App Protection and click Obtain and Copy AppKey in the app list

The SDK package is named tigertally-X.Y.Z-xxxx-ios.zip (where X.Y.Z is the version number) and contains two framework files and two xcframework files. Each Alibaba Cloud account has one AppKey that applies to all WAF-protected domains and works across Android, iOS, and HarmonyOS integrations.

Example AppKey: **OpKLvM6zliu6KopyHIhmneb_u4ekci2W8i6F9vrgpEezqAzEzj2ANrVUhvAXMwYzgY_vc51aEQlRovkRoUhRlVsf4IzO9dZp6nN_Wz8pk2TDLuMo4pVIQvGaxH3vrsnSQiK**

Choose an SDK version

The iOS SDK comes in two versions. Choose based on whether your app uses the identifier for advertisers (IDFA):

Step 1: Create a project

Create a new iOS project in Xcode and complete the setup wizard.

Step 2: Add the framework files

Add the main SDK framework to your project. Choose the version that matches your IDFA requirements.

IDFA version:

Non-IDFA version:

Add the CAPTCHA module framework AliCaptcha.framework to your project:

Add the resource bundle AliCaptcha.bundle to your project:

Step 3: Add dependency libraries

Add the following libraries under Link Binary With Libraries in your target's build phases:

Step 4: Configure linker flags

In Build Settings, add -ObjC to Other Linker Flags:

Step 5: Add integration code

#import <AliTigerTally_IDFA/AliTigerTally.h>

#import <AliTigerTally_NOIDFA/AliTigerTally.h>

- (int)init:(NSString *)appkey
    collectType:(TTCollectType)type
    options:(NSMutableDictionary *_Nullable)options
    listener:(TTInitListener _Nullable)onInitFinish;

NSString *appKey = @"<your-appkey>";

NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
[options setValue:@"0" forKey:@"IPv6"];  // Use IPv4
[options setValue:@"0" forKey:@"Intl"];  // Report from the Chinese mainland
// [options setValue:@"1" forKey:@"Intl"];  // Report from outside the Chinese mainland

// To report to US (Silicon Valley):
// [options setValue:@"https://cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomUrl"];
// [options setValue:@"cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomHost"];

// Full data collection
if (0 == [[AliTigerTally sharedInstance] init:appKey collectType:TT_DEFAULT options:options listener:nil]) {
    NSLog(@"Initialization successful");
} else {
    NSLog(@"Initialization failed");
}

// Custom privacy: exclude basic and extended device data
TTCollectType collectPrivacy = TT_NO_BASIC_DATA | TT_NO_EXTRA_DATA;
[[AliTigerTally sharedInstance] init:appKey collectType:collectPrivacy options:options listener:nil];

// Non-privacy: exclude all privacy fields
[[AliTigerTally sharedInstance] init:appKey collectType:TT_NOT_GRANTED options:options listener:nil];

/**
 * Sets the user account.
 * @param account  A desensitized string identifying the user.
 */
- (void)setAccount:(NSString *)account;

[[AliTigerTally sharedInstance] setAccount:@"<desensitized-user-id>"];

/**
 * Signs data using VMP technology.
 * @param input  The data to sign (request body, or nil for empty body).
 * @return The wtoken string for request authentication.
 */
- (NSString *)vmpSign:(NSData *)input;

NSString *body = @"hello world";
NSString *wtoken = [[AliTigerTally sharedInstance]
    vmpSign:[body dataUsingEncoding:NSUTF8StringEncoding]];
// Attach wtoken to the "wToken" HTTP request header

/**
 * Hashes data for custom signing.
 * @param type   The HTTP method (TT_GET, TT_POST, TT_PUT, TT_PATCH, TT_DELETE).
 * @param input  The data to hash (request body for POST/PUT/PATCH; full URL for GET/DELETE).
 * @return The whash string.
 */
- (NSString *)vmpHash:(TTRequestType)type input:(NSData *)input;

NSString *body = @"hello world";

// Generate whash from the request body
NSString *whash = [[AliTigerTally sharedInstance]
    vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];

// Generate wtoken from the whash
NSString *wtoken = [[AliTigerTally sharedInstance]
    vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];

// Attach whash to "ali_sign_whash" header and wtoken to "wToken" header
NSLog(@"whash: %@, wtoken: %@", whash, wtoken);

NSString *url = @"https://tigertally.aliyun.com/apptest";

// Generate whash from the full URL
NSString *whash = [[AliTigerTally sharedInstance]
    vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];

// Generate wtoken from the whash
NSString *wtoken = [[AliTigerTally sharedInstance]
    vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];

/**
 * Checks whether secondary verification is required.
 * @param cookie  All cookies from the response (merged into "key=value;" format).
 * @param body    The full response body.
 * @return 0: pass. 1: secondary verification required.
 */
- (int)cptCheck:(NSString *)cookie body:(NSData *)body;

NSString *cookie = @"key1=value1;key2=value2;";
NSData *body = /* response body */;
int recheck = [[AliTigerTally sharedInstance] cptCheck:cookie body:body];
// recheck == 1: show CAPTCHA slider

/**
 * Creates a CAPTCHA slider for secondary verification.
 * @param view      The parent view.
 * @param option    Slider configuration.
 * @param delegate  Callback for verification results.
 * @return The TTCaptcha slider object.
 */
- (TTCaptcha *)cptCreate:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)delegate;

@protocol TTDelegate <NSObject>
@required
// Called when verification succeeds.
- (void)success:(TTCaptcha *)captcha data:(NSString *)data;

// Called when verification fails.
- (void)failed:(TTCaptcha *)captcha code:(NSString *)code;
@end

TTOption *option = [[TTOption alloc] init];
option.language   = @"cn";
option.cancelable = YES;

TTCaptcha *captcha = [[AliTigerTally sharedInstance]
    cptCreate:[self view] option:option delegate:self];
[captcha show];

// In TTDelegate callbacks:
- (void)success:(TTCaptcha *)captcha data:(nonnull NSString *)data {
    NSLog(@"Verification passed: %@", data);
}

- (void)failed:(TTCaptcha *)captcha code:(nonnull NSString *)code {
    NSLog(@"Verification failed with code: %@", code);
}

Initialization status codes

CAPTCHA error codes

Troubleshooting

`vmpSign` or `vmpHash` returns an error string instead of a token

If whash or wtoken contains one of the following strings, an error occurred:

• "you must call init first" — init was not called before signing. Call init and wait at least 2 seconds before calling vmpSign.

• "you must input correct data" — The input data is invalid. Check that the request body or URL is not empty or malformed.

• "you must input correct type" — The HTTP method type passed to vmpHash is incorrect.

URL encoding mismatch in GET request signing

If the whash for a GET request is rejected, the URL passed to vmpHash may not match the actual request URL. Some networking frameworks automatically percent-encode query parameters or Chinese characters. Log both URLs and compare them character by character.

Initialization fails with `TT_NETWORK_ERROR` (`-4`)

Check that the device has network access and that the reporting domain is reachable. If you are deploying outside the Chinese mainland, set Intl to 1 in the options dictionary. For a specific regional endpoint, set CustomUrl and CustomHost.

Complete example

The following example shows the full integration flow — initialization, request signing, secondary verification check, and CAPTCHA display.

#import "DemoController.h"
#if __has_include(<AliTigerTally_NOIDFA/AliTigerTally_NOIDFA.h>)
    #import <AliTigerTally_NOIDFA/AliTigerTally_NOIDFA.h>
#else
    #import <AliTigerTally_IDFA/AliTigerTally_IDFA.h>
#endif

@interface DemoController () <TTDelegate>
@end

static NSString *kAppHost = @"******";
static NSString *kAppUrl  = @"******";
static NSString *kAppkey  = @"******";

@implementation DemoController

- (void)viewDidLoad {
    [super viewDidLoad];
    [self doTest];
}

- (void)doTest {
    NSThread *thread = [[NSThread alloc] initWithBlock:^{
        // Step 1: Initialize the SDK
        NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
        // [options setValue:@"1" forKey:@"Intl"];  // Uncomment for outside the Chinese mainland
        int code = [[AliTigerTally sharedInstance] init:kAppkey collectType:TT_DEFAULT options:options listener:nil];
        NSLog(@"tigertally init: %d", code);

        // Step 2: Wait at least 2 seconds before signing
        [NSThread sleepForTimeInterval:2.0];

        // Step 3: Sign the request (custom signing example)
        NSString *body = @"hello world";
        NSString *whash = [[AliTigerTally sharedInstance]
            vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
        NSString *wtoken = [[AliTigerTally sharedInstance]
            vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
        NSLog(@"tigertally vmp — whash: %@, wtoken: %@", whash, wtoken);

        // For default signing (no custom signing option selected):
        // wtoken = [[AliTigerTally sharedInstance] vmpSign:[body dataUsingEncoding:NSUTF8StringEncoding]];

        // Step 4: Send the request and check for secondary verification
        [self doPost:kAppUrl host:kAppHost whash:whash wtoken:wtoken
            body:[body dataUsingEncoding:NSUTF8StringEncoding]
            callback:^(NSInteger code, NSString *cookie, NSData *body) {
                int check = [[AliTigerTally sharedInstance] cptCheck:cookie body:body];
                NSLog(@"captcha check result: %d", check);
                if (check == 0) return;
                // Secondary verification required — show CAPTCHA on main thread
                [[NSOperationQueue mainQueue] addOperationWithBlock:^{
                    [self doShow];
                }];
            }];
    }];
    [thread start];
}

- (void)doShow {
    TTOption *option = [[TTOption alloc] init];
    option.language   = @"cn";
    option.cancelable = YES;
    TTCaptcha *captcha = [[AliTigerTally sharedInstance]
        cptCreate:[self view] option:option delegate:self];
    [captcha show];
}

- (void)doPost:(NSString *)url host:(NSString *)host
        whash:(NSString *)whash wtoken:(NSString *)wtoken
        body:(NSData *)body callback:(void(^)(NSInteger code, NSString *cookie, NSData *body))callback {
    NSURL *requestUrl = [NSURL URLWithString:url];
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:requestUrl
        cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval:10];
    [request setValue:@"text/x-markdown" forHTTPHeaderField:@"Content-Type"];
    [request setValue:host forHTTPHeaderField:@"HOST"];
    [request setValue:wtoken forHTTPHeaderField:@"wToken"];
    if (whash) {
        [request setValue:whash forHTTPHeaderField:@"ali_sign_whash"];
    }
    request.HTTPMethod = @"POST";
    request.HTTPBody = body;

    NSURLSessionDataTask *dataTask = [[NSURLSession sharedSession]
        dataTaskWithRequest:request
        completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
            if (error) {
                callback(-1, nil, [[error description] dataUsingEncoding:NSUTF8StringEncoding]);
                return;
            }
            NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *)response;
            NSMutableString *cookies = [[NSMutableString alloc] init];
            for (NSHTTPCookie *cookie in [[NSHTTPCookieStorage sharedHTTPCookieStorage] cookies]) {
                if ([url containsString:[cookie domain]]) {
                    [cookies appendFormat:@"%@=%@;", [cookie name], [cookie value]];
                }
            }
            callback(httpResponse.statusCode, cookies, data);
        }];
    [dataTask resume];
}

#pragma mark - TTDelegate

- (void)failed:(TTCaptcha *)captcha code:(nonnull NSString *)code {
    NSLog(@"captcha failed: %@", code);
    UIAlertController *alert = [UIAlertController alertControllerWithTitle:nil
        message:code preferredStyle:UIAlertControllerStyleAlert];
    [alert addAction:[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:nil]];
    [self presentViewController:alert animated:YES completion:nil];
}

- (void)success:(TTCaptcha *)captcha data:(nonnull NSString *)data {
    NSLog(@"captcha success: %@", data);
    UIAlertController *alert = [UIAlertController alertControllerWithTitle:nil
        message:data preferredStyle:UIAlertControllerStyleAlert];
    [alert addAction:[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:nil]];
    [self presentViewController:alert animated:YES completion:nil];
}

@end