Quick Tracking:Android SDK

1. Code integration details

The A/B Testing SDK depends on the Android SDK v1.6.4 or later. Before you can use the A/B Testing SDK, you must integrate and initialize the Quick Tracking Statistical Analysis SDK. For more information, see Import and configure the SDK.

2. Programmatic experiments

2.1 Integrate and initialize the SDK

First, initialize the Quick Tracking Statistical Analysis SDK in synchronous mode. After the Statistical Analysis SDK is initialized, you can initialize the Quick Tracking A/B Testing SDK. During the A/B Testing SDK initialization, you must provide the service endpoint for experiment requests. You can obtain this endpoint from your operations personnel.

2.1.1 Synchronous import method

In the build.gradle file of the main module, add the Quick Tracking A/B Testing SDK dependency:

Online package:

dependencies {
    implementation fileTree(include the following:['*.jar'], dir:'libs')

    // Quick Tracking Statistical Analysis SDK 
    implementation 'com.lydaas.qtsdk:qt-px-common:1.8.9.PX'
    // Quick Tracking A/B Test SDK
    implementation 'com.lydaas.qtsdk:qt-ab-test:1.1.0'
  
}

Local package:

dependencies {
    implementation fileTree(include the following:['*.jar'], dir:'libs')
    // Quick Tracking Statistical Analysis SDK 
    implementation files('libs/qt-px-common-1.8.9.PX.aar')
    // Quick Tracking A/B Test SDK
    implementation files('libs/QTABTest-release.aar')

}

2.1.2 SDK initialization

SDK initialization depends on ApplicationContext. You must pass the corresponding parameters at the appropriate time:

import com.quicktracking.sdk.android.abtest.QTABTest;
import com.quicktracking.sdk.android.abtest.QTABTestConfigOptions;

try {
    // Initialize the Quick Tracking A/B Testing SDK. This method fully relies on the data collection SDK to report data.
   QTABTestConfigOptions config = new QTABTestConfigOptions("YOUR_DATA_COLLECTION_ENDPOINT/abtest_results?appkey=xxxxx");
   // Initialize the Quick Tracking A/B Testing SDK. This method does not fully rely on the data collection SDK and is used only for A/B tests.
   QTABTestConfigOptions config = new QTABTestConfigOptions("YOUR_DATA_COLLECTION_ENDPOINT/abtest_results?appkey=xxxxx",10 * 60 * 1000,"custom_device_id", new IQTABTestPropertyChanged() {
        @Override
        public void onPropertyChanged(JSONArray abParams) {
            Log.d("ABTest", "onPropertyChanged: " + abParams.toString());
        }
    });
  
    // Initialization requires passing the Context.
   QTABTest.startWithConfigOptions(this.getApplicationContext(), config);
} catch (Exception e) {
    e.printStackTrace();
}

Configuration methods:

public QTABTestConfigOptions(String url,int timeInterval)
public QTABTestConfigOptions(String url)
public QTABTestConfigOptions(String url,int timeInterval, String customDeviceId, IQTABTestPropertyChanged iQTABTestPropertyChanged)

import com.quicktracking.sdk.android.abtest;

/**
 * Defines the IQTABTestPropertyChanged interface to listen for property change events.
 * 
 * <p>This interface includes one method, {@link #onPropertyChanged(JSONArray)}, which is called when a property changes.
 * 
 * @see JSONArray
 */
 
public interface IQTABTestPropertyChanged {

    /**
     * The callback method triggered when a property changes.
     * 
     * @param abParams A JSON array that contains information about the property changes.
     *                 This parameter is typically used to pass specific data or context information about the property changes.
     */
    void onPropertyChanged(JSONArray abParams);
}

2.1.3 Obfuscation configuration

If your application uses code obfuscation, add the following configurations. This prevents the Quick Tracking and A/B Testing SDKs from being incorrectly obfuscated, which would render them unusable.

-keep class com.umeng.** {*;}
-keep class org.repackage.** {*;}

-keep class com.quick.qt.** {*;}
-keep class rpk.quick.qt.** {*;}

# For AB Test
-keep class com.quicktracking.sdk.android.abtest.** {*;}

-keepclassmembers class * {
   public <init> (org.json.JSONObject);
}
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

2.2 Get experiment variables

After you initialize the Quick Tracking A/B Test SDK, you can use an API to retrieve the variable values for a specific experiment. There are three strategies to retrieve experiment variables:

• fetchABTestFromCache: Reads from the local cache. If the cache does not exist, the default value is used.

• fetchABTestFromServer: Ignores the local cache and retrieves data from the server.

• fetchABTestFromCacheThenServer: Reads from the local cache first. If the cache does not exist, it retrieves data from the server.

2.2.1 Scenario descriptions

2.3 API introduction

Return parameters and descriptions (New in v1.1.0)

After an API request is made, the experiment data and details are returned. The following code shows an example:

import com.quicktracking.sdk.android.abtest.QTABResult
/**
 * The struct for A/B test returns.
 */
public class QTABResult<T> {
    public T value; // The return value.
    public String expid = ""; // The experiment ID.
    public String gid = ""; // The experiment group ID.
}

Parameter descriptions

fetchABTestFromCache

/**
 * Gets the experiment result from the cache.
 *
 * @param paramName The parameter name.
 * @param defaultValue The default value.
 * @param <T> The type of the default value.
 * @return The result.
 */
 
<T> QTABResult<T> fetchABTestFromCache(String paramName, T defaultValue);

Request parameters

Return result

Usage example

import com.quicktracking.sdk.android.abtest.QTABTest;

// Request a String parameter. 
QTABResult<String> result = QTABTest.shareInstance().fetchABTestFromCache(getTextValue(), "test");

// Request a Boolean parameter. 
QTABResult<Boolean> result = QTABTest.shareInstance().fetchABTestFromCache(getTextValue(), false);

// Request a Number parameter. 
QTABResult<Integer> result = QTABTest.shareInstance().fetchABTestFromCache(getTextValue(), 1);

// Request a JSONObject parameter.
try{
  QTABResult<JSONObject> result = QTABTest.shareInstance().fetchABTestFromCache(getTextValue(), null);
}catch (Exception e){
}

fetchABTestFromServer

 /**
   * Requests the experiment result from the network.
   *
   * @param <T>            The type of the default value.
   * @param paramName      The parameter name.
   * @param timeoutMillSeconds The timeout period.
   * @param defaultValue   The default value.
   * @param callback       The callback interface.
   */
   
void fetchABTestFromServer(String paramName, int timeoutMillSeconds, T defaultValue, OnABTestResultCallBack<T> callback);

Request parameters

Callback description:

import com.quicktracking.sdk.android.abtest.OnABTestResultCallBack;

public interface OnABTestResultCallBack<T> {
    /**
     * Request callback.
     *
     * @param result QTABResult<T> The type of the default value.
     */
    void onResult(QTABResult<T> result);
}

Return parameters:

Usage example

import com.quicktracking.sdk.android.abtest.OnABTestResultCallBack;
import com.quicktracking.sdk.android.abtest.QTABTest;

QTABTest.shareInstance().fetchABTestFromServer("", 10 * 1000, null, new OnABTestResultCallBack<JSONObject>() {
    @Override
    public void onResult(QTABResult<JSONObject> result) {
        refreshLogView(result.toString());
    }
});

fetchABTestFromCacheThenServer

/**
   * If a local cache exists, returns the cached data. Otherwise, requests the latest experiment data from the network. You can customize the timeout period.
   *
   * @param <T>          The type of the default value.
   * @param paramName    The parameter name.
   * @param timeout      The timeout period.
   * @param defaultValue The default value.
   * @param callback     The callback interface.
   */
void fetchABTestFromCacheThenServer(String paramName, int timeout, T defaultValue, OnABTestResultCallBack<T> callback);

Request parameters

Callback description:

import com.quicktracking.sdk.android.abtest.OnABTestResultCallBack;

public interface OnABTestResultCallBack<T> {
    /**
     * Request callback.
     *
     * @param result QTABResult<T> The type of the default value.
     */
    void onResult(QTABResult<T> result);
}

Return parameters:

Usage example

import com.quicktracking.sdk.android.abtest.OnABTestResultCallBack;
import com.quicktracking.sdk.android.abtest.QTABTest;

QTABTest.shareInstance().fetchABTestFromCacheThenServer("param_json", 10 * 1000, null, new OnABTestResultCallBack<JSONObject>() {
    @Override
    public void onResult(JSONObject result) {
    }
});

3. Debug experiments

After the experiment starts

When logging is enabled, the log prints the list of experiments that the device is assigned to.