1. SDK Basic Information

SolarEngine (SE) is an all-in-one mobile app growth analytics and data intelligence platform. It supports data management across global channels, assisting developers to monitor every stage of business development. With our attribution tracking and user-granular ROI analysis, you'll be able to measure the true value every channel creates and optimize future growth strategies. SE also offers various analysis models and A/B testing feature to help fully visualize the user journey, identify potential pain points, implement targeted product enhancements and ultimately drive large-scale app growth.

Note: Frontend pages integrated with the Web SDK must use the HTTPS protocol; otherwise, Web SDK functions will be unavailable.

Privacy Policy:  https://www.solar-engine.com/privacyPolicyEN.html

2. Before you start

Step 1: Get User Code

Access Path: Account Management - Account Profile - Secret - User Code

Step 2: Get AppKey

      Access Path: Asset Management - App Management - AppKey

Step 3: Obtain SDK

Download China Mainland version SDK (UMD and ES packages provided) :

https://sdk.solar-engine.com/Web/SolarEngine-Web-CN-SDK-1.3.2.zip    

Download Non-China-Mainland version SDK (UMD and ES packages provided) :

https://sdk.solar-engine.com/Web/SolarEngine-Web-Inter-SDK-1.3.2.zip

3. Initialize the SDK

3.1. SDK initialization

     It is recommended to import and initialize the SDK before any other methods to ensure accurate data initialization. Before initializing the SDK, you must perform pre-initialization by calling the prevInit method and passing in your appKey. The SDK is provided in both UMD and ES formats. Commonly used loading methods are listed below:

Note:

     The SDK should be imported only once per project. After importing the SDK, it is recommended to mount it globally (e.g., on window) for use elsewhere.

    For development environments using ES Modules, import the ES format file. Otherwise, import the UMD format file.

import SESDK from './web-cn-sesdk-umd.js';

// If your build environment enforces ES Modules, please import the ES format file.
// import SESDK from './web-cn-sesdk-es.js'

// Some platforms only support CommonJS imports, in which case please use require.
// const SESDK = require('./web-cn-sesdk-umd.js')

// Pre-initialization
SESDK.prevInit(appKey);
// Initialization
SESDK.init(initParams);
// Mount to global (e.g., window) for use elsewhere
window.SESDK = SESDK;

<script src="./web-cn-sesdk-umd.js"></script>
// Pre-initialization
window.SESDK.prevInit(appKey);
// Initialization
window.SESDK.init(initParams);

initParams parameter description:

Config parameter description:

Code Example:

SESDK.prevInit('666666');
SESDK.init({
  appKey: '666666',
  userId: '888888',
  config: {
    logEnabled: true,
  },
});

  Since the SDK initialization logic runs asynchronously, if your business logic needs to be executed after SDK initialization is complete, you may call the ready method.

SESDK.ready(callback);

   During SDK initialization, if you need to load SDK plugins, you may call the use method.

SESDK.use(sdkPlugin);

   To obtain the distinct ID, you may call the getDistinct method.

SESDK.getDistinct().then(res => {
    // res.distinct_id
    // res.distinct_id_type
})

Note:

   If the page integrating the Web SDK needs to be embedded into an Android app, the Android app’s WebView must support Storage.

webView.getSettings().setDomStorageEnabled(true);

3.2. Visitor ID

      Visitor ID refers to the user's unique identifier (_visitor_id) after install and before login.

      We provide an interface for developers to customize the visitor ID. If you have your own visitor management system and need to replace SolarEngine's visitor ID, you must set it before SDK initialization.

      Only the last visitor ID passed in will be used for data reporting. Multiple calls should be avoided to prevent abnormal situations where multiple visitor IDs are reported consecutively.

Set visitor ID

       Call setVisitorID to set the visitor ID:

SESDK.setVisitorId('vid8709901241')

Note:

• This call only passes the visitor ID to SDK and does not report user setting events.
• The length of the visitor ID set by the developer cannot exceed 128 characters, otherwise the setting will fail.
• Once set by the developer, it will be stored in local storage.

Obtain visitor ID

   Call getVisitorId to get the current visitor ID:

SESDK.getVisitorId()

3.3. Account ID

       Account ID refers to the unique identifier for users who finished login within the app. Prior to login, the visitor ID will be used as the user identifier.

      Once the account ID is set, it will be retained permanently until the logout method is called to clear the account ID. The logout method should only be called when users actually log out, but no need to be called when the app is closed or running in the background.

      Only the last passed account ID will be used for data reporting. Multiple calls should be avoided to prevent abnormal situations where multiple abnormal account IDs are reported consecutively.

Set Account ID

      Call login to set the user's account ID:

SESDK.login('aid25491084');

Note:

• This call only passes the account ID to SDK and does not report user login events.
• The account ID set by the developer cannot exceed 128 characters, otherwise the setting will fail.
• Once set by the developer, it will be stored in local storage.

Obtain account ID

       Call getAccountId to get the user's account ID:

SESDK.getAccountId();

Clear account ID

       Call logout to clear the account ID:

SESDK.logout();

Note:

       This call only notifies the SDK to clear the account ID and will not report the user logout event.

3.4. Public event properties

      Public event properties are included in every event, such as the user's source channel and the advertising ID associated with conversions.

      You can call setSuperProperties function to set public event properties. We recommend you setting the public event properties before sending any events.

      The format of public event properties are the same as custom properties --> 4.4 Custom Properties

SESDK.setSuperProperties({
   key: value
});

       If you need to delete a public event property, you can call unsetSuperProperty to clear one of them.

SESDK.unsetSuperProperty(key);

       If you want to clear all public event properties, you can call clearSuperProperties .

SESDK.clearSuperProperties();

Note:

1. If you call setSuperProperties to upload public event properties that have been set previously, the new values will overwrite the existing ones.
2. If a property key in a normal event is the same as a public event property key, the normal event property will override the public event property.
3. Once set by the developer, these properties will be stored in local storage.

3.5. Preset event properties

   The SolarEngine SDK supports developers to set custom properties for the two preset events: install, and app open.

SESDK.setPresetEvent(eventType, properties);

Note:

• Preset event properties should be set before SDK initialization. In this way, the properties will apply to all subsequent preset events reported by the SDK. If set later, the preset events generated before setting will not include these custom properties.
• Custom preset event properties are not cached. Only the last setting will take effect if multiple settings are made for the same preset event.
• If the enumeration for eventType is set to all, it will overwrite the custom properties set in webInstall and webStart enumerations. If set multiple times, only the last setting takes effect.
• Custom properties set for preset events can be cleared by calling the corresponding enumeration, as shown below:

SESDK.setPresetEvent('webInstall', null)  This method can be used to clear webInstall custom properties, while webStart custom properties can be cleared by changing to the corresponding enumeration value.

• Additionally, SolarEngine SDK supports globally clearing custom properties for all preset events, as shown below:

SESDK.setPresetEvent('all', null)  This method clears the custom properties for all preset events, including those set via the webInstall and webStart enumerations.

Code Example:

SESDK.setPresetEvent('webInstall', {
  k1: 'v1',
  k2: 'v2'
});

3.6. Set other properties

Set channel name

       Call setChannel method to set the channel name "_channel".

SESDK.setChannel('channel');      

Set referrer page title

       Call setReferrerTitle method to set the referrer page title information "_referrer_title".

SESDK.setReferrerTitle('title');      

4. Event Reporting

  After SDK is initialized, you can call the following methods to report other event data, which can be categorized into the following four types:

1. Preset Events: These events are triggered and reported automatically by the SDK according to preset rules. They have specific _event_name such as webInstall, webStart.

2. Predefined Events: These events have predefined definitions and event names in the system. They require developers to report data when those events are triggered, such as in-app ad impression, in-app purchase, etc.

3. Custom Events: These events can be custom defined by developers according to their own analytical needs.

4. Duration Events: These events track the duration of a specific event.

Note:

  The event name supports uppercase and lowercase English characters, numbers, and underscores. The length cannot exceed 40 characters.

4.1. Preset events

1) Install

       This event will be automatically reported when users first open the web page. (If a use clears the browser cache and opens again, it will be counted as a new install.)

       The _event_name is _webInstall.

2) Start

       This event will be automatically reported every time the browser is opened.

       The _event_name is _webStart.

4.2. Predefined events

1) Ad Impression

       Automatically reported every time an ad gets displayed.

SESDK.trackAdImpression(data)

Parameter description:

Code Example:

SESDK.trackAdImpression({
  adNetworkPlatform: 'oppo',
  adType: 1,
  adNetworkAppID: '123',
  adId: '123',
  mediationPlatform: 'custom',
  ecpm: 13.140001,
  currency: 'USD',
  rendered: true,
  customProperties: {
    one: '1',
  }
})

2) Ad Click

   Automatically reported when ads are clicked.

SESDK.trackAdClick(data)

Parameter description:

Code Example

SESDK.trackAdClick({
  adNetworkPlatform: 'oppo',
  adType: 1,
  adId: '123',
  mediationPlatform: 'custom',
  customProperties: {
    one: '1',
  }
})

3) In-app Purchase

    It shall be triggered as users make a purchase.

