Web Application Firewall:Integrate the Android SDK

Background

The app protection SDK signs every request your app sends. WAF verifies these signatures to distinguish legitimate traffic from bots and other malicious actors, protecting your app's backend services.

Limitations

• Supported Android ABI architectures: arm64-v8a and armeabi-v7a

• Minimum Android API level: 16

• After calling init, wait at least 2 seconds before calling vmpSign. The SDK needs this time to fully initialize its security capabilities. This is a recommended delay and can be adjusted as needed. A shorter delay may reduce protection effectiveness.

Prerequisites

Before you begin, ensure that you have:

• The SDK package for Android apps (tigertally-X.Y.Z-xxxxxx-android.tgz), which includes AliTigerTally_X.Y.Z.aar and AliCaptcha_X.Y.Z.aar. To get the SDK, submit a ticket.

• The SDK authentication key (appkey). After you enable Bot Management, go to Bot Management > App Protection and click Obtain and Copy AppKey.

Each Alibaba Cloud account has one unique appkey, which applies to all WAF-protected domains and works across Android, iOS, and HarmonyOS app integrations. Sample appkey format: **OpKLvM6zliu6KopyHIhmneb_u4ekci2W8i6F9vrgpEezqAzEzj2ANrVUhvAXMwYzgY_vc51aEQlRovkRoUhRlVsf4IzO9dZp6nN_Wz8pk2TDLuMo4pVIQvGaxH3vrsnSQiK**

Step 1: Create a project

Open Android Studio and create an Android project using the configuration wizard. The project directory looks like the following:

Step 2: Integrate the AAR package

1. Extract tigertally-X.Y.Z-xxxxxx-android.tgz and copy all AAR files from the resulting folder into the libs directory of your main module. The exact path may vary depending on your project configuration.

   

2. Open build.gradle for your app module. Add the libs directory as a local dependency source and declare compilation dependencies for both AAR files and their required third-party libraries:

   Important

   Replace X.Y.Z in the AAR file names with the actual version number from the SDK package.

   dependencies {
       // ...
       implementation files('libs/AliTigerTally_X.Y.Z.aar')
       implementation files('libs/AliCaptcha_X.Y.Z.aar')
   
       // Required third-party libraries
       implementation 'com.alibaba:fastjson:1.2.83_noneautotype'
       implementation 'com.squareup.okhttp3:okhttp:3.11.0'
       implementation 'com.squareup.okio:okio:1.14.0'
   }

3. If you use ProGuard for code obfuscation, add the following -keep rules to your ProGuard configuration file to preserve the SDK's API methods:

   -keep class com.aliyun.TigerTally.** {*;}
   -keep class com.aliyun.captcha.* {*;}
   -keepclassmembers,allowobfuscation class * {
        @com.alibaba.fastjson.annotation.JSONField <fields>;
   }
   -keep class com.alibaba.fastjson.** {*;}

Step 3: Filter SO CPU architectures

If your project does not already include SO files, add the following ABI filter to your build.gradle file:

android {
    defaultConfig {
        ndk {
            abiFilters 'arm64-v8a', 'armeabi-v7a'
        }
    }
}

Step 4: Declare app permissions

Add the following permissions to your AndroidManifest.xml.

Required:

<uses-permission android:name="android.permission.INTERNET"/>

Optional — grant these to improve device signal collection accuracy:

Install-time permissions are automatically granted at install. Runtime permissions on Android 6.0 and later must be requested dynamically at runtime; they are not automatically granted at install time.

Step 5: Add the integration code

import com.alibaba.fastjson.*;
import com.aliyun.tigertally.*;

public static int setAccount(String account)

// For guest users, skip setAccount and initialize directly.
// After the user logs in, call setAccount and re-initialize.
String account = "user001";
TigerTallyAPI.setAccount(account);

public static int init(Context context, String appkey, int collectType,
                       Map<String, String> otherOptions, TTInitListener listener);

public interface TTInitListener {
    // code: the status code of the initialization call
    void onInitFinish(int code);
}

// Replace with your actual appkey.
final String appkey = "******";

Map<String, String> options = new HashMap<>();
options.put("IPv6", "0");   // Use IPv4
options.put("Intl", "1");   // Report outside the Chinese mainland

