QuickTracking H5 SDK tracking API reference - Quick Tracking

Select the correct QuickTracking H5 SDK tracking API based on your tracking plan.

1. Understand the tracking plan

Before implementing tracking, define your tracking points and target data. QuickTracking provides a standardized template for this.

A tracking plan specifies the following components:

1. Event subject: Identifies "who" triggered the event — either a device ID or an account ID. Every event must include at least one.

device ID: Auto-generated for H5 pages. If the H5 page is embedded in a mini program, set the device ID to match the mini program's.
account ID: Identifies a logged-in user. Unlike device IDs, account IDs persist across devices.

2. User property: An attribute of an account ID, such as "Birthday" or "Membership Level".

3. Channel property: An advertising campaign attribute, such as ad channel, delivery method, or ad content.

4. Global property: An attribute that, once set, is included with every subsequent event.

5. Page view event: Reported on page load. The page code and event code are identical in the tracking plan.

6. Click, exposure, and custom events: Reported on user interaction.

2. Set the device ID and account ID

2.1 Set the device ID

A web device ID is either auto-generated by QuickTracking (default) or manually set by the developer.

Auto-generated (default): Regenerates when the browser changes or the user clears cookies and cache. If the browser and IP remain the same, the regenerated ID stays unchanged.
Manual: Assign a value to _dev_id. The ID must be 24–36 characters long.

// If user ID collection is asynchronous, block the SDK from sending data first.
aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['_hold', 'BLOCK']
});

// Set the _dev_id. 
aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['_dev_id', 'your_custom_device_id']
});

// Because user ID collection is asynchronous, you must set _hold to BLOCK before setting it to START.
// After you set _hold to START, the blocked logs are sent sequentially with the user information.
aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['_hold', 'START']
});

2.2 Set the account ID

Set the account ID when a user logs in and when a logged-in user enters an H5 page. The account ID does not persist across page re-entries, so set it both at login and on every H5 page entry.

// When a user logs in, get the user's account information.
// Or if the user is already logged in, get the account information from a cookie or local storage.
function demoLogin() {
    /************************* For synchronous scenarios ***********************************/
    aplus_queue.push({
        action: 'aplus.setMetaInfo',
        arguments: ['_user_id', 'user_account_id']
    });

    /****************** For asynchronous scenarios where logs depend on the account ID ***********************/
    // First, block data collection by setting _hold to BLOCK.
    aplus_queue.push({
        action: 'aplus.setMetaInfo',
        arguments: ['_hold', 'BLOCK']
    });
    ...
    function callback() {
        // In the callback, get the user's account ID from the asynchronous result.
        aplus_queue.push({
            action: 'aplus.setMetaInfo',
            arguments: ['_user_id', 'user_account_id']
        });
        // Then, allow data collection by setting _hold to START.
        aplus_queue.push({
            action: 'aplus.setMetaInfo',
            arguments: ['_hold', 'START']
        });
    };
    ...
};
// When a user logs out, reset the account ID.
function demoLogOff() {
    aplus_queue.push({
        action: 'aplus.setMetaInfo',
        arguments: ['_user_id', '']
    });
};

2.3 Get the device ID and account ID

Get the device ID

To get an auto-generated device ID:

The ID is stored in a cookie named cna under the current domain. Retrieve it by parsing document.cookie.

To get a manually set device ID:

If you set a custom device ID using setMetaInfo with _dev_id, retrieve it by calling aplus.getMetaInfo('_dev_id').

Get the account ID

If you set a custom account ID using setMetaInfo with _user_id, retrieve it by calling aplus.getMetaInfo('_user_id').

3. Set user properties

To report a user property, use the predefined event code $$_user_profile with event type OTHER.

After setting the account ID, report user properties:

// Example
aplus_queue.push({
    'action': 'aplus.record',
    'arguments': ['$$_user_profile', 'OTHER', {
        name: 'sss',      // User property 1
        gender: 'male',   // User property 2     
        class: '3',       // User property 3
    }]
});

You can customize lines 5, 6, and 7. Do not change the other lines.

4. Channel properties

By default, channel properties persist for the browser tab's SessionStorage lifecycle. Starting from v2.0.7, you can set a custom expiration time (in days) for UTM parameters. The value is stored in a cookie, subject to browser cookie policies.

