# History Version Unity SDK Usage Guide
The Unity SDK has been upgraded to v2.0.0. This article is a guide to the use of historical versions. If you need new access, please refer to the latest Unity SDK use guide
This guide describes how to access your project using the Unity SDK. It is recommended to read the Data Rules chapter before accessing. You can get the Unity SDK source code at GitHub (opens new window).
**The latest version is: **v1.4.4
**Updated: **2020-04-17
Download address (opens new window)
# I. Initialize SDK
# 1.1 Integrated SDK
Download the Unity SDK (opens new window)resource file and import the resource file into your project:
Assets > Import Package > Custom Package
, select the file you just downloadedNote: The Android plug-in uses Gradle integration, so currently only Unity 5.4 and later versions are supported.
Add ThinkingAnalytics GameObject and set SDK configuration
The configurations in the above figure are:
Configuration
- Enable Log: Whether to turn on the log, if so, the report will be printed to facilitate your debugging. You can also verify that events are reported correctly in Editor mode. For unqualified attributes, a
warning
log will be displayed in the console. - Network Type: Set the network conditions for reporting data to the server. The default is
DEFAULT
. The following are all options and corresponding instructions:- DEFAULT: Reporting data in 3G, 4G, 5G and WIFI environments
- WIFI: only report data in WIFI environment
- ALL: Reporting data in 2G, 3G, 4G, 5G and WIFI environments
- Postpone Track: Set whether to delay reporting. After this option is turned on, the data will not start reporting until
StartTrack ()
is called. The data will be cached before the call untilStartTrack ()
is called. **If you need to set the guest ID or public attributes, it is recommended that you turn this on **, please refer to the delayed reporting section for invocation
Tokens
Each Token identifies an instance. If you need to report data to multiple projects, you can click the '+' sign in the lower right corner to increase the project configuration. For multi-project precautions, please refer to the 'Multi-Project Support' section at the end of the section. You can add multiple Token configurations with different APP IDs.
- The APP_ID of your project will be given when you apply for the project, please fill in here.
- SERVER URL: Need to be configured for the URL of the data receiving end:
- If you are using Cloud as a Service, enter the following URL:
- https://receiver.ta.thinkingdata.cn
- If you are using the version of private deployment, enter the following URL:
- https://Data Acquisition Address
- If you are using Cloud as a Service, enter the following URL:
- MODE: SDK instance operation mode. Please use NORMAL mode for the generation environment. Please refer to SDK mode for details.
- Auto Track: Whether to turn on automatic collection events. If checked, the SDK will automatically record the start and close of the game. For details, please refer to automatic collection events
- TimeZone: Supported since v1.4.3, the default alignment time zone for data. This setting is currently only valid for the event time and the time set by the user feature, not for the DateTime type in the property.
Note: Since some devices prohibit plaintext transmission by default, it is strongly recommended that you use the receiving end address in HTTPS format.
# Multi-project Support
When configuring the SDK, you can add multiple APP IDs, and then when calling the API, finally attach a parameter to specify the APP ID. Take the Identify ()
interface as an example:
// Set the visitor ID for the APP ID instance of "debug-appid"
ThinkingAnalyticsAPI.Identify("unity_debug_id", "debug-appid");
Note: Visitor IDs, account IDs, public attributes, etc. are not shared among multiple projects, and need to be set separately for each APP ID instance.
If no APP ID parameter is attached, the first APP ID instance in the list is used by default (the instance identified by default after the Token ID). You can adjust the default APP ID instance by dragging the list items to adjust the list order.
# 1.2 Use the SDK
Once you have finished configuring the SDK, you can start uploading events using the SDK, and we have provided Samples for your reference.
using ThinkingAnalytics;
ThinkingAnalyticsAPI.Track("unity_start");
# II. Set User ID
After using the Unity SDK, the SDK will use random UUID as the guest ID of each user by default, and this ID will be used as the user's identification ID when the user is not logged in. It should be noted that the default guest ID will change when the user reinstates the game and changes the device.
# 2.1 Set Visitor ID (optional)
If your game has its own guest ID management system for each user, you can call Identify
to set the guest ID:
ThinkingAnalyticsAPI.Identify("unity_id");
If you need to get a guest ID, you can call GetDistinctId
to get:
ThinkingAnalyticsAPI.GetDistinctId();
# 2.2 Set and Clear Account ID
When the user logs in, you can call Login
to set the user's account ID. After setting the account ID, the account ID will be used as the user identification ID, and the set account ID will be called Logout
It has been retained until:
// Set Account ID
ThinkingAnalyticsAPI.Login("unity_user");
// Clear Account ID
ThinkingAnalyticsAPI.Logout();
Note: This method does not upload user login, user login and other events.
# III. Upload Events
The ThinkingAnalytics API. Track ()
allows you to report events and their properties. 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. Event type is a string
type 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.
Dictionary<string, object> properties = new Dictionary<string, object>()
{
{"KEY_DateTime", DateTime.Now.AddDays(1)},
{"KEY_STRING", "B1"},
{"KEY_BOOL", true},
{"KEY_NUMBER", 50.65}
};
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties);
- Event attributes are of type
Dictionary < string, object >
, where each element represents an attribute; - The event attribute
Key
is the attribute name, which is ofstring
type. It can only start with letters, including numbers, letters and underscore "_", with a maximum length of 50 characters, and is not sensitive to letter case; - Property values support five types: string, numeric,
bool
,DateTime
, andList
types.Note: List type is supported in versions after v1.4.0, and its elements will be converted to string for storage.
When you call Track ()
, the SDK will take the current system time as the time when the event occurred. If you need to specify the event time, you can pass in DateTime
type parameters to set the event trigger time. Since the v1.3.0 version, the SDK supports uploading the time offset of the event according to the DataTimeKind
(corresponding to the preset attribute #zone_offset), but if the incoming DateTime
's Kind
attribute is DataTimeKind. Unspecified
, the time offset will not be reported:
DateTime dateTime = DateTime.Now.AddDays(-1);
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties, dateTime);
Since v1.4.3, you can configure the default time zone for an SDK instance. If you configure a non-Local time zone, all event times will be aligned to that time zone, and the Kind
property of the DateTime
you pass in will be ignored.
Note: Although the trigger time can be set for the event, the receiving end will only receive data from the first 10 days to the last 3 days relative to the server time. Data exceeding the time limit will be regarded as abnormal data and the whole data cannot be stored.
# 3.2 Set Static Public Properties
For some important attributes, such as the player's zone suit and channel, 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. You can call SetSuperProperties
to set the public event property. We recommend that you set the public event property before sending the event.
Dictionary<string, object> superProperties = new Dictionary<string, object>()
{
{"SERVER", 0},
{"CHANNEL", "A3"}
};
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);
The public event properties will be saved to the cache and need not be called every time the app is started. If a call to SetSuperProperties
uploads a previously set public event property, the previous property is overwritten. If the public event property and the Key
of a property uploaded by Track ()
duplicate, the property of the event overrides the public event property.
If you need to delete a public event property, you can call UnsetSuperProperty ()
to clear one of the public event properties; if you want to empty all public event properties, you can call ClearSuperProperties ()
.
// Clear public property named CHANNEL
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");
// Clear all public attributes
ThinkingAnalyticsAPI.ClearSuperProperties();
# 3.3 Set Dynamic Public Properties
If the value of the public property is not constant, you can do it by setting the dynamic public property. The dynamic public property is also added to all events, and the actual reported value is dynamically obtained when the event is reported.
To set dynamic public properties, you need to create a new dynamic public property class and implement the IDynamicSuperProperties interface, overwrite the public Dictionary < string, object > GetDynamicSuperProperties ()
method, and the return value of this method is the dynamic public property that needs to be set. Then call SetDynamicSuperProperties
to pass in the dynamic public property object, the sample is as follows:
using ThinkingAnalytics;
// Define the implementation of dynamic common attributes, for example, to set dynamic common attributes for UTC time
public class DynamicProp : IDynamicSuperProperties
{
public Dictionary<string, object> GetDynamicSuperProperties()
{
return new Dictionary<string, object>() {
{"KEY_UTCTime", DateTime.UtcNow}
};
}
}
ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());
Note: If the event property has a duplicate name, the dynamic public property has a higher priority than the public event property and is less than the event property set in Track.
# 3.4 Record the Duration of the Event
If you need to record the duration of an event, you can call TimeEvent ()
to start timing, configure the event type you want to time, and when you upload the event, you will automatically add #duration
to your event attribute to indicate the duration of the recording, in seconds.
// Call TimeEvent to open for TIME_ Timing of EVENT events
ThinkingAnalyticsAPI.TimeEvent("TIME_EVENT");
// do some thing...
// Upload TIME_via Track When an EVENT event occurs, the #duration attribute is added to the attribute
ThinkingAnalyticsAPI.Track("TIME_EVENT");
# IV. User Attributes
TA platform currently supports the user feature setting interface for UserSet
, UserSetOnce
, UserAdd
, UserUnset
, UserDelete
, UserAppend
.
# 4.1 UserSet
For general user features, you can call the UserSet
to 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.
ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>()
{
{"USER_PROP_NUM", 0},
{"USER_PROP_STRING", "A3"}
});
Similar to event properties:
- The user feature is a
Dictionary < string, object >
type, where each element represents an attribute; - User feature
Key
is the attribute name, for thestring
type, the provisions can only start with a letter, including numbers, letters and underscore "_", the maximum length of 50 characters, not sensitive to letter case; - User feature values support four types: string, numeric class,
bool
,DateTime
, andList
.Note: List type is supported in versions after v1.4.0, and its elements will be converted to string for storage.
# 4.2 UserSetOnce
If the user feature you want to upload only needs to be set once, you can call UserSetOnce
to set it. When the attribute already has a value before, this information will be ignored:
ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>()
{
{"USER_PROP_NUM", -50},
{"USER_PROP_STRING", "A3"}
});
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 UserAdd
to accumulate the attribute. If the attribute has not been set, it will be assigned a value of 0
and then evaluated. Negative values can be passed in, which is equivalent to subtraction operations.
ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>()
{
{"USER_PROP_NUM", -100.9},
{"USER_PROP_NUM2", 10.0}
});
Note: The restrictions on attribute types and key values in UserAdd are consistent with UserSet, but Value only allows numeric type attributes to be reported.
# 4.4 UserUnset
If you need to reset a user attribute, you can call UserUnset
to clear the value of the user feature specified by the user. This interface supports passing in parameters of string or list type:
// Delete individual user attributes
ThinkingAnalyticsAPI.UserUnset("userPropertyName");
// Delete individual user attributes
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");
ThinkingAnalyticsAPI.UserUnset(listProps);
# 4.5 UserDelete
If you want to delete a user, you can call UserDelete
to 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.
ThinkingAnalyticsAPI.UserDelete();
# 4.6 UserAppend
Starting with v1.4.0, you can call UserAppend
to append elements to a user feature of type List
:
List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
stringList.Add("cat");
// Name property USER_ LIST adds 3 elements to its user attributes
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>
{
{"USER_LIST", stringList }
});
# V. Automatic Acquisition Events
If the Auto Track option is checked when configuring the SDK, the SDK will automatically record:
ta_app_start
That is, the game launch event is triggered every time the user gains focus (that is, in the game)ta_app_end
The game shutdown event is triggered when the game enters thePause
state, and the#duration
attribute will be attached to record the duration of the game (in seconds)
Starting from version 1.1.0, installation events can be collected through interface calls:
// Collect APP installation events
ThinkingAnalyticsAPI.TrackAppInstall();
ta_app_install
, the game installation event, the installation event will only start when the user opens the APP for the first time after installation, the user upgrades the APP will not trigger, and the event will be triggered again after the user deletes and reinstates the APP.
# VI. Other Configuration Options
# 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:
ThinkingAnalyticsAPI.GetDeviceId();
// Use Device ID as Visitor ID
// ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());
# 6.2 Delayed Reporting
If you check the Postpone Track option, it means that all report requests (including user feature settings and event tracking) will be cached until you actively call the following methods:
ThinkingAnalyticsAPI.StartTrack();
When this interface is called, the data will start to be reported. **For the data generated before the interface is called, when reporting, the user ID will be reset and public attributes will be added **. Therefore, setting the user ID and public attributes before calling StartTrack ()
can be effective for all data, suitable for scenarios that need to **set guest ID and public attributes **:
//Set Visitor ID
ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());
//Setting Common Properties
Dictionary<string, object> superProperties = new Dictionary<string, object>()
{
{"SERVER", 0},
{"CHANNEL", "A3"}
};
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);
//Call Update Start Interface
ThinkingAnalyticsAPI.StartTrack();
# 6.3 Pause/stop Data Reporting
In version 2.1.0, the function of stopping SDK reporting data has been added. There are two types of interfaces to stop SDK reporting:
- Suspend 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 logs in to a test account. At this time, you can call the following interfaces to temporarily stop SDK reporting.
You can call EnableTracking
through an instance (including the main instance and the light instance) and pass in false
to suspend the reporting of the SDK. The #distinct_id
, #account_id
, and public attributes that have been set by the instance will be retained; the data that has been collected but has not been successfully reported by the instance will continue to try to report; the subsequent instance cannot collect and report any new data, cannot set visitor ID, account ID, and public attributes, etc., but can read the public attributes and Device ID, guest ID, account ID and other information.
The stop state of the instance will be saved in the local cache until EnableTracking
is called and true
is passed in. The SDK instance will resume data collection and reporting. It should be noted that the light instance is not cached, so every time you open the APP, The paused state of the light instance will not be retained, and the reporting will be reopened.
// Pause reporting of default instances, cached data and information that has been set are not cleared
ThinkingAnalyticsAPI.EnableTracking(false);
// Restore reporting of default instances
ThinkingAnalyticsAPI.EnableTracking(true);
- Stop SDK reporting (OptOutTracking)
In some special situations, you may need to completely stop the functions of the SDK. For example, in areas where GDPR is applicable, users choose not to provide data collection permissions, you can call the following interface to completely turn off the functions of the SDK.
OptOutTracking
can only be called through the primary instance, and the biggest difference with EnableTracking
is that it will empty the local cache of the instance, including the guest ID, account ID, public attributes, and unreported data queues of this instance. Then turn off the collection and reporting functions of this instance.
// Stop reporting default instances and empty local caches
ThinkingAnalyticsAPI.OptOutTracking();
If you want to delete the user's user data in the TA cluster while turning off the SDK function, you can call OptOutTrackingAndDeleteUser
, which will report a piece of UserDelete
data before stopping the function of the SDK instance to delete the user's user data.
// Stop reporting the default instance and send user_ Del
ThinkingAnalyticsAPI.OptOutTrackingAndDeleteUser();
The stopped state of the instance will also be saved 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
ThinkingAnalyticsAPI.OptInTracking();
# 6.4 Creating Light Instances
You can create multiple instances under the same APP ID by light instances
// Create a light instance and return to the token of the light instance (Like APP ID)
string lightToken = ThinkingAnalyticsAPI.CreateLightInstance();
// Set Account ID for Light Instance
ThinkingAnalyticsAPI.Login("anotherAccount", lightToken);
// Report Events via Light Instance
ThinkingAnalyticsAPI.Track("TEST_EVENT", lightToken);
Note: The APP ID, reporting address and some settings of the child lightweight instance are consistent with the parent instance, but other information is not shared
# 6.5 SDK Operation Mode
Since v1.4.0, 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, users 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.
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 three ways:
- #device_id attribute in event data in TA platform
- Client side log: The device DeviceId is printed after the SDK initialization is completed
- Called through the instance interface: get device ID
# Release Note
# v1.4.4 2020/04/17
- Fix double type formatting error in custom CultureInfo scenario
# v1.4.3 2020/03/19
- Supports default time zone settings for data #time property
- Update native SDK version
# v1.4.2 2020/02/21
- Update iOS plugin to fix bugs introduced in older versions iOS systems
# v1.4.1 2020/02/14
- Adapt to Unity 2019.3.1f1
# v1.4.0 2020/02/11
- Property values support List/Array types
- Add UserAppend interface
- Support Debug mode data validation
- Support to configure the receiving end address separately for each instance
- Remove local data format validation
# v1.3.1 2019/12/25
- Fix Android 4.3 Exit Timeout
- Fix an error when iOS development environment is not included
# v1.2.0 2019/09/02
- Support to turn off/on data reporting
- Support pause/continue data reporting
- Supports lightweight instances
- Fix 2019.2.1f version setting network type failure
- Fix timeEvent inaccuracy
- Android/iOS SDK upgrade to 2.1.0
# v1.1.0 2019/08/09
- Support for obtaining device ID
- Support dynamic public attributes
- Support installation event collection
- Embedded Android SDK upgraded to 2.0.2
- Embedded iOS SDK upgraded to 2.0.1
- Support the report caching option, users can choose to actively call
StartTrack ()
to start reporting
# v1.0.0 2019/06/20
- Supports settings for Visitor ID and User Account
- Support event and user feature reporting
- Supports automatic reporting of
ta_app_start
andta_app_end
events - Support public property interface
- Support
timeEvent
interface - Support multi-project reporting