1. SDK Basic Information

SolarEngine (SE) is an all-in-one mobile app growth analytics and publishing intelligent decision-making 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.

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

Note:

The frontend pages integrating the WebSDK must use the HTTPS protocol. Otherwise, it will make the WebSDK functionalities unavailable.

2. Before you start

Before officially starting data access, there are some parameters and SDK packages required. Follow the directions below to get prepared.

Step 1: Get User Code

Entry: Account Management - Account Profile - Secret - User Code

Step 2: Get AppKey

      Entry: Asset Management - App Management - AppKey

Step 3: Obtain SDK

Download China Mainland version SDK via  

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

Download Non-China-Mainland (International) version SDK via  

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

3. Initialize the SDK

3.1. SDK initialization

   It is recommended to initialize the SDK before any other mothods to ensure the accuracy of data initialization. Before initializing the SDK, a pre-initialization is required by calling the prevInit method and passing the appKey of the application. The SDK is built in UMD format and supports multiple loading methods. Below are commonly used loading methods:

import SESDK from './web-sesdk.js'
// pre-initialization
SESDK.prevInit(appKey);
// initialization
SESDK.init(initParams);

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

initParams parameter description:

Config parameter description:

Call example:

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

  As the initialization logic of the SDK is performed asynchronously, if the business scenario requires execution logic that depends on the completion of SDK initialization, you can call the ready method.

SESDK.ready(callback);

   During the SDK initialization process, if you need to load the SDK plug-in, you can call the use method.

SESDK.use(sdkPlugin);

Note:

  If the page integrating the WebSDK needs to be embedded in an Android app, the WebView used in the Android app must support storage functionality.

webView.getSettings().setDomStorageEnabled(true);

3.2. Visitor ID

      Visitor ID refers to the user's unique identifier (_visitor_id) after installing and before logging in.

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

      During data reporting, only the latest visitor ID passed in will be used. 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 the 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 of the user's login account within the app. Prior to logging in, visitor IDs will be used as the user identifier.

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

      During data reporting, only the latest account ID passed in will be used. Multiple calls should be avoided to prevent abnormal situations where multiple non-normal 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 the 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 refer to the properties that are included in every event, such as the user's source channel and the advertising ID associated with conversions.

      It is best to set public event properties before SDK initialization, which will guarantee that all the events reported later will have the public properties.

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

      The format requirements for public event attributes are consistent with event attributes , see " Event Reporting - Custom Attribute Requirements "

SESDK.setSuperProperties({
   key: value
});

       If you need to delete a public event property, you can call unsetSuperProperty to clear one of the public event properties;

SESDK.unsetSuperProperty(key);

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

SESDK.clearSuperProperties();

Note:

1. If setSuperProperties is called to upload previously set public event properties, the previous properties will be overwritten.
2. If the public event attribute and the key of an attribute uploaded by the event report are the same, the attribute of the event will overwrite the public event attribute.
3. Once set by the developer, it will be stored in local storage.

3.5. Preset event attributes

   The SolarEngine SDK supports developers to set custom properties for three preset events: app startup, installation, and exit.

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 after SDK initialization, 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 SEPresetEventType enumeration is set to SEPresetEventTypeAppInstall, it will override the custom properties set through the SEPresetEventTypeAppInstall, SEPresetEventTypeAppStart, and SEPresetEventTypeAppEnd enumerations. If set multiple times, only the last setting will be effective.
• Preset event properties can be cleared by calling the corresponding enumeration with nil as the property value. For example: [[SolarEngineSDK sharedInstance] setPresetEvent:SEPresetEventTypeAppStart withProperties:nil] can be used to clear the custom properties for the startup event. Clearing the installation and exit events only requires changing the corresponding enumeration value.
• SolarEngine SDK also supports clearing the custom properties for all preset events, including properties set through the SEPresetEventTypeAppInstall, SEPresetEventTypeAppStart, and SEPresetEventTypeAppEnd enumerations. This can be done by calling [[SolarEngineSDK sharedInstance] setPresetEvent:SEPresetEventTypeAll withProperties:nil] .

Call example:

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

3.6. Set other properties

Set channel name

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

SESDK.setChannel('channel');      

Set referrer page title

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

SESDK.setReferrerTitle('title');      

4. Event Reporting

  After the SDK initialization is complete, you can call "track" to report data.

  The reported data 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 installation, launch, exit, etc.

2. Predefined Events: These events have predefined meanings and event names in the system. They require developers to report data when the corresponding events occur, such as ad impressions, in-app purchases, etc.

3. Custom Events: These events can be custom defined by developers who need to instrument the code to trigger and report these events.

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

Note:

  The event name supports uppercase and lowercase Chinese and English, numbers, and underscores, and the length does not exceed 40 characters.

4.1. Preset events

1) Installation

       This event will be automatically reported every time users open it for the first time after installation. (If a use clears the application browser cache and opens it again, it will be counted as an installation.)

       The _event_name of the installation event is _webInstall.

2) Start

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

       The _event_name of the startup event is _webStart.

4.2. Predefined events

1) Ad Impression

       Automatically reported every time th ad gets displayed.

SESDK.trackAdImpression(data)

Parameter description:

Call 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:

Call example:

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

3) In-app Purchase

   Automatically reported when in-app purchasement is made.

SESDK.trackIAP(data)

Parameter description:

Note:

  The failureReason parameter is only be passed in when the payStatus parameter is SolarEngineIAPFail. For other statuses, simply pass "".

Call 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

       Enables the reporting of attribution results data from a third-party or self-attribution platform to SolarEngine. The timing of reporting can be customized by developers. (Event Name: "_appAttr")

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

       Used for order data analysis.

SESDK.trackOrder(data)

Parameter description:

Call example:

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

6) Registration event

       Automatically reported when users register within the app.

SESDK.trackRegister(data)

Parameter description:

Call example:

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

7) Login event

       When a user logs in, this event is reported for user login data analysis.

SESDK.trackLogin(data)

Parameter description:

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

       The custom event names should be customized by the developer.

       Here are the naming conventions for event names:

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

Call example:

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

4.4. Custom Properties

       A custom property is a Obejct 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 basic data types like String, int, long, float, double, boolean, and date
• 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 occurrence 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 summation, 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 name of the event. 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.

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

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

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

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

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

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

SDK Update Log

2024-10-31 1.2.1

• Added internal SDK log 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