Set the expiration time:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-utm-expire-days', '1']
});

Use cases for H5 channel parameters include:

4.1 Launch from an H5 link

The SDK automatically captures channel properties from the launch URL. Property keys must start with utm_. Example:

qaplus/product?utm_channel=gzh

Note: For third-party ad platforms that do not use the utm_ prefix, use the global property API to report channel properties. The keys must still begin with utm_.

4.2 Launch app via app store

Adding utm_ parameters to the H5 link alone cannot attribute app launches after installation. The system fuzzy-matches the H5 launch event and the app start event based on IP address and browser User-Agent.

When a user clicks the "Launch/Download App" button in the H5 page, report an app link event ($$_app_link). This event must include the appkey of the target app and the channel properties.

// Example
aplus_queue.push({
    action: 'aplus.recordAppLink',
    arguments: [{
        targetAppKey: 'appKey_of_the_target_app',  // Required. The appKey of the app to launch.
        custom1: 'custom1', // Optional. A custom parameter.
        ...
    }]
})

The QuickTracking App SDK automatically collects the first app start event after installation, which is the app install event ($$_app_install).
The QuickTracking system performs a fuzzy match between the app link event ($$_app_link) and the app install event ($$_app_install) based on their IP address and browser User-Agent. You can then analyze the channel properties of the "App Install (predefined)" event directly in your app analytics.

5. Global properties

The lifecycle of a global property starts when the API is first called and ends when the browser tab is closed, the browser is closed, or the URL changes in a multi-page application.

5.1 Append global properties (aplus.appendMetaInfo)

aplus.appendMetaInfo updates an existing global property or adds a new one if the key does not exist.

API:

aplus_queue.push({
    action: 'aplus.appendMetaInfo',  // Append global properties
    arguments: ['globalproperty', {
        xxx: xxx,
    }]
});

Example:

aplus_queue.push({
    action: 'aplus.appendMetaInfo', // Append global properties
    arguments: ['globalproperty', {
        a: 3,
        b: 4
    }]
});
// The current globalproperty is {a: 3, b: 4}

aplus_queue.push({
    action: 'aplus.appendMetaInfo', // Append global properties
    arguments: ['globalproperty', {
        b: 2,
        d: 4
    }]
});
// The current globalproperty is {a: 3, b: 2, d: 4}

Once set, a global property is included with every subsequent event until the browser tab closes, the browser closes, or the URL changes in a multi-page application.

5.2 Overwrite global properties (aplus.setMetaInfo)

aplus.setMetaInfo replaces all existing global properties with the new set.

Warning

Use this method only if it aligns with your business logic. A common use case is to clear all global properties. Use with caution.

Important: This method also overwrites all channel properties.

API:

aplus_queue.push({
    action: 'aplus.setMetaInfo',   // Overwrite global properties
    arguments: ['globalproperty', {
        xxx: xxx
    }]
});

Example:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['globalproperty', {
        a: 1,
        b: 2
    }]
});
// The current globalproperty is {a: 1, b: 2}

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['globalproperty', {
        c: 1,
        d: 2
    }]
});
// The current globalproperty is {c: 1, d: 2}. The properties {a: 1, b: 2} no longer exist.

5.3 Get global properties

Use getMetaInfo to retrieve all current global and channel properties.

aplus.getMetaInfo('globalproperty');

Note: You must call this method after the SDK has finished initializing.

6. Page view event API

1. Page view events support automatic or manual tracking. Automatic tracking is enabled by default.

2. Information to track for a page view event:

Event code: For a page view event, this is the same as the page code.
Event properties for the page view event: See your tracking plan for details.

6.1 pageConfig

Use the global pageConfig object to configure page codes:

<head>
  ...
  <script>

      ...SDK integration code

    // Set the page code and page title.
    // Set pageConfig. Effective for SDK v1.7.7 and later.
    // If pageConfig is not set,
    // the page code defaults to the current page URL without parameters,
    // and the page title defaults to document.title.
    aplus_queue.push({
      action: 'aplus.setMetaInfo',
      arguments: ['pageConfig', {
        hashMode: false, // Default is false for History mode. Set to true to enable Hash mode.
        // Effective only when hashMode=true. Default is false. If true, automatic PV in hash mode supports full URL equality checks.
        hashAutoPVSupportFullURL: false, 
        '/': {
          pageName: 'home_page_test',
          pageTitle: 'Home',
          skipMe: true // Ignores automatic reporting for this page view event. Default is undefined.
        },
        '/search': {    // Match based on location.pathname
          pageName: 'search_page_test',
          pageTitle: 'Search Page',
          regRule: /\/search/  // (Optional) Validate dynamic routes.
        },
        '#/hash_page': {  // Match based on location.hash
          pageName: 'hash_page_test',
          pageTitle: 'Hash Mode Page',
          regRule: a_regex_to_match_current_hash_route // (Optional) Validate dynamic routes with a regular expression.
        },
        '/demo.html': {
          pageName: 'demo_test',
          pageTitle: 'Demo Test Page'
        }
      }]
    });
  </script>
</head>

pageName
- The page code.
pageTitle
- The page title.
skipMe: Disables automatic tracking for the page.
- Set to true to disable or false to enable.
- This setting overrides the global aplus-disable-apv switch.
hashMode
- Specifies whether automatic page view URL detection is based on hash mode. The default is false.
hashAutoPVSupportFullURL
- In hash mode, specifies whether to send an automatic page view event when the URL, including its parameters, changes.
- The default is false. This setting is effective only when hashMode is true.
  - For example, if both hashMode and this property are true, navigating from www.example.com/#/a?p=111 to www.example.com/#/a?p=222 triggers an automatic page view event.
- Supported in v2.4.3 and later.

6.2 Automatic page view tracking

When the SDK finishes loading, it reports a page view event with:

Current client time
Page path
Page code (defaults to the page path; if pageConfig is set, it uses the mapped page_name)
Page title (defaults to the page title; if pageConfig is set, it uses the mapped page_title)
Time on page: The SDK does not collect this metric.

6.2.1 Enable or disable automatic page views

Automatic page view reporting is enabled by default. To disable it:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-disable-apv', true]
});

To disable automatic reporting for a single page, set skipMe to true in its pageConfig.

6.2.2 Custom properties for automatic page views

In automatic tracking mode, add custom properties to page view events via the extData object in pageConfig. The extData object or its fields can be a function.

Supported in v2.0.17 and later.

Usage example:

<head>
  ...
  <script>

        ...SDK integration code

    aplus_queue.push({
      action: 'aplus.setMetaInfo',
      arguments: ['pageConfig', {
        '/page1': {
          pageTitle: '',
          pageName: '',
          skipMe: true,
          extData: {
            customData1: 1,
            customData2: 1,
          },
        },
        '/page2': {
          extData: {
            customData1: 1,
            customData2: function () {
              return 1342;
            }
          }
        },
        '/page3': {
          extData: function () {
            return {
              customData1: 1,
              customData2: 1342
            }
          }
        },
      }]
    });
  </script>
</head>

6.3 Manual page view tracking

API

sendPV reports a manual page view event.

aplus_queue.push({
    action: 'aplus.sendPV',
    arguments: [pageEventConfig, userData]
});

Where:

pageEventConfig is the page event configuration. Set this to { is_auto: false }.
userData is an object for custom parameters for this page view event. It must be a flat JSON object (no nested objects). If you have no parameters to pass, use an empty object {}.

Example:

// A simple demo
aplus_queue.push({
    'action': 'aplus.sendPV',
    'arguments': [{
        is_auto: false
    }, {

        page_title: "Home", // Defaults to the value in pageConfig. This value overrides it. (Optional)
        page_name: "yourCurrentPageName", // Defaults to the value in pageConfig. This value overrides it. (Optional)

        // If you set the duration parameter (in milliseconds), QuickTracking uses it as the "Event Property - Duration (s)" in analysis.
        duration: 1111111,

        // Custom event properties
        x: 111,
        y: 222
    }]
});

This value overrides the page_title from pageConfig.

This value overrides the page_name from pageConfig.

7. Event tracking

For all events other than page views, use 'action': 'aplus.record'. Information to track:

Event code:

Event properties:

Page code (optional): The SDK defaults to collecting the page path. If the path is mapped in pageConfig with a page_name, that value is used by the SDK. If page_name is also set as an event property, the event property takes precedence. The priority is:

page_name in event properties > page_name in pageConfig > Page path

Page title (optional): The SDK defaults to collecting the page title. If the path is mapped in pageConfig with a page_title, that value is used by the SDK. If page_title is also set as an event property, the event property takes precedence. The priority is:

page_title in event properties > page_title in pageConfig > Page title

Event tracking can be automatic or manual. By default, automatic tracking for click and exposure events is disabled.

Note:

Native apps enforce strict data types, whereas H5 uses weak typing. When an H5 page is embedded in a native app, a type mismatch (such as null) can cause errors. Use appropriate data types (numbers, strings, or arrays of strings) when passing data from H5.

Event properties can be one of the following types: String, Number, Boolean, a date (as a string), or an array of strings.

7.1 Exposure events

EXP indicates an exposure event.

aplus_queue.push({
    'action': 'aplus.record',
    'arguments': ['event_code_from_tracking_plan', 'EXP', {
        x: '111',
        y: '222',
        z: 333,
        page_name: "demoPageName", // Optional. A custom page code for the current page.
    }]
});

7.2 Click events

CLK indicates a click event.

aplus_queue.push({
    'action': 'aplus.record',
    'arguments': ['event_code_from_tracking_plan', 'CLK', {
        x: '111',
        y: '222',
        z: 333,
        page_name: "demoPageName", // Optional. A custom page code for the current page.
    }]
});

7.3 Other custom events

OTHER indicates a custom event that is not a click or exposure event.

aplus_queue.push({
    'action': 'aplus.record',
    'arguments': ['event_code_from_tracking_plan', 'OTHER', {
        x: '111',
        y: '222',
        z: 333,
        page_name: "demoPageName", // Optional. A custom page code for the current page.
    }]
});

Data type reference:

Type	Value	System-recognized type	Limitations
number	12 or 12.0	<Number: Integer, Long, Float, Short, Double>	None
boolean	true or false	<Boolean>	None
string	"This is test Text"	<String>	Maximum length of 1024 bytes after UTF-8 encoding. The system discards fields that exceed this limit.
string[]	["ABC","123"]	<Set (String)>	An array of string elements (duplicates are not removed). The maximum number of elements is 100. Each element has a max length of 255 bytes after UTF-8 encoding.
date (as string)	"2025-11-11 11:11:11.111" "2025-11-11 11:11:11" "2025-11-11"	<Datetime>	The recommended format is `yyyy-MM-dd HH:mm:ss.SSS`, where `SSS` represents milliseconds. Other supported formats: yyyy-MM-dd HH:mm:ss.SSS yyyy-MM-dd HH:mm:ss yyyy-mm-dd (The time is set to 00:00:00)

7.4 Automatic exposure tracking

The SDK automatically detects element exposure. An exposure triggers when >50% of an element is visible in the viewport for >300 ms.

<body>
    <div id="root">
        <h1 class="title">demo</h1>
        <!-- To pass parameters, use data-* attributes with lowercase names. -->
        <button class="autoexp-component-css"
            data-pagename="custom_page_code_for_this_event"
            data-page_title="custom_page_title_for_this_event">Test Exposure</button>
        <List>
            <List.Item class="autoexp-list-item" data-name={"a"}>a</List.Item>
            <List.Item class="autoexp-list-item" data-name={"b"}>b</List.Item>
            <List.Item class="autoexp-list-item" data-name={"c"}>c</List.Item>
            <List.Item
                class='autotrack_exp_web'
                data-itemname={'Reading'}
                data-itemzoon={'abc'}
                data-itemid={'a_product_id'}
                data-promotioninformation={'abc'}
                data-pagename={'Home'}>Automatic Tracking - Auto Exposure</List.Item>

        </List>
    </div>
</body>

SDK configuration:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-auto-exp', [
        // Track exposure for the button element.
        {
            cssSelector: '.autoexp-component-css', // The class of the element to track. 
            logkey: 'auto-exp-id',   // The corresponding event code from your tracking plan.
            props: ['data-pagename', 'data-page_title'], // Custom attributes on the element to track.
        },
        // Track exposure for list elements.
        {
            cssSelector: '.autoexp-list-item',
            logkey: 'auto-exp-item', // The corresponding event code from your tracking plan.
            props: ['data-name'], // Automatic exposure tracking will include the item's name field.
        },
    ],
    ],
});

