目录
此内容是否有帮助?

# Unreal Engine SDK User Guide

TIP

Before accessing, please read the preparation before accessing .

ThinkingAnalytics implements the built-in Analytics service of Unreal 4, and also supports reporting data directly through the C++ code call interface. Currently supports Android , iOS , Windows and MacOS platforms .

**The latest version is: **v1. 4.0 .

**Updated: **2021- 12 - 31

Download address (opens new window)

# I. Integrated SDK

# 1.1 Integration with ThinkingAnalytics Plugin

Download the Unreal SDK (opens new window), unzip and put ThinkingAnalyticsinto your project's Pluginsdirectory; if the Pluginsdirectory does not exist, first create the Pluginsdirectory under the project root directory, and then put the ThinkingAnalyticsdirectory into it.

# 1.2 Activate the ThinkingAnalytics plugin

In order to enable the ThinkingAnalytics plugin, you need to perform the following steps:

  • Restart Unreal Editor

  • Open, Edit > Plugins, under the Project Analyticscategory, enable ThinkingAnalytics

  • If you use Blueprint, enable the Analytics Blueprint Libraryunder the Built-in Analytics

  • Restart Unreal Editor again

  • Open, edit > project settings, under the plugin category, set the ThinkingAnalytics parameter:

    • Server Url: Required. Receiving end address, use an address of type https
    • App ID: Required. The APP ID of your project can be viewed on the TA background project management page
    • SDK MODE: SDK operation mode, the default is normal mode (Normal), you can refer to SDK mode
    • Enable Log: Whether to open client side log
    • TimeZone: Optional, if you need to align the time zone, please fill in the standard TimeZone ID, such as "Asia/Shanghai", "UTC". If you do not need to align the time zone, you do not need to fill in

      Note: Windows/MacOS does not support aligning time zones for the time being.

  • Add the following to the DefaultE ngine.inifile in the Configdirectory:

[Analytics]
ProviderModuleName=ThinkingAnalytics
  • If you want to use the ThinkingAnalyticsinterface directly in C++ code, you need to use the *. B uild.csadd the following to the file:
PrivateDependencyModuleNames.AddRange(new string[] { "ThinkingAnalytics" });

PrivateIncludePathModuleNames.AddRange(new string[] { "ThinkingAnalytics" });

Also, reference the ThinkingAnalytics.hheader file in the file you wish to use the SDK:

#include "ThinkingAnalytics.h"

# 1.3 Initialize SDK

Before calling the ThinkingAnalyticsinterface, you should first call the SDK's initialization interface.

If you use blueprints, you need to first call the StartSessioninterface of the Analytics Blueprint Library. You can also call the Initializeinterface under the Thinking Analyticscategory.

If called in C++ code, it can be called as follows:

// Initialize SDK
UThinkingAnalytics::Initialize();

Once the initialization is complete, events can be reported using the SDK. You can use the RecordEventinterface in the Analytics Blueprint Library, refer to UE4's official blueprint analysis plug-in (opens new window)guide, or use the interface provided by the UThinkingAnalyticsclass described below.

# II. Set User ID

By default, the SDK will use a random UUID as a visitor ID to identify a user, and the visitor ID will change when the user reinstates the game or changes the device.

# 2.1 Set Visitor ID (optional)

If your game has its own guest ID management system, you can call Identifyto set the guest ID:

UThinkingAnalytics::Identify("your_distinct_id");

If you need to get a visitor ID, you can call GetDistinctIdto get:

FString distinctId = UThinkingAnalytics::GetDistinctId();

# 2.2 Set Account ID

When the user logs in, you can call Loginto set the user's account ID. After setting the account ID, the account ID will be used as the identification ID, and the set account ID will be called LogoutIt has been retained until:

// Set Account ID
UThinkingAnalytics::Login("your_account_id");

// Clear Account ID
UThinkingAnalytics::Logout();

Note: This method does not upload user login, user login and other events.

The SetUserIdinterface in the Analytics Blueprint Libraryis equivalent to the above Logininterface.

# III. Upload Events

You can use the RecordEventinterface in the Analytics Blueprint Libraryto report the time, or you can use Json in C++ code to report events with event attributes more flexibly. In general, you may need to upload a dozen to hundreds of different events. If you are using TA background for the first time, we recommend that you upload a few key events first.

