Android Application Integration¶

dependencies {
    //Add SDK dependency
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
    //Dependency to capture native layer crash information, needs to be used with ft-sdk and cannot be used alone
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:[latest_version]'
    //Recommended to use this version; other versions have not undergone sufficient compatibility testing
    implementation 'com.google.code.gson:gson:2.8.5'

}
//Apply the plugin
apply plugin: 'ft-plugin'   //If using legacy version compatible ft-plugin-legacy, no changes needed
//Configure plugin parameters
FTExt {
    //Whether to display Plugin logs, default is false
    showLog = true

    //Set ASM version, supports asm7 - asm9, default is asm9
    //asmVersion='asm7'

    //ASM ignore path configuration, paths are equivalent with . and /
    //ignorePackages=['com.ft','com/ft']

    // Native so specified path, only need to specify the upper directory of the abi file
    // |-stripped_native_libs
    //      |-release
    //          |-out
    //          |-lib
    //              |-arm64-v8a
    //              |-armeabi-v7a
    //              |-...
    //nativeLibPath='/build/intermediates/merged_native_libs/release/out/lib'
}
android{
    //... Omitted part of the code
    defaultConfig {
        //... Omitted part of the code
        ndk {
            //When using ft-native to capture native layer crash information, choose supported abi architectures based on the application's compatibility with different platforms.
            //Currently, ft-native includes abi architectures 'arm64-v8a',
            // 'armeabi-v7a', 'x86', 'x86_64'
            abiFilters 'armeabi-v7a'
        }
    }
    compileOptions {
        sourceCompatibility = 1.8
        targetCompatibility = 1.8
    }
}

<application 
       android:name="YourApplication"> 
</application> 

| **Method Name** | **Required** | **Meaning** | **Description** |
| --- | --- | --- | --- |
| NetStatusBean.fetchStartTime | No | Request start time | |
| NetStatusBean.tcpStartTime | No | TCP connection time |  |
| NetStatusBean.tcpEndTime | No | TCP end time |  |
| NetStatusBean.dnsStartTime | No | DNS start time |  |
| NetStatusBean.dnsEndTime | No | DNS end time | |
| NetStatusBean.responseStartTime | No | Response start time |  |
| NetStatusBean.responseEndTime | No | Response end time |  |
| NetStatusBean.sslStartTime | No | SSL start time |  |
| NetStatusBean.sslEndTime | No | SSL end time | |
| NetStatusBean.property| No | Additional attributes | |
| ResourceParams.url | Yes | URL address | |
| ResourceParams.requestHeader | No | Request header parameters |  |
| ResourceParams.responseHeader | No | Response header parameters |  |
| ResourceParams.responseConnection | No | Response connection | |
| ResourceParams.responseContentType | No | Response ContentType | |
| ResourceParams.responseContentEncoding | No | Response ContentEncoding |  |
| ResourceParams.resourceMethod | No | Request method | GET, POST etc. |
| ResourceParams.responseBody | No | Returned body content | |
| ResourceParams.property| No | Additional attributes |  |

## Logger Log Printing {#log} 
Use `FTLogger` for custom log output, requiring enabling `FTLoggerConfig.setEnableCustomLog(true)`
> Current log content limit is 30 KB, exceeding characters will be truncated.

### Usage Method

=== "Java"

    ```java

        /**
         * Store a single log data locally for synchronization
         *
         * @param content Log content
         * @param status  Log level, enum Status
         * @param property Additional attributes (optional)
         */
        public void logBackground(String content, Status status, HashMap<String, Object> property)

        /**
         * Store a single log data locally for synchronization
         *
         * @param content Log content
         * @param status  Log level, String
         * @param property Additional attributes (optional)
         */
        public void logBackground(String content, String status, HashMap<String, Object> property)

        /**
         * Store multiple log data locally for synchronization
         *
         * @param logDataList {@link LogData} list
         */
        public void logBackground(List<LogData> logDataList)

    ```

=== "Kotlin"

    ```kotlin

        /**
         * Store a single log data locally for synchronization
         *
         * @param content Log content
         * @param status  Log level
         * @param property Log attributes (optional)
         */
        fun logBackground(content: String, status: Status, property: HashMap<String, Any>)


        /**
         * Store a single log data locally for synchronization
         *
         * @param content Log content
         * @param status  Log level
         * @param property Log attributes (optional)
         */
        fun logBackground(content: String, status: String, property: HashMap<String, Any>)

        /**
         * Store multiple log data locally for synchronization
         *
         * @param logDataList Log data list
         */
        fun logBackground(logDataList: List<LogData>)

    ```

