Web SDK-Quick Tracking(Quick Tracking)-阿里云帮助中心

Integrate the Quick Tracking Web/H5 SDK to run programmed A/B test experiments on your website.

1. Import and initialize the SDK

The Quick Tracking A/B test SDK does not directly collect personal information. It relies on behavioral data from the Quick Tracking Analytics SDK. Ensure you have integrated and initialized the Quick Tracking Analytics Web SDK v2.4.0 or later. For more information, see Import & Initialize SDK.

1.1 SDK information

SDK name

Version

MD5 value

Quick Tracking Web A/B test SDK

Latest version: 1.0.2

Changelog:

1.0.2: Standardized the key names for A/B test data properties.

1.0.1: Added a method for retrieving A/B properties.

1.0.0: Added support for the programmed experiment feature.

qt_ab_h5.umd.js:

256e91fa9cdb48612576651a46f47b57

qt_ab_h5.cjs.js:

5992469d29486bf8e95c1991d75f9133

qt_ab_h5.iife.js:

c9a28f667edf29338c41fd8229acc19b

qt_ab_h5.amd.js:

c52caa2a5aade63cfa6faf66bd7a3610

2. Programmed experiment

2.1 Integrate and initialize the SDK

Initialize the Quick Tracking Analytics SDK synchronously, then initialize the Quick Tracking A/B test SDK with the A/B test request URL. Contact the support team to obtain this URL.

Synchronous import

<html>
  <head>
    <script src="Copy the SDK link from the 'management console - Data Collection' module of Quick Tracking" charset="UTF-8" id="beacon-aplus">
    </script>
    <script>
      aplus.initParams({
        appKey: "The unique identifier for the application you created in the 'management console - application list' module of Quick Tracking",
        trackDomain: "Copy the data collection endpoint from the 'management console - Data Collection' module of Quick Tracking",
        // Enable detailed logs for the Analytics SDK.
        DEBUG: true,
        // Set global properties.
        globalproperty: {
          n: 1,
          s: "s",
          arr: ["1", "2", "3"]
        },
      });
    </script>
    <script src="Copy the SDK link from the 'management console - Data Collection' module of Quick Tracking" charset="UTF-8" id="beacon-aplus-ab">
    </script>
    <script>
      aplus.use('qt_abtest', {
        // The request URL for the A/B test.
        // Format: {data_collection_endpoint}/abtest_results?appkey={your_app_key}
        url: `${trackDomain}/abtest_results?appkey=${appKey}`,
        // Specifies whether to encrypt cached data.
        need_encrypt_data: true,
        // Enable detailed logs for the A/B test SDK.
        enableLog: true,
        // The polling interval for new experiment results, in milliseconds. Default: 600,000 (10 minutes).
        update_interval_milliseconds: 60*10*1000 
      });
    </script>
  </head>
</html>

2.2 Get an experiment variable

After initialization, use the SDK API to retrieve experiment variable values. Three retrieval strategies are available:

fetchABTestFromCache: Reads from the local cache. If the value is not found, a default value is returned.
fetchABTestFromServer: Ignores the local cache and fetches data from the server.
fetchABTestFromCacheThenServer: Reads from the local cache first. If not found, it fetches data from the server.

Use cases

API name	Description
fetchABTestFromCache	Retrieves the variable value only from the local cache. Best for high-performance scenarios, but may not return the most up-to-date experiment results.
fetchABTestFromServer	Bypasses the local cache and fetches the experiment variable value directly from the server. Best for time-sliced experiments that require the latest data, but may introduce network latency.
fetchABTestFromCacheThenServer	Recommended for most use cases. Reads from the local cache first and falls back to the A/B test server if no cached value is found, balancing performance and timeliness.

2.3 Get A/B properties

API name	Description
onABTestResultChange	A callback function triggered when experiment data in the SDK's local cache is updated.

Example

// Method 1
aplus.use('qt_abtest', {
      url: "https://bare1-qlc.aplus.emas-poc.com/abtest_results?appkey=p0x252tg8klhfxqaq478ofni",
      need_encrypt_data: true,
      enableLog: true,
      onABTestResultChange:(res)=>{
        console.log('res1',res);
        /** Example of the returned data
        [
          {"gid": xxx, "expid": xxx,}, 
          {"gid": xxx, "expid": xxx,},
          ...
        ]
    **/
      },
      update_interval_milliseconds: 2000,
    })
// Method 2
aplus.qt_abtest.onABTestResultChange = (res)=>{
      console.log('res2',res);
      /** Example of the returned data
        [
          {"gid": xxx, "expid": xxx,}, 
          {"gid": xxx, "expid": xxx,},
          ...
        ]
    **/
 }

2.4 API reference

Return parameters

Each API request returns an object with the following fields:

result = 
{
    "expid": "114", // The experiment ID
    "gid": "201", // The group ID
    "value": "" // The returned value
}

Parameters

Parameter	Type	Default	Description	Remarks
value	String \| Boolean \| Integer \| JSONObject	undefined	The result value of the experiment parameter.	The type of the returned `value` must match the experiment's `value_type`. A mismatch is considered an anomaly. Ensure your business logic handles the `result` object correctly.
expid	String	""	The experiment ID.
gid	String	""	The group ID.

fetchABTestFromCache

const result = aplus.qt_abtest.fetchABTestFromCache({
  param_name: "your_parameter_name",
  value_type: "your_value_type",
  default_value: "your_default_value",
})