// A pre-callback function for automatic exposure tracking to support custom parameters, such as camelCase names (since data attributes only support lowercase).
// Supported in v1.9.25 and later.
aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-auto-exp-userfn', function (e) {
        if (e.className.indexOf('autotrack_exp_web') != -1) {
            var dataset = e.dataset;
            var obj = {};
            obj.itemID = dataset.itemid;
            obj.itemName = dataset.itemname;
            obj.itemZoon = dataset.itemzoon;
            obj.promotionInformation = dataset.promotioninformation;
            obj.pageName = dataset.pagename;
            return {
                userdata: obj
            };
        }
    }]
});

If the element scrolls within a container (a block with its own scrollbar), you must add the positionSelector configuration as shown below:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-auto-exp', [{
        positionSelector: '.content-wrap',  // The class of your scrollable container.
        cssSelector: '.autoclk-app-option', // The class of the element to track. 
        logkey: 'auto-exp-id',  // The corresponding event code from the tracking plan.
        props: ['data-name'], // Custom attributes on the element.
    },
    ],
    ],
});

In a single-page application (SPA), the SDK may re-report an exposure when a user navigates away and returns. To prevent this:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-exposure-event-can-repeat', false]
});

The default is true (repeated exposure events allowed).

Supported in v1.10.2 and later. In earlier versions, the SDK does not re-track an already-exposed element on page re-entry without a full reload.

7.5 Automatic click tracking

Supported from v1.7.0. The SDK supports automatic click event collection.

<body>
    <div id="root">
        <h1 class="title">Demo</h1>
        <!-- 1. First, identify the class of the HTML element to track. -->
        <!-- 2. To pass parameters, use data-* attributes with lowercase names. -->
        <button
            class='autoclk-component-css'
            data-aparam="1"
            data-pagename="custom_page_code_for_this_event"
            data-page_title="custom_page_title_for_this_event">
            Test Click
        </button>
        <li
            className='autotrack_clk_web'
            data-itemname='Reading'
            data-itemzoon='abc'
            data-itemid='a_product_id'
            data-promotioninformation='abc'
            data-pagename='Home'>Automatic Click</li>
    </div>
</body>

SDK configuration:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-auto-clk', [{
        cssSelector: '.autoclk-component-css', // The class of the element 
        logkey: 'auto-clk-id',  // The corresponding event code from the tracking plan
        props: ['data-aparam', 'data-pagename', 'data-page_title'], // Custom attributes on the element
    },
    ],
    ],
});

// A pre-callback function for automatic click tracking to support custom parameters, such as camelCase names (since data attributes only support lowercase).
// Supported in v1.9.25 and later.
aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-auto-clk-userfn', function (e) {
        if (e.className.indexOf('autotrack_clk_web') != -1) {
            var dataset = e.dataset;
            var obj = {};
            obj.itemID = dataset.itemid;
            obj.itemName = dataset.itemname;
            obj.itemZoon = dataset.itemzoon;
            obj.promotionInformation = dataset.promotioninformation;
            obj.pageName = dataset.pagename;
            return {
                userdata: obj
            };
        }
    }]
});

7.6 Automatic click capture

7.6.1 Enable or disable automatic click capture

The aplus-autotrack-enabled parameter controls the automatic click capture feature. It is true by default.

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-autotrack-enabled', true]
});

7.6.2 Configure elements for automatic capture

By default, the Web SDK only captures click events for a, button, textarea, and input elements. To capture clicks on other element types, configure them using aplus-autotrack-config.

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-autotrack-config', {
        collect_tags: {
            li: true, // Capture <li/> elements
            img: true,// Capture <img/> elements
            svg: true,// Capture <svg/> elements
            div: true,// Capture <div/> elements
            span: true,// Capture <span/> elements
            path: true,// Capture <path/> elements
            p: true // Capture <p/> elements
        },
        collect_input: true, // Captures the content of input fields. Default is false.
        element_capture_enable: true // Enables event capture mode for automatic click tracking. The default is bubbling mode (false).
    }]
});