#### Log Levels

| **Method Name** | **Meaning** |
| --- | --- |
| Status.DEBUG | Debug |
| Status.INFO | Info |
| Status.WARNING | Warning |
| Status.ERROR | Error |
| Status.CRITICAL | Critical |
| Status.OK | Recovered |

### Code Example


=== "Java"

    ```java
    // Upload a single log
    FTLogger.getInstance().logBackground("test", Status.INFO);

    // Pass parameters to HashMap
    HashMap<String, Object> map = new HashMap<>();
    map.put("ft_key", "ft_value");
    FTLogger.getInstance().logBackground("test", Status.INFO, map);

    // Batch upload logs
    List<LogData> logList = new ArrayList<>();
    logList.add(new LogData("test", Status.INFO));
    FTLogger.getInstance().logBackground(logList);
    ```

=== "Kotlin"

    ```kotlin
    //Upload a single log
    FTLogger.getInstance().logBackground("test", Status.INFO)

    //Pass parameters to HashMap
    val map = HashMap<String,Any>()
    map["ft_key"]="ft_value"
    FTLogger.getInstance().logBackground("test", Status.INFO,map)

    //Batch upload logs
    FTLogger.getInstance().logBackground(mutableListOf(LogData("test",Status.INFO)))
    ```

## Tracer Network Trace Link

Configure `FTTraceConfig` to enable `enableAutoTrace` to automatically add trace data or manually use `FTTraceManager` in HTTP requests with `Propagation Header`, as follows:

=== "Java"

    ```java
    String url = "https://guance.com";
    String uuid = "uuid";
    // Get trace header parameters
    Map<String, String> headers = FTTraceManager.get().getTraceHeader(uuid, url);

    OkHttpClient client = new OkHttpClient.Builder().addInterceptor(chain -> {
        Request original = chain.request();
        Request.Builder requestBuilder = original.newBuilder();
        // Add trace header parameters in the request
        for (String key : headers.keySet()) {
            requestBuilder.header(key, headers.get(key));
        }
        Request request = requestBuilder.build();

        Response response = chain.proceed(request);

        if (response != null) {
            Map<String, String> requestHeaderMap = new HashMap<>();
            Map<String, String> responseHeaderMap = new HashMap<>();
            for (Pair<String, String> header : response.request().headers()) {
                requestHeaderMap.put(header.first, header.second);
            }
            for (Pair<String, String> header : response.headers()) {
                responseHeaderMap.put(header.first, header.second);
            }
        }

        return response;
    }).build();

    Request.Builder builder = new Request.Builder().url(url).method(RequestMethod.GET.name(), null);
    client.newCall(builder.build()).execute();
    ```

=== "Kotlin"

    ```kotlin
    val url = "https://guance.com"
    val uuid ="uuid"
    //Get trace header parameters
    val headers = FTTraceManager.get().getTraceHeader(uuid, url)

    val client: OkHttpClient = OkHttpClient.Builder().addInterceptor { chain ->

                        val original = chain.request()
                        val requestBuilder = original.newBuilder()
                        //Add trace header parameters in the request
                        for (key in headers.keys) {
                            requestBuilder.header(key!!, headers[key]!!)
                        }
                        val request = requestBuilder.build()

                        response = chain.proceed(request)

                        if (response != null) {
                            val requestHeaderMap = HashMap<String, String>()
                            val responseHeaderMap = HashMap<String, String>()
                            request.headers.forEach {
                                requestHeaderMap[it.first] = it.second
                            }
                            response!!.headers.forEach {
                                responseHeaderMap[it.first] = it.second

                            }

                        }

                        response!!
                    }.build()

     val builder: Request.Builder = Request.Builder().url(url).method(RequestMethod.GET.name, null)
    client.newCall(builder.build()).execute()
    ```

## Customizing Resource and TraceHeader via OKHttp Interceptor {#okhttp_resource_trace_interceptor_custom}

