User

Broadly speaking, a user refers to each unique individual who interacts with the product. Regardless of the number of devices they use or switch between, they are treated as a single user and identified with a unique cross-device and cross-platform ID: account ID. The account ID requires registration or login to be generated.

Narrowly speaking, a user refers to each unique device that accesses the product. Even if multiple individuals use the same device or an individual uses multiple devices, each device is counted as a separate user and identified with a unique device-centered ID: visitor ID.

However, in real life, a user might have a visitor ID after install and register for an account ID later. Therefore, we still need another ID to connect the user's behavior before and after registration. This ID is referred to as the user ID in the SolarEngine system.

In short, the user ID is to link the user's entire lifecycle and serves as a cross-platform identification ID. As it involves cross-platform recognition, in the user ID genration rules, the account ID takes precedence over the visitor ID in terms of priority.

User Identification

SolarEngine uses device ID, user ID, account ID and visitor ID to identify users.

• Device ID: A unique device identifier generated by SDK, with the attribute name "_distinct_id".
• User ID: A unique user identifier generated based on user identification rules (see below), with the attribute name "_user_id".
• Account ID: Reported by the developer, with the attribute name "_account_id".
• Visitor ID: Reported by the developer, with the attribute name "_visitor_id". If not provided, it takes the value of "_distinct_id".

Identification Rules

  Basic Rules:

• A single user ID can only be bound to 1 account ID and 1 visitor ID.
• The binding priority is given to account ID over visitor ID.
• One account ID can only be bound to 1 user ID.
• One visitor ID can only be bound to 1 user ID.

  Detailed Description:

• When only an account ID is present,
• If the account ID is already bound to a user ID, the data belongs to the bound user ID.
• If the account ID is not bound to an existing user ID, a new user ID is created and bound.
• When only a visitor ID is present,
• If the visitor ID is already bound to a user ID, the data belongs to the bound user ID.
• If the visitor ID is not bound to an existing user ID, a new user ID is created and bound.
• When both an account ID and a visitor ID are present, and the account ID is already bound to a user ID, the data belongs to the bound user ID. Then check the binding status of the visitor ID:
• If the visitor ID is already bound to a user ID, the binding status remains unchanged.
• If the visitor ID is not bound to any user ID, the following check is performed:
• If the account ID is already bound to another visitor ID, the visitor ID is not bound to any user ID.
• If the account ID is not bound to any visitor ID, the visitor ID is bound to the user ID that the account ID is bound to.
• When both an account ID and a visitor ID are present, and the account ID is not bound to an existing user ID, the binding status of the visitor ID is checked:
• If the visitor ID is bound to a user ID and the bound user ID is already associated with an account ID, a new user ID is created and bound to the current account ID.
• If the visitor ID is bound to a user ID but the bound user ID is not associated with an account ID, the current account ID is bound to the user ID.
• If the visitor ID is not bound to any user ID, a new user ID is created, and the current account ID, along with the visitor ID, is bound to the newly created user ID.

User Properties

User IDs can only be used to count the number of users but cannot meet more in-depth user analysis requirements. Therefore, SolarEngine provides the concept of user properties, allowing our clients to report user-related properties and utilize them within SolarEngine user analysis models to gain further insights into user behavior.

It is recommended to select properties that change infrequently or hold significant value, such as first payment time and total payment amount. Other properties with higher change frequency can be reported and recorded through events.

User properties are divided into preset user properties and custom user properties.

Preset User Properties

Here are the user properties collected by default.

Custom User Properties

In addition to preset ones, you can also customize user properties based on your analysis requirements. It is recommended to synchronize these properties in the event tracking plan to enbale information sharing among all team members.

Data Reporting Format Table

Device

Many of our clients do not enforce user login in their applications. In such cases, the device ID serves as the visitor ID. As for applications with few multi-device logins or without a login system at all, like some IAA hyper casual games, we can directly use the device ID as a unique identifier for users.

In this context, we developed the Device Table to record and update device-level properties and advertising-related data in real time.

Device ID (_distinct_id) Generation Rules:

Device Table

When a device generates an event for the first time, its device ID and properties of this event will be added into the device table in real time.

The device table updates its properties daily at 2:00 a.m. for devices added the day before, using the latest non-empty property values reported.

The Application of Device Table

The device table can be used in the following scenarios:

• User Analysis

Device properties can be used as the conditions to filter analysis subjects or group users.

Multiple analysis models support device-level user behavior analysis.

• Online Parameter

Taking "_distinct_id" as the traffic diversion entity, you can use properties in the device table as conditions to further filter the audience.

• A/B Testing

Taking "_distinct_id" as the traffic diversion entity, you can use properties in the device table as conditions to further filter the audience.

Event

Events represent specific actions that users perform within a product (App/Mini-program/Web Page). These events can include interactions such as app launches, registration, login, page views, purchases, or any other meaningful actions. Some events occur only once in a user's lifecycle, such as registration. However, most events occur multiple times, such as app launches, ad impressions, purchases and so on.