7.6.3 Report properties for automatic click events

Similar to other automatic events, you can report properties using HTML data attributes.

<body>
    <div id="root">
        <!-- To pass parameters, use data-* attributes. -->
        <button data-aparam="1">Test Click</button>
    </div>
</body>

7.6.4 Disable automatic tracking for a single element

To disable event reporting for a specific element, add the aplus-autotrack-off="true" attribute to it.

<body>
    <div id="root">
        <!-- To pass parameters, use data-* attributes. -->
        <button data-aparam="1" aplus-autotrack-off="true">
            Components with aplus-autotrack-off are not tracked
        </button>
    </div>
</body>

7.6.5 Set a custom event code for an element

Use data-clk-logkey to set a custom event code.

<button data-clk-logkey="demoEventCode">Set a custom event code with data-clk-logkey</button>

8. Heatmaps

8.1 Enable or disable heatmaps

Heatmaps are disabled by default. To enable:

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-heatmap-enabled', true]
});

Or:

<meta name="aplus-heatmap-enabled" content="1">

8.2 Set heatmap sampling rate

The heatmap sampling rate supports values down to three decimal places (0.001).

aplus_queue.push({
    action: 'aplus.setMetaInfo',
    arguments: ['aplus-rate-ahot', 0.001] // Heatmap event sampling rate. Minimum value is 0.001.
});

Or:

<meta name="aplus-rate-ahot" content="0.001">

9. Viral sharing

Viral sharing leverages social connections to spread information and acquire new users.

Integrate the SDK's viral sharing features to use the share trend model in QuickTracking, measuring user acquisition through share metrics.

View top sharing users and share acquisition metrics across different levels.
Combine acquisition metrics to identify key opinion leaders. Track sharing paths and relationships.

9.1 Get source share parameters

window.aplus.getRefShareParams();

Version requirement

H5 SDK v2.2.0 and later.

Purpose

When a recipient opens a shared H5 page, this API retrieves the source share ID and source share URL.

Request parameters

None

Return parameters

Object

Parameter	Type	Default	Description	Notes
$$_ref_share_url	String	""	The source share URL, excluding the share ID.	None
$$_ref_share_id	String	""	The source share ID.	None

Usage example

Promise-based return value

// Promise-based return value
function onShare(options) {
    const {
        $$_ref_share_url,
        $$_ref_share_id
    } = window.aplus.getRefShareParams();
    const promise = window.aplus.requestShareParams({
        title: 'Share Campaign Page',
        path: 'https://www.taobao.com/productId?utm_test=test',
        campaign: 'This is a share campaign',
        shareId: $$_ref_share_id
    }).then(res => {
        const { $sid } = res;
        if ($sid) {
            window.aplus.record("$$_share", "CLK", {
                $$_share_title: "This is a share title",
                $$_share_id: $sid,
                $$_share_campaign_id: "This is a custom share campaign",
                $$_share_type: "User-defined share platform",
                $$_share_url: "This is a share URL"
            });
        } else {
            console.log("Failed to get share parameters."); // In DEBUG mode, the reason for the failure is printed to the console.
        }
    });
}

Callback-based return value

// Callback-based return value
function onShare() {
    const {
        $$_ref_share_url,
        $$_ref_share_id
    } = window.aplus.getRefShareParams();

    window.aplus.requestShareParams({
        title: 'Share Campaign Page',
        path: '/pages/share/shareCampaign?utm_test=test',
        campaign: 'This is a share campaign',
        shareId: $$_ref_share_id
    }, (res) => {
        const { $sid } = res;
        if ($sid) {
            window.aplus.record("$$_share", "CLK", {
                $$_share_title: "This is a share title",
                $$_share_id: $sid,
                $$_share_campaign_id: "This is a custom share campaign",
                $$_share_type: "User-defined share target platform",
                $$_share_url: "This is a share URL"
            });
        } else {
            console.log("Failed to get share parameters."); // In DEBUG mode, the reason for the failure is printed to the console.
        }
    });
}

9.2 Request share parameters

window.aplus.requestShareParams(Object params, Function callback);

Version

H5 SDK v2.2.0 and later.