When both `FTRUMConfig`'s `enableTraceUserResource` and `FTTraceConfig`'s `enableAutoTrace` configurations are enabled, custom `Interceptor` configurations have priority.
> For ft-sdk versions < 1.4.1, disable `FTRUMConfig`'s `enableTraceUserResource` and `FTTraceConfig`'s `enableAutoTrace`.
> For ft-sdk versions > 1.6.7, support associating custom Trace Headers with RUM data

=== "Java"

    ```java
     new OkHttpClient.Builder()
            .addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
                   @Override
                   public HashMap<String, String> getTraceHeader(Request request) {
                       HashMap<String, String> map = new HashMap<>();
                       map.put("custom_header","custom_value");
                       return map;
                  }

                 // Supported in versions 1.6.7 and above
                  @Override
                  public String getSpanID() {
                    return "span_id";
                 }
                // Supported in versions 1.6.7 and above
                 @Override
                 public String getTraceID() {
                    return "trace_id";
                 }
            }))
           .addInterceptor(new FTResourceInterceptor(new FTResourceInterceptor.ContentHandlerHelper() {
               @Override
               public void onRequest(Request request, HashMap<String, Object> extraData) {
                   String contentType = request.header("Content-Type");
                   extraData.put("df_request_header", request.headers().toString());
                   if ("application/json".equals(contentType) ||
                           "application/x-www-form-urlencoded".equals(contentType) ||
                           "application/xml".equals(contentType)) {
                       extraData.put("df_request_body", request.body());


               @Override
               public void onResponse(Response response, HashMap<String, Object> extraData) throws IOException {
                   String contentType = response.header("Content-Type");
                   extraData.put("df_response_header", response.headers().toString());
                   if ("application/json".equals(contentType) ||
                           "application/xml".equals(contentType)) {
                       // Copy part of the body to avoid consuming large data
                       ResponseBody body = response.peekBody(33554432);
                       extraData.put("df_response_body", body.string());
                   }

               @Override
               public void onException(Exception e, HashMap<String, Object> extraData)
               }
           }))
           .eventListenerFactory(new FTResourceEventListener.FTFactory())
           .build();
    ```

=== "Kotlin"

    ```kotlin
    OkHttpClient.Builder()
    .addInterceptor(FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler {
        override fun getTraceHeader(request: Request): HashMap<String, String> {
            val map = HashMap<String, String>()
            map["custom_header"] = "custom_value"
            return map
        }
    }))
    .addInterceptor(FTResourceInterceptor(object : FTResourceInterceptor.ContentHandlerHelper {
        override fun onRequest(request: Request, extraData: HashMap<String, Any>) {
            val contentType = request.header("Content-Type")
            extraData["df_request_header"] = request.headers().toString()
            if ("application/json" == contentType ||
                "application/x-www-form-urlencoded" == contentType ||
                "application/xml" == contentType) {
                extraData["df_request_body"] = request.body()
            }
        }

        override fun onResponse(response: Response, extraData: HashMap<String, Any>) {
            val contentType = response.header("Content-Type")
            extraData["df_response_header"] = response.headers().toString()
            if ("application/json" == contentType ||
                "application/xml" == contentType) {
                // Copy part of the response body to avoid consuming large data
                val body = response.peekBody(33554432)
                extraData["df_response_body"] = body.string()
            }
        }

        override fun onException(e: Exception, extraData: HashMap<String, Any>) {
            // Handle exception situation
        }
    }))
    .eventListenerFactory(FTResourceEventListener.FTFactory())
    .build()
    ```

## Binding and Unbinding User Information {#userdata-bind-and-unbind}
Use `FTSdk` for binding and unbinding user information 

### Usage Method

=== "Java"

    ```java

       /**
         * Bind user information
         *
         * @param id
         */
        public static void bindRumUserData(@NonNull String id)

        /**
         * Bind user information
         */
        public static void bindRumUserData(@NonNull UserData data)
    ```

=== "Kotlin"

    ``` kotlin
    /**
         * Bind user information
         *
         * @param id User ID
         */
        fun bindRumUserData(id: String) {
            // TODO: implement bindRumUserData method
        }

        /**
         * Bind user information
         *
         * @param data User information
         */
        fun bindRumUserData(data: UserData) {
            // TODO: implement bindRumUserData method
        }
    ```


