Android SDK

Supported platforms

The Android SDK supports following platforms:

• Android

Requirements

• Install or update Android Studio to the latest version.
• Make sure that your project meets the following requirements:
  1. Targets API level 16(Jelly Bean) or higher
  2. Use Android 4.1 or higher
  3. Use Jetpack AndroidX and make sure it meets the following version requirements:
     • com.android.tools.build:gradle v3.2.1 or later
     • compileSdkVersion 27 or later
• Set up a physical device or use an emulator to run your app.

Getting Started

The following will outline how to get up and running with ABetterChoice for Android Phone/Pad.

To work with the SDK, you will need a ABetterChoice project.Create a Project.

If you don't yet have a project, you can sign up for a free one here or ask us for help. You could skip this for now.

Installation

1. In Android studio，change to the "Project" view so you can see the root directory. In the root-level (project-level) Gradle file（<project>/build.gradle）, make the following config changes:

buildscript {
  repositories {
    // Ensure that the following two repositories are included
    google()  // Google's Maven repository
    jcenter()  // Central repository
  }
  dependencies {
    // ...
  }
}

allprojects {
  // ...
  repositories {
    // Ensure that the following two repositories are included
    google()  // Google's Maven repository
    jcenter()  // Central repository
  }
}

2. In the module (app-level) build.gradle file(<project/<app-module>/build.gradle>), add the Tab SDK which you will use within your code:

.......
buildscript {
  repositories {
    maven { url 'https://mirrors.tencent.com/repository/maven/tencent_public' }
    maven { url 'https://mirrors.tencent.com/repository/maven/abetterchoice_android_sdk'}
  }
  dependencies {
    implementation(group: 'com.tencent.abc.exp.sdk', name: 'abcexpsdk', version: 'x.x.x')
  }
}

allprojects {
  ...
  repositories {
    maven { url 'https://mirrors.tencent.com/repository/maven/tencent_public' }
    maven { url 'https://mirrors.tencent.com/repository/maven/abetterchoice_android_sdk'}
  }
}

3. Obfuscated configuration

// agreement document
-keep class com.abc.sea.sdk.pbdata.** {*;}

// storage components
-keep class com.tencent.mmkv.** { *; }
-keep class com.getkeepsafe.relinker.** { *; }

SDK Integration

You want to initialize the SDK after installing. One or more project ID is required to provide in initialization. We also support providing multiple project ID(s).

1. Add network and storage permissions in <project/<app-module>/src/main/AndroidManifest.xml>

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

2. Initialize SDK within the OnCreate() function of the corresponding Application.java file.

........
AbcExpInitTask.init(this);  // Initialize the context
AbcExpSDKOptions abcOptions = new AbcExpSDKOptions.Builder() // Set the functional parameters
  .projectId(PROJECT_ID)    // Required, set the business platform assigned by the platform
  .unitId(unitID)    // Required, the unique identifier of the user
  .secretKey(SECRET_KEY) // Optional, used for business authentication
  .requestTimeout(DEFAULT_REQUEST_TIMEOUT) // Optional, defaults to 15s if not set
  .autoReport(false) // Optional, defaults to false. When set to true, calling the interface to obtain data will also automatically report internally
  .autoPoll(true) // Optional, defaults to true. When set to false, data will not be updated internally in the SDK
  .initiativeUpdate(true) // Optional, defaults to true. When set to false, the current process obtains data directly from stored data rather than pulling data through the network
  .attributes(generateAttributes()) // Optional, used for tag experiments. For more information on tag usage, refer to: https://iwiki.woa.com/pages/viewpage.action?pageId=491725203
  .build();

AbcExpSDK abcExpSDK = AbcExpSDKFactory.singleton().create(abcOptions);  // Instantiate the SDK
......

3. Get the SDK Object and run the SDK

......
AbcExpSDK mAbcExpSDK = AbcExpSDKFactory.singleton().get(PROJECT_ID); // Required, get the SDK instance by the business ID configured during initialization
IAbcExperiment mAbcExperiment = mAbcExpSDK.getAbcExperiment();    // Required, get the experiment interface object
mAbcExpSDK.start(mAbcExpUseListener); // Required, start using the SDK. The SDK will pull the experiment data information under the current project ID and perform relevant pre-state initialization processing.
......
// Then call different interfaces based on different functional interface objects, which can be seen from the interfaces provided by the ITabExperiment interface class.

4. Calling functional interfaces