Request parameters

Parameter	Type	Default	Description	Remarks
param_name	String	None	The name of the experiment parameter.	Required. Must be a non-empty string.
value_type	String	None	The value type of the experiment.	Required. The value must be one of the following: "NUMBER", "STRING", "BOOLEAN", or "JSON".
default_value	String \| Number \| Boolean \| Object \| null \| undefined	None	The default result value for the experiment parameter.	Required. The type of this value must match the `value_type`. For example, if `value_type` is `NUMBER`, `default_value` must be a number. The `value` field in the returned `result` object will also be a number.

Important

Important: Ensure your business logic correctly handles the default values returned by the API.

Return value

Parameter	Type	Default	Description	Remarks
result	String \| Number \| Boolean \| Object \| undefined	undefined	The result value of the experiment parameter.	The type of the returned `result` must match the experiment's `value_type`. A mismatch is considered an anomaly. Ensure your business logic handles the `result` object correctly.

Example

const result = aplus.qt_abtest.fetchABTestFromCache({
  param_name: "color1",
  value_type: "STRING",
  default_value: "a_string_default_value",
})
// If a result is found in the local cache
console.log(result); //{expid: 122, gid: 218, value: 'the_cached_value'}
// If no result is found in the local cache
console.log(result); //{expid: '', gid: '', value: 'a_string_default_value'}

fetchABTestFromServer

aplus.qt_abtest.fetchABTestFromServer({
  param_name: "your_parameter_name",
  value_type: "your_value_type",
  default_value: "your_default_value",
  timeout_milliseconds: 3000, // Timeout for the A/B test server request in milliseconds. Default: 3000.
  callback: (result) => {
    // Handle the returned experiment result in your business logic.
    // TODO: Implement your experiment based on the result.
  },
});

Request parameters

Parameter	Type	Default	Description	Remarks
param_name	String	None	The name of the experiment parameter.	Required. Must be a non-empty string.
value_type	String	None	The value type of the experiment.	Required. The value must be one of the following: "NUMBER", "STRING", "BOOLEAN", or "JSON".
default_value	String \| Number \| Boolean \| Object \| null \| undefined	None	The default result value for the experiment parameter.	Required. The type of this value must match the `value_type`. For example, if `value_type` is `NUMBER`, `default_value` must be a number. The `value` field in the returned `result` object will also be a number.
timeout_milliseconds	Number \| undefined	3000	The request timeout, in milliseconds.	Optional.
callback	Function	None	The callback function for the A/B test result.	Required.

Important

Important: Ensure your business logic correctly handles the default values returned by the API.

Return value

Parameter	Type	Default	Description	Remarks
result	String \| Number \| Boolean \| Object \| undefined	undefined	The result value of the experiment parameter.	The type of the returned `result` must match the experiment's `value_type`. A mismatch is considered an anomaly. Ensure your business logic handles the `result` object correctly.

Example

aplus.qt_abtest.fetchABTestFromServer({
  param_name: "color1",
  value_type: "STRING",
  default_value: "a_string_default_value",
  callback: (result) => {
    // If an experiment result is found on the server
    console.log(result); //{expid: 122, gid: 218, value: 'the_server_value'}
    // If no experiment result is found
    console.log(result); //{expid: '', gid: '', value: 'a_string_default_value'}
  },
})

fetchABTestFromCacheThenServer

aplus.qt_abtest.fetchABTestFromCacheThenServer({
  param_name: "your_parameter_name",
  value_type: "your_value_type",
  default_value: "your_default_value",
  timeout_milliseconds: 3000, // Timeout for the A/B test server request in milliseconds. Default: 3000.
  callback: (result) => {
    // Handle the returned experiment result in your business logic.
    // TODO: Implement your experiment based on the result.
  },
});

Request parameters

Parameter	Type	Default	Description	Remarks
param_name	String	None	The name of the experiment parameter.	Required. Must be a non-empty string.
value_type	String	None	The value type of the experiment.	Required. The value must be one of the following: "NUMBER", "STRING", "BOOLEAN", or "JSON".
default_value	String \| Number \| Boolean \| Object \| null \| undefined	None	The default result value for the experiment parameter.	Required. The type of this value must match the `value_type`. For example, if `value_type` is `NUMBER`, `default_value` must be a number. The `value` field in the returned `result` object will also be a number.
timeout_milliseconds	Number \| undefined	3000	The request timeout, in milliseconds.	Optional.
callback	Function	None	The callback function for the A/B test result.	Required.

Important

Important: Ensure your business logic correctly handles the default values returned by the API.

Return value

Parameter	Type	Default	Description	Remarks
result	String \| Number \| Boolean \| Object \| undefined	undefined	The result value of the experiment parameter.	The type of the returned `result` must match the experiment's `value_type`. A mismatch is considered an anomaly. Ensure your business logic handles the `result` object correctly.

Example

aplus.qt_abtest.fetchABTestFromCacheThenServer({
  param_name: "your_parameter_name",
  value_type: "your_value_type",
  default_value: "your_default_value",
  timeout_milliseconds: 3000, // Timeout for the A/B test server request in milliseconds. Default: 3000.
  callback: (result) => {
    // If an experiment result is found in the local cache or on the server
    console.log(result); //{expid: 122, gid: 218, value: 'the_retrieved_value'}
    // If no experiment result is found
     console.log(result); //{expid: '', gid: '', value: 'a_string_default_value'}
  },
})