SESDK.trackIAP(data)

Parameter description:

Note:

  The failureReason parameter should only be passed in when the payStatus is 2 (fail). For other statuses, simply pass "".

Code Example:

SESDK.trackIAP({
  orderId: '12345678',
  payAmount: 1234.5678,
  currencyType: 'USD',
  payType: 'alipay',
  productID: '12345678',
  productName: 'this is product name',
  productCount: 10,
  payStatus: 1,
  failReason: 'this is fail reason',
  customProperties: {
    one: '1',
  }
})

4) Self-Reported Attribution Results

     This feature allows developers to send attribution data from a third-party or self-attribution platform to SolarEngine. The reporting timing can be customized by developers. (Event Name: "_webAttr")

SESDK.trackAppAttr(data)

Parameter description:

Sample code:

SESDK.trackAppAttr({
  adNetwork: '123456',
  subChannel: '123456',
  adAccountID: '123456',
  adAccountName: '123456',
  adCampaignID: '123456',
  adCampaignName: '123456',
  adOfferID: '123456',
  adOfferName: '123456',
  adCreativeID: '123456',
  adCreativeName: '123456',
  attributionPlatform: '123456',
  customProperties: {
  	one: '1',
  }
})

5) In-App Order

       It shall be triggered as users initiate an order.

SESDK.trackOrder(data)

Parameter description:

Code Example:

SESDK.trackOrder({
  orderId: '12345678',
  payAmount: 1234.5678,
  currencyType: 'USD',
  payType: 'alipay',
  status: 'this is fail status',
  customProperties: {
    one: '1',
  }
})

6) Registration event

       It shall be triggered as users register.

SESDK.trackRegister(data)

Parameter description:

Code Example:

SESDK.trackRegister({
  regType: 'WeChat',
  registerStatus: 'success',
  customProperties: {
    one: '1',
  }
})

7) Login event

      It shall be triggered as users login.

SESDK.trackLogin(data)

Parameter description:

Code Example

SESDK.trackLogin({
  loginType: 'WeChat',
  loginStatus: 'success',
  customProperties: {
    one: '1',
  }
})

4.3. Custom Events

       In addition to the clearly predefined events listed above, developers can report custom events according to their own analysis needs.

       Developers should name the custom events following the guide below:

• String type
• Start with letters only.
• No more than 40 characters.
• Contain numbers, lowercase letters and underscores only.

Code Example:

SESDK.track('test', {
  one: '1',
});

4.4. Custom Properties

       A custom property is an Obejct where each key-value represents a property.

Key: Property Name

• String type
• Start with letters only.
• No more than 40 characters.
• Contain numbers, lowercase letters and underscores only.

Value: Property Value

• Support data types like string, number, boolean, and array
• For elements of an array, only string type is supported.
• For other types, they will be forcibly converted to strings and stored.

Custom Property Types

       The data type of custom event properties is determined by their data types reported for the first time and cannot be changed once confirmed. For subsequent reporting of the same properties, only properties with the same data types as the first time will be stored in the database.

Note:

  The data type of the property determines their analysis logic available in analysis models. For example, the numerical type can perform calculations such as maximum value, minimum value, and sum, while the Boolean type can perform calculations of true and false values. Therefore, when determining the format of data reporting, you need to consider the analysis scenarios and business needs and formulate a complete event tracking plan as directions.

4.5. Duration Events

       If you need to record the duration of an event, call the eventStart(eventName) to start timing, and configure the event namet. When the event comes to an end, you need to call eventFinish(event name, data), and a "_duration" property will automatically be added for this event (unit: millisecond). It should be noted that there can only be one timing task for the same event.

SESDK.eventFinish('testEvent', {
  one: '1',
});

5. Set User Property

SolarEngine provides multiple methods for reporting user properties. You can use these methods to add or modify user properties.

It is recommended for you to select properties that change infrequently or hold significant value, for example, age, game level, location, first payment time and total payment amount. Other properties with higher change frequency can be reported and recorded through events.

User property settings can be set by calling userUpdate, userInit, userAdd, userUnset, userAppend, or userDelete.

Note:

      The format requirements of user properties are consistent with those of event properties.

1)  userInit

       If you want to upload a batch of user attributes, among which the existing user attributes will not update their values, and the non-existing attributes will be created and saved, you can call userInit to set them.

Code Example

SESDK.userInit({
  regtime: "2021-03-01 12:34:56.789", // cusom property
  rolename: "engineer", // cusom property
  age: 29, // cusom property
});

2)  userUpdate

       For general user attributes, you can call userUpdate to set them. The attributes uploaded in this way will overwrite the original attribute values. If the user attribute does not exist before, it will be created, and the data type will follow the value passed in.

