Updated on 2025-09-07 GMT+08:00

LTS Web SDK

If you need to collect and analyze user information on websites, such as browser, browsing behavior, device, device exception, and network usage records, you can use this SDK to report logs to LTS.

To use this SDK, enable the anonymous write function of log streams. After this function is enabled, the reported logs are not authenticated and may generate dirty data. For details, see Managing Log Streams.

The Web SDK supports cross-cloud and local log reporting for whitelisted users in CN North-Beijing4, CN East-Shanghai1, and CN South-Guangzhou. To use it, create a service ticket.

Transport Protocol

HTTPS

Prerequisites

  • You have obtained the name of the region where LTS is deployed.
  • You have obtained a project ID of your Huawei Cloud account. For details, see API Credentials.
  • You have obtained the IDs of the target log group and log stream in LTS.

Version Updates

Table 1 Version updates

Version

Description

1.0.24

Added support for regions CN East-Shanghai1 and CN South-Guangzhou.

1.0.21

  • Deprecated the config method. Use the new SDK to create an instance.
  • Removed the dependency on third-party packages and Chinese characters in the code.

1.0.19

Changed the time threshold range from 1–60 to 1–1800, and changed the default value from 30 to 3.

1.0.18

  • Adjusted log levels.
  • Supported labels nesting.

1.0.15

Added support for multiple instances.

Instructions

To ensure that web logs can be reported, add the reporting address to the domain name list of the web developer platform. For details about the reporting address, see Table 2.

Installing the SDK Using NPM

  1. Run the npm i lts-web-sdk command in the root directory of the project to install the SDK. You can download the latest SDK from the open-source repository.
  2. Example code:
    const LTS_WEB_SDK = require('lts-web-sdk').default;
    // import LTS_WEB_SDK from 'lts-web-sdk';
    // Initialization
    const weblog = new LTS_WEB_SDK({
       // Region for log reporting
       region: string,
       // Project ID
       projectId: string,
       // Log reporting address
       url: string,  
       // LTS log group ID
       groupId: string,
       // LTS log stream ID
       streamId: string,
       // Debug log level
       debug: string,
       // Threshold for the number of reported log records
       cacheThreshold: number,
       // Threshold for the interval between log reports
       timeInterval: number,
    });
    // Immediately report a single record, with labels
    weblog.reportImmediately({ 'name': 'xiaoming', 'age': 18 }, { 'key': 'value' });
    // Immediately report a single record, without labels
    weblog.reportImmediately([{   key: 'value',   number: 1,   array: [],   json: {     json: 'json'   } }, { 'key': 'value' }]);
    // Cache and report multiple records, with labels
    weblog.report([{ 'name': 'xiaohong', 'age': 18 }, { 'name': 'xiaobai', 'age': 20 }], { 'key': 'value' });
    // Cache and report multiple records, without labels
    weblog.report([{ 'name': 'xiaohong', 'age': 18 }, {   key: 'value',   number: 1,   array: [],   json: {     json: 'json'   } }]);
    // Cache and report multiple records, with multiple labels (max. 50)
    weblog.report([{ 'name': 'xiaohong', 'name': 'xiaolan' }], {'version': '1.0.0', 'render': 'web', 'link': '/', from: 'web'});

Installing the SDK Through CDN Synchronization

  1. How to install:

    In your HTML file, reference the SDK as follows:

    <script src="https://res.hc-cdn.com/web-sdk-cdn/Version number/websdk.min.js"></script>

  2. Example code:
    // Import the SDK on the page.
    <script src="https://res.hc-cdn.com/web-sdk-cdn/1.0.15/websdk.min.js"></script>
    // Initialization
    const weblog = new LTS_WEB_SDK({
       // Region for log reporting
       region: string,
       // Project ID
       projectId: string,
       // Log reporting address
       url: string,  
       // LTS log group ID
       groupId: string,
       // LTS log stream ID
       streamId: string,
       //Debugging switch. If enabled, you can view the debug logs.
       debug: boolean,
       // Threshold for the number of reported log records
       cacheThreshold: number,
       // Threshold for the interval between log reports
       timeInterval: number,
    });
    // Immediately report a single record, with labels
    weblog.reportImmediately({ 'name': 'xiaoming', 'age': 18 }, { 'key': 'value' });
    // Immediately report a single record, without labels
    weblog.reportImmediately([{   key: 'value',   number: 1,   array: [],   json: {     json: 'json'   } }, { 'key': 'value' }]);
    // Cache and report multiple records, with labels
    weblog.report([{ 'name': 'xiaohong', 'age': 18 }, { 'name': 'xiaobai', 'age': 20 }], { 'key': 'value' });
    // Cache and report multiple records, without labels
    weblog.report([{ 'name': 'xiaohong', 'age': 18 }, {   key: 'value',   number: 1,   array: [],   json: {     json: 'json'   } }]);
    // Cache and report multiple records, with multiple labels (max. 50)
    weblog.report([{ 'name': 'xiaohong', 'name': 'xiaolan' }], {'version': '1.0.0', 'render': 'web', 'link': '/', from: 'web'});

