1. SDK Basic Information

SolarEngine (SE) is an all-in-one mobile app growth analytics and data intelligence platform, designed to assist developers to monitor every stage of business development. We provide both fixed analysis reports and highly customizable data analytics services, allowing developers to personalize configurations across multiple aspects, including data tracking, property settings, report creation, and dashboard configuration.

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

2. Before you start

2.1. Get User Code

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

2.2. Get AppKey

      Access Path: Asset Management - App Management - AppKey

2.3. Obtain SDK

Download SDK (UMD and ES packages provided) :

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

2.4. Configure Douyin Open Platform

• Get AppID and AppSecret

     Log in to「抖音小游戏_开发者平台」and go to the homepage > 开发 > 开发设置 > 开发管理 > 小程序Key. Then copy the AppID and AppSecret, and paste them into SolarEngine dashboard.

• Server Domain Configuration

     Log in to「抖音小游戏_开发者平台」and go to the homepage > 开发 > 开发设置 > 开发管理 > 服务器域名 > request 合法域名, and enter the following domains to complete the configuration (see example screenshot):

• https://api-receiver.detailroi.com
• https://rule.detailroi.com

3. Initialize the SDK

3.1. SDK initialization

    It is recommended to import and initialize SDK in the entry JS file of your Mini Game project to ensure data accuracy. Before initializing the SDK, you need to perform pre-initialization by calling the prevInit method and passing in the appKey.

    Note: The SDK should only be imported once in one Mini Game. After importing the SDK in app.js, it is recommended to mount it to the global scope (e.g. globalThis) for use elsewhere.

Import the ES format file for ES Modules environments; otherwise, use the UMD format.

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

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

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

initParams parameter description:

Config parameter description:

Sample Code

SESDK.prevInit('666666');
SESDK.init({
  appKey: '666666',
  userId: '888888',
  openid: 'xxxxxxxxxxx',
  anonymous_openid: 'ccccccccccc',
  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);

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

3.6.1. Set channel name

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

SESDK.setChannel('channel');      

3.6.2. Set referrer page title

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

SESDK.setReferrerTitle('title');      

3.6.2. Set current page title

       Call setXcxPageTitle method to set the current page title information "_page_title".

SESDK.setXcxPageTitle('title');      

3.7. Get distinct_id & distinct_id_type

       Call getDistinct method to retrieve distinct_id and distinct_id_type. This method returns a Promise object.

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

3.8. Get Attribution Results

3.8.1. Set Attribution Callback Listener

       Developers can set a callback listener for attribution results. This method can only be called once and returns a Promise object.

SESDK.setOnAttributionListener().then(res => {
   // res.result
})

3.8.2. Actively Retrieve Attribution Results

       Developers can actively retrieve attribution results. This method can be called multiple times and returns a Promise object.

SESDK.getAttribution().then(res => { 
     // res.result
})

Attribution Results Example

Re-engagement attribution results will be displayed in "re_data".

{
            //New user attribution results
            "account_id": "",
            "ad_type": "",
            "adcreative_id": "",
            "adcreative_name": "",
            "adcreative_type": "",
            "adgroup_id": "",
            "adgroup_name": "",
            "adplan_id": "",
            "adplan_name": "",
            "attribution_time": "2023-08-31 11:16:35",
            "attribution_touch_type": "",
            "attribution_type": "",
            "callback_id": "",
            "channel_id": "-1",
            "channel_name": "organic",
            "click_id": "",
            "conversion_id": "",
            "custom_params_1": "",
            "custom_params_10": "",
            "custom_params_2": "",
            "custom_params_3": "",
            "custom_params_4": "",
            "custom_params_5": "",
            "custom_params_6": "",
            "custom_params_7": "",
            "custom_params_8": "",
            "custom_params_9": "",
            "impression_id": "",
            "install_time": "2023-08-31 11:16:32",
            "placement_id": "",
            "report_time": "2023-08-31 11:16:34",
            "request_id": "",
            "ry_touchpoint_ts": "",
            "site_id": "",
            "site_name": "",
            "turl_campaign_id": "",
            "turl_campaign_name": "",
            "turl_id": "",
            "re_data": {
                //Re-engagement attribution results
                "account_id": "",
                "ad_type": "",
                "adcreative_id": "",
                "adcreative_name": "",
                "adcreative_type": "",
                "adgroup_id": "",
                "adgroup_name": "",
                "adplan_id": "",
                "adplan_name": "",
                "attribution_time": "2023-08-31 11:16:35",
                "attribution_touch_type": "",
                "promotion_objectives": "",
                "callback_id": "",
                "channel_id": "-1",
                "channel_name": "organic",
                "click_id": "",
                "conversion_id": "",
                "custom_params_1": "",
                "custom_params_10": "",
                "custom_params_2": "",
                "custom_params_3": "",
                "custom_params_4": "",
                "custom_params_5": "",
                "custom_params_6": "",
                "custom_params_7": "",
                "custom_params_8": "",
                "custom_params_9": "",
                "impression_id": "",
                "install_time": "2023-08-31 11:16:32",
                "placement_id": "",
                "report_time": "2023-08-31 11:16:34",
                "request_id": "",
                "ry_touchpoint_ts": "",
                "site_id": "",
                "site_name": "",
                "turl_campaign_id": "",
                "turl_campaign_name": "",
                "turl_id": ""
            }
        }

attributionData parameter description:

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:

Event name supports uppercase and lowercase English characters, numbers, and underscores. Limit 40 characters.

4.1. Preset events

1) Install

       This event is automatically reported when users first open Mini Game. (If a user deletes the Mini Game and opens again, it will count as a new install.)

       The _event_name is _mpInstall.