*-————————————————————————Get experiment information————————————————————————————————*/
// Get experiment information interface, other information acquisition interfaces can be viewed in the ITabExpData interface file
AbcExpInfo expInfo = mAbcExperiment.getExperiment("test_exp_name_layer");
if (null == expInfo) {
    // Indicates that the default version is hit or the data is abnormal or the experiment is offline
    // Execute the default version
    handleView("Default version");
    return;
}
// Get the hit experiment parameters
String paramVlue = expInfo.getStringValue("paramKey", "defVal");
// Execute different business logic based on the hit experiment configuration parameter value
switch(paramVlue) {
    case "Experimental group version configuration parameter value":
        // Execute experimental group related logic
        handleView("Experimental group");
        break;
    case "Control group version configuration parameter value"：
        // Execute control group related logic
        handleView("Control group");
        break;
    case "Other version configuration parameter value":
        // Execute other version name logic
        handleView("Other version");
        break;
    default:
        // Non-enumerated other version parameter value logic
        handleView("Non-enumerated version name logic")
        break;
}
// The type of experiment configuration parameter values obtained is not only strings, but also basic types such as integers, booleans, floats, and doubles, and there are also JSONObject object types, respectively:
String paramIntValue = expInfo.getIntValue("paramKey", 0);   // Integer
String paramBooleanValue = expInfo.getBooleanValue("paramKey", true); // Boolean
String paramFloatValue = expInfo.getFloatValue("paramKey", 0.1f);  // Float
String paramDoubleValue = expInfo.getDoubleValue("paramKey", 0.1111d); // Double
String paramJSONObjectValue = expInfo.getJSONObjectValue("paramKey", new JOSNObject()); // JSONObject object type

/*-————————————————————————Account and environment switching————————————————————————————————*/
// Switch accounts, "otherUnitID" represents other accounts
mAbcExpSDK.switchUnitId("otherUnitID", mAbcExpUseListener);

/*-———————————————————-------—————Force refresh——————————————————————--——————————*/
// Will force to initiate data update to the background
mAbcExperiment.refreshExperiment(mAbcExpUseListener);


/*-———————————————————-------—————Experiment report exposure———————————————————--——————————*/
// When autoReport configuration is not set, manual exposure can be performed in suitable scenarios
final boolean reportResult = mAbcExperiment.LogExperimentExposure(expInfo);

Getting experiments and logging Exposures

To get experiment traffic splitting configuration information including which group that a unit is assigned to by SDK. This requires users to create an experiment on the web UI first. The response contains detailed information of the group assigned to, including group parameters, which can be fetched by strong type API.

Terms	Meaning
project_id	The abetterchoice business platform assigned by the platform.
unit_id	A unitID can be a userID, a sessionID or a machineID. the SDK assigns a unitID to the same group consistantly.
Experiment	An AB test.
Group	There are two or more groups in an experiment, including one control and one or more treatments.

1. New Experiment creation

If you haven't done so, please go to the console and create a new experiment following our doc on how to create an experiment.

2. Fetching experiment assignments

Suppose in step 1 under the project project_id we already created a experiment whose layer name is abc_layer_name, under this layer there is a parameter whose name is should_show_banner and type is Boolean. Note that if you use our basic version the layer name is same with experiment name by default, but if you create new experiments under the same layer you need to find the layer name under the experiment page.

Right now we provide three ways of fetching the traffic assignement given a particular unit id. All the these APIs requires you to get the experiment interface object.

IAbcExperiment mAbcExperiment = mAbcExpSDK.getAbcExperiment();

a. Fetch experiment by layer key

The first way is getting the experiment assignment by the layer key, and fetching the parameters under the layer via the strong type APIs. This is convenient when you have more than one parameters under the layer/experiment, and this same API will automatically give you the correct result when there are multiple experiments under the same layer, since the unit will and can only fall into one of them. One more benefit of doing this is you can iterate the experiments quickly, by deallocating the old experiment and creating new ones under the same layer without modifying the code.

AbcExpInfo expInfo = mAbcExperiment.getExperiment("abc_layer_name");
String paramBooleanValue = expInfo.getBooleanValue("should_show_banner", true); // Boolean

b. Fetch experiment by parameter key

AbcExpInfo expInfo = mAbcExperiment.getExperiment("abc_layer_name");
String paramVlue = expInfo.getStringValue("paramKey", "defVal");

3. Exposure Data Logging

When fetching the experiment assignments above, you can choose to disable exposure logging to prevent exposure dilution, you can log the exposure manually later at the right place:

final boolean reportResult = mAbcExperiment.LogExperimentExposure(expInfo);

4. Account switching

Switch accounts, "otherUnitID" represents other accounts

mAbcExpSDK.switchUnitId("otherUnitID", mAbcExpUseListener);

5. Force Data refresh

Will force to initiate data update to the background

mAbcExperiment.refreshExperiment(mAbcExpUseListener);

Example

1. initialize the SDK

........
AbcExpInitTask.init(this);  // Initialize the context
AbcExpSDKOptions abcOptions = new AbcExpSDKOptions.Builder()
            .projectId("6666")
            .unitId("unitID")
            .secretKey("0c9ebb2ded806d7ffda75cd0b95eb70c") // Optional, used for business authentication
            .autoReport(true)
            .initiativeUpdate(true)
            .build();

AbcExpSDK abcExpSDK = AbcExpSDKFactory.singleton().create(abcOptions);
......

2. use the SDK

......
AbcExpSDK mAbcExpSDK = AbcExpSDKFactory.singleton().get("6666");
mAbcExpSDK.start(mExpRefreshListener); //start using the SDK. The SDK will pull the experiment data information under the current project ID and perform relevant pre-state initialization processing.
IAbcExperiment mAbcExperiment = mAbcExpSDK.getAbcExperiment();
AbcExpInfo expInfo = mAbcExperiment.getExperiment("test_exp_name_layer");
String paramVlue = expInfo.getStringValue("paramKey", "defVal");
final boolean reportResult = mAbcExperiment.LogExperimentExposure(expInfo);
......