A complete event should consist of the following elements:

•Who: User information, such as the user ID.

•When: The time when the event occurs.

•Where: The location where the event occurs.

•How: Refers to how the user engages in the event. It includes various aspects, such as the device and browser used, app version, operating system, channel of acquisition, etc. You can also customize more properties as needed.

After a user is acquired, there will be many events to occur. These events are independent and arranged in chronological order (see pic). For each user, there is only one piece of record that integrates all their properties (see pic).

Event data is stored in an event table, while user data is stored in a user table. These two tables are associated with each other using the user ID as a common identifier.

Due to different event collection methods, SolarEngine divides events into preset events and self-reported events (event tracking).

Preset Events

Preset events do not require any additional tracking code inserted. They are automatically collected and recorded by the SolarEngine SDK, including app install, app launch and app exit.

Self-Reported Events

In practical business operations, besides preset events, developers often need to define and report more events for analysis. Therefore, SolarEngine provides two methods, SDK and API, for our clients to report events according to their own needs.

In SolarEngine, self-reported events are categorized into three types: predefined events, automatically captured events, and custom events.

Predefined Events

1) Ad Impression

Automatically reported when displaying ads within the app, which is essential for ad revenue measurement in ROI analysis and user analysis. (Event Name:  "_appImp")

2) Ad Click

Automatically reported when users click ads within the app. (Event Name:  "_appClick")

3) In-App Purchase

Automatically reported when users make purchases within the app (Event name: "_appPur"), which is essential for IAP revenue measurement. It is also a key event for training the payment prediction model, so if you are using our payment prediction services, "_appPur" will be a mandatory event to report.

4) Order

Automatically reported when users place orders within the app. (Event Name: "_appOrder")

5) Registration

Automatically reported when users register within the app. (Event Name: "_appReg")

6) Login

Automatically reported when users log into the app. (Event Name: "_appLogin")

7) Attribution

Allows our customers to send us the attribution results from a third-party attribution platform or SANs. You can define when and how to report this event. (Event Name: "_appAttr")

Automatically Captured Events

You can set up automatically captured events when initializing the SolarEngine SDK.

1) _appViewScreen

Report when users view a specific page within the app.

2) _appElementClick

Report when users click a specific element within the app.

Custom Events

In addition to those industry-wide events listed above, you can also custom-define and report events based on your analysis goals.

Here are the naming conventions for custom events:

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

Event Properties

Event properties are divided into: general event properties, public event properties, predefined event properties, automatically captured event properties and custom event properties, each corresponding to the events mentioned above.

General Event Properties

General event properties are reported by the SolarEngine SDK.

Custom Event Properties

After defining custom events, you are also prompted to set up their properties according to the integration documentation for different platforms.

Note that the data type of custom event properties is determined by their data types reported for the first time and cannot be changed once confirmed.

Data Reporting Format Table

Predefined Event Properties

Predefined event properties include general event properties, custom event properties and properties specific to predefined events.

Here is an explanation of properties specific to predefined events.

1）_appImp

2）_appClick

3）_appPur

4）_appOrder

5）_appReg

6）_appLogin

7）_appAttr

Automatically Captured Event Properties

   Automatically captured event properties include general event properties, self-reported custom event properties, and predefined properties for the event.

1）_appViewScreen

2）_appElementClick

First Time/Day Properties

When analyzing user behavior, we might pay more attention to events that occur on the first day after app installation, or for the first time after user acquisition regardless of whether it's on the first day or later. Therefore, we developed two more identifiers for each event: "_is_first_day" and "_is_first_time".

The value of these two identifiers is either true or false.

As you can see, we will validate and correct the value of the two markers for certain important events like "_appInstall" based on the user data reported before, so that the markers can be more reliable.

If you decide to report data through API, the responsibility for value assignment accuracy and accountability lies with the developer.

Event Tracking Plan

Given the high complexity of user behavior and huge quantity of events, it is recommended that you and your team establish a unified event tracking plan document to standardize the process and maintain data consistency.

Event data can be reported through either SDK or API. The only difference between these two methods is that SDK automatically collects certain events for you, such as app install, launch and exit, while API requires you to create customized code for each event you want to track.

SDK/API integration is performed on an application level, so please use different AppKeys for different apps.

Considerations

• Determine user identification method, such as user ID, or device ID.
• Determine events, event properties, and event triggers.
• Determine user properties.
• Prioritize the implementation of event tracking.

Naming Conventions

In event tracking, custom event identifiers and custom property identifiers must adhere to the following naming conventions: they can consist of lowercase letters, numbers and underscores, but cannot begin with an underscore, contain spaces, or exceed 40 characters.

• The data type of property values is determined by the format type used in the initial reporting. Subsequent reports will only accept inputs of the same type. Otherwise, the data will be considered erroneous and will not be stored in the database.
• Event identifiers and property identifiers are for development personnel to use and should be filled in by technical staff.
• For event triggers, it is recommended to align the calibration internally between operations and development personnel, and then fill in the information uniformly to ensure data consistency and accuracy.