Parameters

  • See the following table.
    Table 2 Parameters

    Field

    Type

    Mandatory

    Default Value

    Description

    region

    String

    Yes

    -

    Region where LTS is located.

    projectId

    String

    Yes

    -

    Project ID of the account. The value contains a maximum of 128 characters.

    groupId

    String

    Yes

    -

    Log group ID. The value contains a maximum of 128 characters.

    streamId

    String

    Yes

    -

    Log stream ID. The value contains a maximum of 128 characters.

    url

    String

    No

    -

    Public network address domain name used to report logs. The port number can be specified, for example, https://lts-access.cn-north-4.myhuaweicloud.com:443. If url is not set, a link is automatically generated based on the region. The format is as follows: https://lts-access.{region}.myhuaweicloud.com

    • When the SDK is used to report logs across clouds or locally, port 443 is used.
    • When Huawei Cloud hosts report logs via the Huawei Cloud intranet, port 8102 is used.

    debug

    String

    No

    OFF

    • Output level of the console debugging information. The options are OFF, ERROR, WARN, INFO, and DEBUG.
    • If an invalid value is entered, this parameter defaults to OFF. The highest level is DEBUG, and the level decreases in descending order.
    • If this parameter is set to true, DEBUG logs are enabled. If this parameter is set to false, DEBUG logs are disabled.

    cacheThreshold

    int

    No

    30

    By default, the cache threshold is 30 records. When the number of cached records reaches the threshold (range: 30 to 1,000), cached records are reported.

    timeInterval

    number

    No

    3

    By default, records are reported every 3 seconds. When the threshold interval (range: 1 to 1,800) is reached, cached records are reported.

  • Parameters of the Report method for reporting logs
    Table 3 Report parameters

    Field

    Type

    Mandatory

    Default Value

    Description

    content

    Object | Array<Object>

    Yes

    -

    Object or object array to be reported. The limits are as follows: Each object can contain a maximum of 300 key-value pairs. The maximum length of the JSON string is 1024 × 30 characters. Excess characters will be truncated.

    Each object in the array can contain a maximum of 300 key-value pairs. The maximum length of the JSON string is 1024 × 30 bytes. Excess characters will be truncated.

    The log field name cannot contain double underscores (__).

    labels

    Object

    No

    Null

    Log labels. The outermost key-value pair can contain a maximum of 50 key-value pairs. The outermost key can contain a maximum of 64 characters including letters, digits, and underscores (_), and must start with a letter. The maximum length of the converted JSON string is 1024 × 30 characters. If the length exceeds the limit, the record will not be reported.

    The log field name cannot contain double underscores (__).

  • Parameters of the reportImmediately method for reporting logs immediately
    Table 4 reportImmediately parameters

    Field

    Type

    Mandatory

    Default Value

    Description

    content

    Object | Array<Object>

    No

    -

    Object or object array to be reported immediately. The limits are as follows: Each object can contain a maximum of 300 key-value pairs. The maximum length of the JSON string is 1024 × 30 characters. Excess characters will be truncated.

    Each object in the array can contain a maximum of 300 key-value pairs. The maximum length of the JSON string is 1024 × 30 bytes. Excess characters will be truncated. If this parameter is left empty, cached logs will be reported immediately.

    The log field name cannot contain double underscores (__).

    labels

    Object

    No

    Null

    Log labels. The outermost key-value pair can contain a maximum of 50 key-value pairs. The outermost key can contain a maximum of 64 characters including letters, digits, and underscores (_), and must start with a letter. The maximum length of the converted JSON string is 1024 × 30 characters. If the length exceeds the limit, the record will not be reported.

    The log field name cannot contain double underscores (__).

Obtaining Parameters

  • Read the region table.
    Table 5 Regions

    Name

    Region

    CN North-Beijing4

    cn-north-4

    CN East-Shanghai1

    cn-east-3

    CN South-Guangzhou

    cn-south-1

  • To obtain a log group's ID, choose Log Management in the navigation pane of the LTS console and hover over the target log group's name.
  • To obtain a log stream's ID, click next to the corresponding log group and hover over the target log stream's name.