#### UserData
| **Method Name** | **Meaning** | **Required** | **Description** |
| --- | --- | --- | --- |
| setId | Set user ID | No | |
| setName | Set username | No | |
| setEmail | Set email | No | |
| setExts | Set user extensions | No | Refer to [here](#key-conflict) for addition rules|

### Code Example

=== "Java"

    ```java
    // You can call this method after successful user login to bind user information
    FTSdk.bindRumUserData("001");

    UserData userData = new UserData();
    userData.setName("test.user");
    userData.setId("test.id");
    userData.setEmail("test@mail.com");
    Map<String, String> extMap = new HashMap<>();
    extMap.put("ft_key", "ft_value");
    userData.setExts(extMap);
    FTSdk.bindRumUserData(userData);

    // You can call this method after user logout to unbind user information
    FTSdk.unbindRumUserData();

    ```

=== "Kotlin"

    ```kotlin
    //You can call this method after successful user login to bind user information
    FTSdk.bindRumUserData("001")


    //Bind more user data
    val userData = UserData()
    userData.name = "test.user"
    userData.id = "test.id"
    userData.email = "test@mail.com"
    val extMap = HashMap<String, String>()
    extMap["ft_key"] = "ft_value"
    userData.setExts(extMap)
    FTSdk.bindRumUserData(userData)

    //You can call this method after user logout to unbind user information
    FTSdk.unbindRumUserData()
    ```


## Closing SDK
Use `FTSdk` to close the SDK 

### Usage Method
=== "Java"

    ```java
        /**
         * Close running objects within the SDK
         */
        public static void shutDown()

    ```

=== "Kotlin"


    ``` kotlin
        /**
         * Close running objects within the SDK
         */
        fun shutDown()
    ```

### Code Example

=== "Java"

    ```java
    //If dynamically changing SDK configuration, need to close first to avoid incorrect data generation
    FTSdk.shutDown();
    ```

=== "Kotlin"

    ```kotlin
    //If dynamically changing SDK configuration, need to close first to avoid incorrect data generation
    FTSdk.shutDown()
    ```

## Clearing Cached Data in SDK
Use `FTSdk` to clear uncaptured cached data 

### Usage Method
=== "Java"

    ```java
        /**
         * Clear uncaptured cached data
         */
        public static void clearAllData()

    ```

=== "Kotlin"


    ``` kotlin
         /**
          * Clear uncaptured cached data
          */
        fun clearAllData()
    ```

### Code Example

=== "Java"

    ```java
    FTSdk.clearAllData();
    ```

=== "Kotlin"

    ```kotlin
    FTSdk.clearAllData()
    ```

## Actively Synchronizing Data
Use `FTSdk` to actively synchronize data.
> FTSdk.setAutoSync(false) requires manual data synchronization

### Usage Method

=== "Java"

    ```java
       /**
         * Actively synchronize data
         */
        public static void flushSyncData()
    ```

=== "Kotlin"

    ```kotlin
       /**
         * Actively synchronize data
         */
        fun flushSyncData()
    ```

### Code Example

=== "Java"

    ```java
    FTSdk.flushSyncData()
    ```

=== "Kotlin"

    ```kotlin
    FTSdk.flushSyncData()
    ```



## Dynamically Enable or Disable Getting AndroidID
Use `FTSdk` to set whether to get Android ID in the SDK

### Usage Method

=== "Java"

    ```java
       /**
         * Dynamically control getting Android ID
         *
         * @param enableAccessAndroidID Apply if true, do not apply if false
         */
        public static void setEnableAccessAndroidID(boolean enableAccessAndroidID)
    ```

=== "Kotlin"

    ```kotlin
       /**
         * Dynamically control getting Android ID
         *
         * @param enableAccessAndroidID Apply if true, do not apply if false
         */
        fun setEnableAccessAndroidID(enableAccessAndroidID:Boolean)
    ```

### Code Example

=== "Java"

    ```java
    // Enable getting Android ID
    FTSdk.setEnableAccessAndroidID(true);

    // Disable getting Android ID
    FTSdk.setEnableAccessAndroidID(false);
    ```

=== "Kotlin"

    ```kotlin
    //Enable getting Android ID
    FTSdk.setEnableAccessAndroidID(true)

    //Disable getting Android ID
    FTSdk.setEnableAccessAndroidID(false)
    ```

## Adding Custom Tags

Use `FTSdk` to dynamically add tags while the SDK is running

### Usage Method

=== "Java"

    ```java
    /**
     * Dynamically set global tag
     * @param globalContext
     */
    public static void appendGlobalContext(HashMap<String,Object> globalContext)

    /**
     * Dynamically set RUM global tag
     * @param globalContext
     */
    public static void appendRUMGlobalContext(HashMap<String,Object> globalContext)

    /**
     * Dynamically set log global tag
     * @param globalContext
     */
    public static void appendLogGlobalContext(HashMap<String,Object> globalContext)

    ```

=== "Kotlin"

    ```kotlin
    /**
     * Dynamically set global tag
     * @param globalContext
     */
    fun appendGlobalContext(globalContext: HashMap<String, Any>) 

    /**
     * Dynamically set RUM global tag
     * @param globalContext
     */
    fun appendRUMGlobalContext(globalContext: HashMap<String, Any>) 

    /**
     * Dynamically set log global tag
     * @param globalContext
     */
    fun appendLogGlobalContext(globalContext: HashMap<String, Any>)

    ```

### Code Example

=== "Java"

    ```java
    HashMap<String, Object> globalContext = new HashMap<>();
    globalContext.put("global_key", "global_value");
    FTSdk.appendGlobalContext(globalContext);

    HashMap<String, Object> rumGlobalContext = new HashMap<>();
    rumGlobalContext.put("rum_key", "rum_value");
    FTSdk.appendRUMGlobalContext(rumGlobalContext);

    HashMap<String, Object> logGlobalContext = new HashMap<>();
    logGlobalContext.put("log_key", "log_value");
    FTSdk.appendLogGlobalContext(logGlobalContext);
    ```

=== "Kotlin"

    ```kotlin
    val globalContext = hashMapOf<String, Any>(
        "global_key" to "global_value"
    )
    FTSdk.appendGlobalContext(globalContext)

    val rumGlobalContext = hashMapOf<String, Any>(
        "rum_key" to "rum_value"
    )
    FTSdk.appendRUMGlobalContext(rumGlobalContext)

    val logGlobalContext = hashMapOf<String, Any>(
        "log_key" to "log_value"
    )
    FTSdk.appendLogGlobalContext(logGlobalContext)
    ```

## R8 / Proguard Obfuscation Configuration {#r8_proguard}

```java
-dontwarn com.ft.sdk.**

### ft-sdk library
-keep class com.ft.sdk.**{*;}

### ft-native library
-keep class ftnative.*{*;}

### Prevent Action from obfuscating action_name during acquisition###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem

FTExt {
    //...
    autoUploadMap = true
    autoUploadNativeDebugSymbol = true
    datakitUrl = 'https://datakit.url'  // datakit reporting address, generateSourceMapOnly=true does not require configuration
    datawayToken = 'dataway_token'      // space token, generateSourceMapOnly=true does not require configuration
    appId = "appid_xxxxx"               // appid, generateSourceMapOnly=true does not require configuration
    env = 'common'                      // environment, generateSourceMapOnly=true does not require configuration
    generateSourceMapOnly = false //only generate sourcemap, default is false, path example: /app/build/tmp/ft{flavor}SourceMapMerge-release.zip, ft-plugin:1.3.4 and above versions support

    prodFlavors { //prodFlavors configuration overrides outer settings
        prodTest {
            autoUploadMap = false
            autoUploadNativeDebugSymbol = false
            datakitUrl = 'https://datakit.url'
            datawayToken = 'dataway_token'
            appId = "appid_prodTest"
            env = "gray"
        }
        prodPublish {
            autoUploadMap = true
            autoUploadNativeDebugSymbol = true
            datakitUrl = 'https://datakit.url'
            datawayToken = 'dataway_token'
            appId = "appid_prodPublish"
            env = "prod"
        }
    }
}

android{
    //…
    productFlavors {
        prodTest {
            buildConfigField "String", "CUSTOM_VALUE", "\"Custom Test Value\""
            //…
        }
        prodPublish {
            buildConfigField "String", "CUSTOM_VALUE", "\"Custom Publish Value\""
            //…
        }
    }
}

//SDK initialization pseudocode, set tags after obtaining parameters from the network

FTSdk.init() 

getInfoFromNet(info){
    HashMap<String, Object> globalContext = new HashMap<>();
    globalContext.put("delay_key", info.value);
    FTSdk.appendGlobalContext(globalContext)
}