# 3.1 Upload Events

It is recommended that you set the properties of the event and the conditions for sending information according to the previously combed doc. The event type is a FStringtype that can only start with a letter and can contain numbers, letters, and an underscore "_". It is up to 50 characters in length and is not sensitive to letter case.

  • Event properties are FStringtypes in JSON format
  • Event property Keyis the property name, which can only start with letters, including numbers, letters and underscore "_", with a maximum length of 50 characters, and is not sensitive to letter case;
  • Four types of attribute values are supported: string, numeric class, bool, JSONArray
// Report an event without attributes
UThinkingAnalytics::Track("TEST_EVENT", "");

# 3.2 Record the Duration of the Event

You can call TimeEventto start timing, configure the event type you want to time, and when you upload the event, you will automatically add the #durationattribute to your event attribute to indicate the length of the record, in seconds.

// Call TimeEvent to open for TIME_ Timing of EVENT events
UThinkingAnalytics::TimeEvent("TIME_EVENT");

// do some thing...

// Upload TIME_via Track When an EVENT event occurs, the #duration attribute is added to the attribute
UThinkingAnalytics::Track("TIME_EVENT", "");

Note: Windows/MacOS does not support logging event duration for the time being.

# IV. User Attributes

TA platform currently supports the user feature setting interface for UserSet, UserSetOnce, UserAdd, UserDelete, UserUnset, UserAppend.

# 4.1 UserSet

For general user features, you can call the UserSetto set it. Attributes uploaded using this interface will overwrite the original attribute values. If the user feature does not exist before, the user feature will be created.

// UserSet Interface Definition
UThinkingAnalytics::UserSet(const FString& Properties);

The format requirements for user features are similar to those for event properties.

# 4.2 UserSetOnce

If the user feature you want to upload only needs to be set once, you can call UserSetOnceto set it. When the attribute already has a value before, this information will be ignored:

// UserSetOnce Interface Definition
UThinkingAnalytics::UserSetOnce(const FString& Properties);

Note: The user feature type and restrictions set by UserSetOnce are consistent with UserSet.

# 4.3 UserAdd

When you want to upload a numeric attribute, you can call UserAddto accumulate the attribute. If the attribute has not been set, it will be assigned a value of 0and then evaluated. Negative values can be passed in, which is equivalent to subtraction operations.

// Numeric user attributes minus 100.9
UThinkingAnalytics::UserAdd("USER_PROP_NUM", -100.9);

Note: The property types and key values of the UserAdd are restricted to the UserSet, but Value only allows numeric types.

# 4.4 UserDelete

If you want to delete a user, you can call UserDeleteto delete the user. You will no longer be able to query the user features of the user, but the events generated by the user can still be queried.

// delete user
UThinkingAnalytics::UserDelete();

# 4.5 UserUnset

If you need to reset a property of the user, you can call UserUnsetto delete the set property.

// Delete a user property
UThinkingAnalytics::UserUnset("userPropertyName");

# 4.6 UserAppend

You can call UserAppend to append elements to a user feature of type List.

// UserSetOnce Interface Definition
UThinkingAnalytics::UserAppend(const FString& Properties);

# V. Automatic Acquisition Events

The ThinkingAnalytics SDK provides automatic collection of three types of events:

  • ta_app_install: The game is installed, when the game is opened for the first time after installation, the event will be collected
  • ta_app_start: Collect the event when the game enters the foreground
  • ta_app_end: Collect the event when the game retreats to the background

By calling the EnableAutoTrackinterface, you can turn on automatic collection:

// Turn on automatic acquisition
UThinkingAnalytics::EnableAutoTrack();

Note: If you need to customize the guest ID, be sure to call the Identify interface to set the guest ID before turning on the automatic collection function.

Windows/MacOS does not currently support automatic event collection.

# VI. Other Interfaces

# 6.1 Get the Device ID

After the SDK is initialized, the device ID will be automatically generated and recorded in the local cache. For the same application/game, the device ID of a device is unchanged. You can call GetDeviceId ()to obtain the device ID:

FString deviceId = UThinkingAnalytics::GetDeviceId();

# 6.2 Flush

By default, data is stored in the local cache and then uploaded to the server level according to a certain reporting policy. You can call the Flushinterface if you want to report data in the cache immediately. The ``Flush Eventsinterface in the Analytics Blueprint Library eventually calls Flush:

UThinkingAnalytics::Flush();

# 6.3 Calibration Time

# Timestamp calibration

By default, the SDK uses the native time as the time of the event. If the user manually modifies the device time, which will affect your business analysis, you can use the current timestamp obtained from the server level to calibrate the SDK time. After that, all calls that do not specify a time, including event data and user feature setting operations, will use the calibrated time as the time of occurrence.

// 1585633785954 is the current UNIX time stamp in milliseconds corresponding to Beijing Time 2020-03-31 13:49:45
UThinkingAnalytics::CalibrateTime(1585633785954);

# NTP Calibration

New NTP time calibration interface in v1.3.0, you need to pass in the NTP server address that your users can access. The SDK then attempts to obtain the current time from the incoming NTP service address and calibrate the SDK time. If the correct return result is not obtained within the default timeout time (3 seconds), the data will be reported using the local time later.

UThinkingAnalytics::CalibrateTimeWithNtp(const FString& urlString);

Note: The calibration time should be performed after the initialization is completed, before starting automatic collection or reporting any other data; you can also calibrate the time first and then call the initialization interface . Time calibration is not currently supported on Windows/MacOS.

# 6.4 Pause/stop data reporting

There are two types of interfaces that stop SDK reporting:

# Pause SDK Reporting (EnableTracking)

You may want to temporarily stop SDK data collection and reporting in some scenarios, such as the user is in a test environment, or the user logged in to a test account. At this time, you can call EnableTrackingand pass in falseto suspend SDK reporting. The previously set visitor ID and account ID will be retained; the data that has been collected but has not been successfully reported will continue to try to report; you cannot collect and report any new data in the future. Cannot set guest ID, account ID, etc.

The stopped state of the SDK will be saved in the local cache until EnableTrackingis called and trueis passed, and the SDK will resume data collection and reporting.

// Pause reporting, cached data and set information are not cleared
UThinkingAnalytics::EnableTracking(false);

// Restore reporting
UThinkingAnalytics::EnableTracking(true);

# Stop SDK Reporting (OptOutTracking)

In some special situations, you may need to completely stop the SDK function. For example, in areas where GDPR is applicable, users choose not to provide data collection permissions, then you can call OptOutTracking. The biggest difference between this interface and EnableTrackingis that it will empty the local cache, including guest ID, account ID, and unreported data queue. Then turn off the collection and reporting functions.

// Stop reporting default instances and empty local caches
UThinkingAnalytics::OptOutTracking();

The stopped state of the SDK will also be kept in the local cache until OptInTracking is called, and subsequent reports can continue, but this is equivalent to a completely new instance.

// Re-start reporting
UThinkingAnalytics::OptInTracking();

Windows/MacOS does not support stopping/restarting the reporting function for the time being.

# 6.5 SDK Operation Mode

The SDK supports running in three modes:

  • NORMAL: Normal mode, data will be stored in the cache and reported according to a certain cache policy
  • DEBUG: Debug mode, data is reported one by one. When problems occur, the user will be prompted with logs and exceptions
  • DEBUG_ONLY: Debug Only mode, only check the data, not into the library

    Note: DEBUG mode is only used for integration phase data validation and should not be used in production mode.

Windows/MacOs does not support DEBUG / DEBUG_ONLY mode.

In order to prevent Debug mode from going live in the production environment, it is stipulated that only specified devices can turn on Debug mode. Debug mode can only be enabled on the client side, and the device ID is configured in the "Debug Data" section of the "Event tracking management" page in the background of the TA.

The device ID can be obtained in the following ways:

  • #device_id attribute in event data in TA platform
  • Client side log: The device DeviceId is printed after the SDK initialization is completed

# 6.6 Setting Public Event Properties

In v1.3.0 version, public event attributes are newly set. For some important attributes, such as the user's membership level, source channel, etc., these attributes need to be set in each event. At this time, you can set these attributes as public event attributes. The public event property refers to the property that each event will carry. We recommend that you set the public event property before sending the event.

UThinkingAnalytics::SetSuperProperties("{\"static_property1\":\"value1\",\"static_property2\":\"value2\"}");

You can also get the set public event properties.

FString SuperProperties = UThinkingAnalytics::GetSuperProperties();