Code Example

SESDK.userUpdate({
  rolename: "leader", // cusom property
});

3)  userAdd

       If you want to report a numeric attribute and accumulate its values, you can call userAdd. If the attribute has not been set, it will be assigned a value of 0 and then calculated. You can pass in a negative value, which is equivalent to a subtraction operation.

Code Example

SESDK.userAdd({
  age: 1, // cusom property
});

Note:

  The value called by userAdd only allows Number type.

4)  userUnset

       When you want to clear the user attribute values of a user, you can call userUnset to clear the specified attributes (string array). If the attribute has not been created in the array, the attribute will not be created.

Code Example

SESDK.userUnset(["age"]);

       The parameter passed in by userUnset is the attribute name of the user attribute, and the type is a string array.

5)  userAppend

       You can call userAppend to append user attributes of array type. If the attribute does not exist, it will be created.

Code Example

SESDK.userAppend({
  location: ["BeiJing"], // cusom property
});

6)  userDelete

       You can call userDelete to delete users. After a user is deleted, you will no longer be able to query the user's user attributes, but the events generated by the user can still be queried.

Code Example

SESDK.userDelete(deleteType);

6. Data Connection between Native App and H5

       In certain scenarios, it is common to integrate H5 (HTML5) pages within a mobile app to achieve fast deployment and updates. However, due to technical limitations, the mobile app is unable to directly access and track event data occurring on the H5 page. To ensure data consistency between the mobile app and the H5 page, the SE SDK enables the data connection function.

Note:

      In this scenario, the appKey passed in when JSSDK is initialized needs to be consistent with the appKey passed in when APPSDK is initialized.

7. A/B testing

Common Questions

1. If the frontend project environment is non-Node environment, such as PHP, JSP, etc., and you encounter compilation errors when importing the SDK file with a relative path using the <script> tag, you can resolve it by importing the SDK file from the CDN using the <script> tag.
2. In case you encounter cross-origin exceptions during local development with SDK integration, you need to change the protocol header of the local development environment to HTTPS.

3. In an in-App environment, if WebView-embedded H5 tracking requests all fail with Network Error, ensure the HTML page is loaded via https:// instead of file://.

4. If the frontend project gets stuck during compilation after integrating the SDK, it may be due to ESLint validation failures on the SDK files. Please configure and ignore the SDK files in .eslintignore.

SDK Update Log

2026-02-02 1.3.2

• Optimized event reporting logic

2025-03-14 1.3.0

• Optimized event reporting logic

2025-03-13 1.2.9

• Optimized event reporting logic

2025-02-13 1.2.8

• Optimized purchase event reporting

2025-01-03 1.2.7

• Optimized purchase event reporting

2024-12-10 1.2.4

• Optimized event reporting logic

2024-11-29 1.2.3

• Optimized initialization logic

2024-11-11 1.2.2

• Optimized initialization logic

2024-10-31 1.2.1

• Added SDK internal logs reporting

2024-09-26 1.2.0

• Added getDistinct method

2024-08-14 1.1.9

• Optimized external API validation logic for the SDK.
• Fixed _log_count counting issue.

2024-05-22 1.1.8

• Optimized install event reporting.

2024-04-22 1.1.7

• Added _webEnd event to record the duration of the current page view with the _duration field.
• Optimized event reporting logic.

2024-04-16 1.1.6

• Optimized event reporting logic.

2024-04-01 1.1.5

• Fixed an issue where reported events could not be deleted under extreme scenarios.

2024-03-15 1.1.4

• Added new parameters to A/B test requests.

2024-03-01 1.1.3

• Fixed A/B Testing initialization parameters

2024-01-22 1.1.2

• Fixed internal logs reporting issue

2023-12-06 1.1.1

• Event reporting online verification

2023-11-02 1.1.0

• Add pre-initialization
• Add polling reporting of local unreported events

2023-08-16 1.0.6

• Event reporting and offline verification

2023-08-08 1.0.5

•Optimize plug-in loading mechanism

2023-07-31 1.0.4

• Supports communication with native App data
• Add multi-link test plug-in

2023-06-01 1.0.3

• Add Setting service
• SDK supports China Mainland SDK and international SDK
• Optimize SDK data reporting success logic

2023-04-26 1.0.2

• Optimize SDK UserDelete operation

2023-03-30 1.0.1

• SDK adds debugModel debugging mode

2023-03-20 1.0.0

• SolarEngine Web SDK first version
• Supports predefined attributes and custom attribute settings
• Supports predefined events and custom event reporting
• Support user attribute settings
• Support parameter delivery plug-in
• Support automatic buried point collection