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/TikTok/SolarEngine-TikTok-US-SDK-1.3.3.zip  

2.4. Configure TikTok Open Platform

• Get AppID and AppSecret

     Log in to「TikTok Open Platform」and go to the homepage > Developer Portal > Select your Mini Program > Basic Information > Credentials. Then copy the "Client key" and "Client Secret", and paste them into SolarEngine.

     TikTok Open Platform:

     SolarEngine Platform:

• Server Domain Configuration

     Log in to「TikTok Open Platform」and go to the homepage > Development configuration > Security > Add domian, and enter the following domains to complete the configuration (see example screenshot):

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

3. Initialize the SDK

3.1. SDK initialization

     It is recommended to import the SDK in the app.js file of your Mini Program project, and initialize it within onLaunch (triggered on Mini Program cold start) 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 Program. After importing the SDK in app.js, it is recommended to mount it to the global scope (e.g. globalThis) for use in other parts of the project.

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

// app.js
import SESDK from './minitiktok-us-sesdk-es.js';

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

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

App({
  onLaunch() {
    // 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',
  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
})

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 Program. (If a user deletes the Mini Program 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 Program is opened or brought to foreground from background.

       The _event_name is _mpStart.

3) End

       This event is automatically reported every time the Mini Program 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-06-10

• Support TikTok Mini Program