Purpose

Requests a share ID required to build a share link.

Request parameters

Parameter

Type

Default

Description

Notes

params

Object

None

An object containing the share parameters.

Required parameters

url: The path of the page being shared. String. Defaults to location.href.

Optional parameters

campaign: Share campaign identifier. String. Defaults to undefined. Max length is 4,096 characters.

title: Share title. String. Defaults to undefined. Max length is 4,096 characters.

shareId: Source share ID. String. Defaults to undefined.

callback

Function

undefined

Callback function for environments that do not support Promises.

If you do not provide a callback, the API returns a promise that resolves with the result.

If a callback function is provided, the result is returned through the callback.

Return parameters

If the request does not include a callback, it returnsPromise.resolve(Object result);.

Parameter	Type	Default	Description	Notes
$sid	String	undefined	Share ID. A unique identifier for the sharing action.	None

If the request includes a callback, it returns an Object result.

Parameter	Type	Default	Description	Notes
$sid	String	undefined	Share ID. A unique identifier for the current sharing action.	None

Usage example

Promise-based return value

// Promise-based return value

function onShare(options) {
    const promise = window.aplus.requestShareParams({
        title: 'Share Campaign Page',
        path: 'https://www.taobao.com/productId?utm_test=test',
        campaign: 'This is a share campaign',
        shareId: "this_is_a_source_share_id"
    }).then(res => {
        const { $sid } = res;
        if ($sid) {
            window.aplus.record("$$_share", "CLK", {
                $$_share_title: "This is a share title",
                $$_share_id: $sid,
                $$_share_campaign_id: "This is a custom share campaign",
                $$_share_type: "User-defined share target platform",
                $$_share_url: "This is a share URL"
            });
        } else {
            console.log("Failed to get share parameters."); // In DEBUG mode, the reason for the failure is printed to the console.
        }
    });
}

Callback-based return value

function onShare() {
    window.aplus.requestShareParams({
        title: 'Share Campaign Page',
        path: '/pages/share/shareCampaign?utm_test=test',
        campaign: 'This is a share campaign',
        shareId: "this_is_a_source_share_id"
    }, (res) => {
        const { $sid } = res;
        if ($sid) {
            window.aplus.record("$$_share", "CLK", {
                $$_share_title: "This is a share title",
                $$_share_id: $sid,
                $$_share_campaign_id: "This is a custom share campaign",
                $$_share_type: "User-defined share target platform",
                $$_share_url: "This is a share URL"
            });
        } else {
            console.log("Failed to get share parameters."); // In DEBUG mode, the reason for the failure is printed to the console.
        }
    });
}

9.3 Report a share event

Report a share event using the predefined event code $$_share with event type CLK.

Example:

window.aplus.record("$$_share", "CLK", {
    $$_share_title: "This is a share title",
    $$_share_id: "the_share_id_from_the_request_api",
    $$_share_campaign_id: "This is a custom share campaign",
    $$_share_type: "User-defined share target platform",
    $$_share_url: "This is a share URL"
});

Note: The destination URL must include the $sid parameter with the share ID as its value. For example: https://example.aliyun.com/path/to/content?$sid=123456

Example of launching another application from an H5 link:

const {
    $$_ref_share_url,
    $$_ref_share_id
} = window.aplus.getRefShareParams();

window.aplus.requestShareParams({
    title: 'Share Campaign Page',
    path: '/pages/share/shareCampaign?utm_test=test',
    campaign: 'This is a share campaign',
    shareId: $$_ref_share_id
}, (res) => {
    const { $sid } = res;
    if ($sid) {
        window.aplus.record("$$_share", "CLK", {
            $$_share_title: "This is a share title",
            $$_share_id: $sid,
            $$_share_campaign_id: "This is a custom share campaign",
            $$_share_type: "User-defined share target platform",
            $$_share_url: "This is a share URL"
        });

        setTimeout(() => {
            var urlScheme = "https://example.aliyun.com/path/to/content?utm_source=utm_test&$sid=" + $sid;
            window.location.href = urlScheme;
        }, 1000)
    } else {
        console.log("Failed to get share parameters."); // In DEBUG mode, the reason for the failure is printed to the console.
    }
});