# 6.7 Setting Dynamic Public Properties

After setting the dynamic public property class, the SDK will automatically execute when reporting event properties and get the properties in the return value, and add them to each event.

// Define dynamic common attribute functions
static FString TDReturnDyldParams() {
    return "{\"dyld_property1\":\"value1\",\"dyld_property2\":\"value2\"}";
}

// Set Dynamic Common Properties
void UMyDemoWidget::callSetDynamicSuperPropertiesFunction(){
    UThinkingAnalytics::dynamicPropertiesMap.insert(pair<FString,FString(*)(void)>("inset your appid" ,&TDReturnDyldParams));
}

# 6.8 Get Prefabricated Attributes

In v1.3.0 version of the new pre-acquisition system attribute interface, SDK will automatically add some built-in attributes when event attributes are reported, you can obtain preset attributes through this interface.

FString PresetProperties = UThinkingAnalytics::GetPresetProperties();

# VII. Advanced Functions

Starting from v1.1.0, the SDK supports the reporting of three special types of events: first events, updatable events, and rewritable events. These three events need to be used in conjunction with TA system 2.8 and later versions. Since special events are only applicable in certain specific scenarios, please use special events to report data with the help of Count Technology's customer success and analysts.

# 7.1 First Incident

First-time events are events that are recorded only once for an ID of a device or another dimension. For example, in some scenarios, you may want to record the first event on a device, so you can use first-time events to report data.

UThinkingAnalytics::TrackFirst(const FString& EventName, const FString& Properties);

If you want to determine whether it is the first time in a dimension other than the device, you can set FIRST_CHECK_ID for the first event. For example, if you need to record the first event of an account, you can set the account ID to the FIRST_CHECK_ID of the first event.

UThinkingAnalytics::TrackFirstWithId(const FString& EventName, const FString& Properties, const FString& FirstCheckId);

Note: Due to the completion of the verification of whether it is the first time at the server level, the first event will be delayed by 1 hour by default.

# 7.2 Updatable Events

You can implement the requirement to modify event data in a specific scenario through updatable events. Updatable events need to specify an ID that identifies the event and pass it in when the updatable event object is created. The TA background will determine the data that needs to be updated based on the event name and event ID.

UThinkingAnalytics::TrackUpdate(const FString& EventName, const FString& Properties, const FString& EventId);

# 7.3 Rewritable Events

Rewritable events are similar to updatable events, except that rewritable events will completely cover historical data with the latest data, which is equivalent to deleting the previous data and storing the latest data in effect. The TA background will determine the data that needs to be updated based on the event name and event ID.

UThinkingAnalytics::TrackOverwrite(const FString& EventName, const FString& Properties, const FString& EventId);

# Release Notes

# v1.4.0 2021/12/31

  • New Windows and MacOS platforms support event reporting, user features, advanced features, public properties
  • Added Windows and MacOS platform preset properties
  • Partial code logic adjustment

# v1.3.0 2021/08/27

  • Added prefabricated attribute acquisition interface
  • Support setting dynamic public properties
  • Support NTP/timestamp calibration time
  • Support static public property setting and getting

# v1.2.1 2021/06/29

  • Support visitor ID acquisition
  • Support device ID acquisition

# v1.2.0 2021/06/03

  • Optimize install, start event reporting logic
  • Optimized data transfer format
  • Added preset property #bundle_id (apply unique identification)
  • Code optimization
  • Upgrade native SDK version

# v1.1.0 2020/08/25

  • Supports first-time events, allowing custom ID checks to be passed in to verify whether it is reported for the first time
  • Supports updatable, rewritable events
  • Optimize the #lib/#lib_version field for UE4 SDK information
  • Upgrade the native SDK version to v2.6.0

# v1.0.3 2020/06/28

  • Optimization code: Avoid occasional null pointer exceptions in Android environment

# v1.0.2 2020/06/23

  • Added preset property #system_language
  • Upgrade native SDK version

# v1.0.1 2020/05/27

  • Solve packaging errors caused by unreasonable dependencies

# v1.0.0 2020/05/18

  • Supports event reporting and all user features
  • Support DEBUG mode
  • Support time zone alignment and time calibration
  • Support other auxiliary interfaces: Flush, OptOutTracking, OptInTracking, EnableTracking.

← Egret Engine Mini Game SDK User Guide →