2) Start

       This event is automatically reported every time the Mini Game is opened or brought to foreground from background.

       The _event_name is _mpStart.

3) End

       This event is automatically reported every time the Mini Game is brought to background from foreground.

       The _event_name is _mpEnd.

4.2. Predefined events

4.2.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',
  }
})

4.2.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',
  }
})

4.2.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 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.2.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: "_mpAttr")

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',
  }
})

4.2.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',
  }
})

4.2.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',
  }
})

4.2.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 Object 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',
});

       When reporting the preset event _appEnd, the SDK will automatically report the duration timed from the previous _appStart. In other words, you do not need to manually configure the start time for the exit event; the duration will be assigned by default.

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.

5.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
});

5.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
});

5.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.

5.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.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
});

5.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);

// Delete user by AccountId
SESDK.userDelete('userDeleteByAccountId'); 

// Delete user by VisitorId
SESDK.userDelete('userDeleteByVisitorId');

Changelog

2026-02-02 1.3.2

• Event reporting logic optimization

2025-03-14 1.3.0

• Event reporting logic optimization

2025-03-13 1.2.9

• Event reporting logic optimization

2025-02-13 1.2.8

• Payment event reporting optimization

2025-01-03 1.2.7

• Payment event reporting optimization

2024-12-31 1.2.6

• Internal initialization logic optimization

2024-12-10 1.2.4

• Compatible with CocosCreator platform compilation and build

2024-11-29 1.2.3

• Initialization logic optimization
• Attribution data result structure adjustment

2024-11-11 1.2.2

• Optimized event reporting logic

2024-10-31 1.2.1

• Added SDK internal log reporting

2024-08-14 1.1.9

• The type of the reported scene value _launch_scene was changed from numeric to string

2024-05-22 1.1.8

• Fixed the issue of the Douyin Mini Game install event being reported multiple times

2024-04-22 1.1.7

• 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 in extreme scenarios
• Optimized the trigger timing of the ready hook in Mini Programs

2024-03-15 1.1.4

• Added new parameters to A/B test requests

2024-03-01 1.1.3

• Fixed A/B test initialization parameter issue

2024-01-22 1.1.2

• Fixed internal log reporting issue

2023-12-06 1.1.1

• Added getDistinct method to get distinct_id and distinct_id_type
• Added setOnAttributionListener method to set a callback for listening to attribution results
• Added getAttribution method to actively get attribution result information
• Added unionid parameter to the init method
• Added signature verification for event reporting

2023-11-02 1.1.0

• Supported pre-defined property and custom property settings
• Supported pre-defined event and custom event reporting
• Supported user property settings
• Supported A/B testing plugin