// To report to the US (West) site specifically:
// options.put("CustomUrl", "https://cloudauth-device.us-west-1.aliyuncs.com");
// options.put("CustomHost", "cloudauth-device.us-west-1.aliyuncs.com");

// Full data collection
int ret = TigerTallyAPI.init(this.getApplicationContext(), appkey, TigerTallyAPI.TT_DEFAULT, options, null);

// Selective privacy exclusion — combine flags with |
int privacyFlag = TigerTallyAPI.TT_NO_BASIC_DATA | TigerTallyAPI.TT_NO_UNIQUE_DATA;
int ret = TigerTallyAPI.init(this.getApplicationContext(), appkey, privacyFlag, options, null);

// Exclude all privacy data
int ret = TigerTallyAPI.init(this.getApplicationContext(), appkey, TigerTallyAPI.TT_NOT_GRANTED, options, null);

Log.d("AliSDK", "ret:" + ret);

public enum RequestType { GET, POST, PUT, PATCH, DELETE }

public static String vmpHash(RequestType type, byte[] input);

// GET request
String url = "https://tigertally.aliyun.com/apptest";
String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.GET, url.getBytes());
Log.d("AliSDK", "whash:" + whash);

// POST request
String body = "hello world";
String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.POST, body.getBytes());
Log.d("AliSDK", "whash:" + whash);

public static String vmpSign(int type, byte[] input);

// Default signing
String body = "i am the request body, encrypted or not!";
String wtoken = TigerTallyAPI.vmpSign(1, body.getBytes("UTF-8"));
Log.d("AliSDK", "wToken:" + wtoken);

// Custom signing — GET request
String url = "https://tigertally.aliyun.com/apptest";
String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.GET, url.getBytes());
String wtoken = TigerTallyAPI.vmpSign(1, whash.getBytes());
Log.d("AliSDK", "whash:" + whash + ", wtoken:" + wtoken);

// Custom signing — POST request
String body = "hello world";
String whash = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.POST, body.getBytes());
String wtoken = TigerTallyAPI.vmpSign(1, whash.getBytes());
Log.d("AliSDK", "whash:" + whash + ", wtoken:" + wtoken);

public static int cptCheck(String cookie, String body)

String cookie = "key1=value1;key2=value2;";
String body = "....";
int recheck = TigerTallyAPI.cptCheck(cookie, body);
Log.d("AliSDK", "recheck:" + recheck);

public static TTCaptcha cptCreate(Activity activity, TTOption option, TTListener listener);

public interface TTListener {
    void success(TTCaptcha captcha, String data);  // data = certifyId (token)
    void failed(TTCaptcha captcha, String code);   // code = error code
}

TTCaptcha.TTOption option = new TTCaptcha.TTOption();
// option.customUri = "file:///android_asset/ali-tt-captcha-demo.html";
option.language   = "cn";
option.cancelable = false;

TTCaptcha captcha = TigerTallyAPI.cptCreate(this, option, new TTCaptcha.TTListener() {
    @Override
    public void success(TTCaptcha captcha, String data) {
        Log.d(TAG, "captcha check success:" + data);
    }
    @Override
    public void failed(TTCaptcha captcha, String code) {
        Log.d(TAG, "captcha check failed:" + code);
    }
});
captcha.show();

Best practice example

The following end-to-end example shows the complete integration flow: initialization, request signing, sending the request, and handling the CAPTCHA challenge.

package com.aliyun.tigertally.apk;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;
import com.aliyun.TigerTally.TigerTallyAPI;
import com.aliyun.TigerTally.captcha.api.TTCaptcha;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class DemoActivity extends AppCompatActivity {
    private final static String TAG = "TigerTally-Demo";

    private final static String APP_HOST = "******";
    private final static String APP_URL  = "******";
    private final static String APP_KEY  = "******";

    private final static OkHttpClient okHttpClient = new OkHttpClient();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_demo);

        doTest();
    }

    private void doTest() {
        Log.d(TAG, "captcha flow");
        new Thread(() -> {
            // Step 1: Initialize the SDK.
            Map<String, String> options = new HashMap<>();
            // options.put("Intl", "1"); // Uncomment for international reporting.
            int ret = TigerTallyAPI.init(this, APP_KEY, TigerTallyAPI.TT_DEFAULT, options, null);
            // int ret = TigerTallyAPI.init(this, APP_KEY, TigerTallyAPI.TT_NOT_GRANTED, null, null); // No privacy data
            Log.d(TAG, "tiger tally init: " + ret);

            // Step 2: Wait at least 2 seconds before signing — initialization is asynchronous.
            try {
                Thread.sleep(2000);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }

            // Step 3: Sign the request data.
            String data = "hello world";
            String whash = null, wtoken = null;

            // Custom signing
            whash  = TigerTallyAPI.vmpHash(TigerTallyAPI.RequestType.POST, data.getBytes());
            wtoken = TigerTallyAPI.vmpSign(1, whash.getBytes());
            Log.d(TAG, "tiger tally vmp: " + whash + ", " + wtoken);

            // Default signing (no vmpHash needed)
            // wtoken = TigerTallyAPI.vmpSign(1, data.getBytes());
            // Log.d(TAG, "tiger tally vmp: " + wtoken);

            // Step 4: Send the request and check whether a CAPTCHA is required.
            doPost(APP_URL, APP_HOST, whash, wtoken, data, (code, cookie, body) -> {
                int recheck = TigerTallyAPI.cptCheck(cookie, body);
                Log.d(TAG, "captcha check result: " + recheck);

                if (recheck == 0) return;
                this.runOnUiThread(this::doShow);
            });
        }).start();
    }

    // Show the CAPTCHA slider.
    public void doShow() {
        Log.d(TAG, "captcha show");

        TTCaptcha.TTOption option = new TTCaptcha.TTOption();
        // option.customUri = "file:///android_asset/ali-tt-captcha-demo.html";
        option.language   = "cn";
        option.cancelable = false;

        TTCaptcha captcha = TigerTallyAPI.cptCreate(this, option, new TTCaptcha.TTListener() {
            @Override
            public void success(TTCaptcha captcha, String data) {
                Log.d(TAG, "captcha check success:" + data);
            }

            @Override
            public void failed(TTCaptcha captcha, String code) {
                Log.d(TAG, "captcha check failed:" + code);
            }
        });

        captcha.show();
    }

    // Send a POST request with the wToken and optional whash headers.
    public static void doPost(String url, String host, String whash, String wtoken, String body, Callback callback) {
        Log.d(TAG, "start request post");

        int responseCode = 0;
        String responseBody = "";
        StringBuilder responseCookie = new StringBuilder();
        try {
            Request.Builder builder = new Request.Builder()
                    .url(url)
                    .addHeader("wToken", wtoken)  // Required: WAF signature token
                    .addHeader("Host",   host)
                    .post(RequestBody.create(MediaType.parse("text/x-markdown"), body.getBytes()));

            if (whash != null) {
                builder.addHeader("ali_sign_whash", whash);  // Required for custom signing
            }
            Response response = okHttpClient.newCall(builder.build()).execute();

            responseCode = response.code();
            responseBody = response.body() == null ? "" : response.body().string();
            for (String item : response.headers("Set-Cookie")) {
                responseCookie.append(item).append(";");
            }

            Log.d(TAG, "response code:" + responseCode);
            Log.d(TAG, "response cookie:" + responseCookie);
            Log.d(TAG, "response body:" + (responseBody.length() > 100 ? responseBody.substring(0, 100) : ""));

            if (response.isSuccessful()) {
                Log.d(TAG, "success: " + response.code() + ", " + response.message());
            } else {
                Log.e(TAG, "failed: " + response.code() + ", " + response.message());
            }

            response.close();
        } catch (Exception e) {
            e.printStackTrace();
            responseCode = -1;
            responseBody = e.toString();
        } finally {
            if (callback != null) {
                callback.onResponse(responseCode, responseCookie.toString(), responseBody);
            }
        }
    }

    public interface Callback {
        void onResponse(int code, String cookie, String body);
    }
}

After the SDK is integrated, it automatically:

1. Signs every outgoing request with a wToken header for WAF to verify.

2. Optionally attaches an ali_sign_whash header for custom signing scenarios.

3. Enables your app to detect and respond to WAF CAPTCHA challenges.