Unity-3D SDK documentation
1 Introduction#
1.1. Scope of application#
TapDB provides a set of SDK that game developers can integrate into the game. The system collects player data, analyzes it, and finally forms a data report to help game developers analyze player behavior and optimize the game.
For games developed by Unity, Android supports 4.0 and above systems, and iOS supports 9.0 and above systems.
1.2. Noun explanation#
| Noun | meaning |
|---|---|
| Account | Corresponding to a player account, a unique identifier is required. |
| Equipment | Equipment with corresponding game installed |
| Paid | Players use real currency in exchange for game virtual coins or game props |
| Subcontracting Channels | Identifies the source of the game installation package channel, which needs to be set in the code |
2. Access method#
2.1. Application#
Register a game in the TapDB console and get the APP ID corresponding to the game. This is a 16-bit string. iOS and Android can share the same APP ID.
2.2. Import SDK into the project#
Download the latest SDK on the TapDB website, which contains a TapDB.unitypackage file, select Assets --> Import Package --> Custom Package in the Unity3D compiler, find the TapDB.unitypackage file, and click the "Open button" to import successfully.Among them, demo.cs is only the sample code, not the code required by the SDK.
2.3.Android#
2.3.1. Permission#
The SDK requires the following permissions.
| Permissions | Is it necessary | Purpose |
|---|---|---|
| android.permission.INTERNET | Yes | Permission to use the network |
| android.permission.ACCESSNETWORKSTATE | Yes | Get mobile network connection status |
| android.permission.ACCESS_WIFI_STATE | 是 | WIFI |
Optional permissions, it is strongly recommended to add.This permission is required when the SDK obtains IMEI; failure to obtain it does not affect the normal use of the function. IMEI is used to assist data analysis to make statistical results more accurate
| Permissions | Is it necessary | Purpose |
|---|---|---|
| android.permission.READ_PHONE_STATE | No | Get phone status information |
2.3.2. Third-party device ID description#
Note: Device ID will make data statistics more accurate. It is recommended to add it. TapDB SDK supports obtaining the device ID of OAID (you need to manually add the SDK of OAID). The obtained device ID will be reported to the server to assist in data analysis and make statistics. The result is more accurate, you can skip this step if you don’t need it
OAID SDK get device ID#
TapDB SDK currently supports OAID SDK 1.0.5~1.0.25 versions. When the application is integrated, it will automatically use OAID to obtain the device ID. You can download it from the OAID official website or download it from here [1.0.25](https ://res.xdcdn.net/tapdb/Android/oaid/oaid_sdk_1.0.25.aar) version [If you need other versions, please go to the OAID official website to download; then import the OAID SDK (downloaded as an aar) into the application project table of Contents
Add the following permissions in AndroidManifest.xml
<!-- 必选权限 --><uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.READ_PHONE_STATE" /><uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/><uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /><!-- 强烈建议权限 --><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />note: The SDK uses HTTP to transmit data by default. When targetSdkVersion >= 28, you need to add the following configuration in AndroidManifest.xml
<application...android:usesCleartextTraffic="true".../>2.4.iOS#
2.4.1. Permission#
If you need to collect the advertising identifier (IDFA), you can call the following interface.Please call before initialization
TapDB.enableAdvertiserIDCollection(true);Starting from iOS 14, to obtain IDFA, you need to configure a separate permission statement, configure NSUserTrackingUsageDescription and description text in info.plist.For example, please allow xxx to obtain and use your IDFA to provide you with better services.
TapDB version 2.2.3 and above, please use Xcode 12.3 or above.
| Permission Statement | Meaning |
|---|---|
| NSUserTrackingUsageDescription | Used to obtain device advertising identifiers and track devices |
The following dependent frameworks or libraries need to be introduced for the Xcode project exported by iOS
2.4.2. System dependencies#
The following dependent frameworks or libraries need to be introduced for the Xcode project
| Noun | Meaning | Remarks |
|---|---|---|
| AdSupport.framework | Used to obtain device advertising logos and track devices | |
| AdService.framework | Advertising Framework | optional |
| AppTrackingTransparency.framework | iOS14 new app tracking framework | optional |
| SystemConfiguration.framework | ||
| CoreMotion.framework | ||
| Security.framework | For better persistent storage | |
| libc++.tdb | c++ | |
| libresolv.tbd | ||
| libz.tbd | ||
| libsqlite3.0.tbd |
3. Interface description#
3.1. Initialization#
Initialize the statistics system SDK. Calling this interface is a prerequisite for using other interfaces and needs to be called as soon as possible.It is generally recommended to call it in Start() in Unity.
public static void onStart(string appId, string channel, string gameVersion);public static void onStartWithProperties(string appId, string channel, string gameVersion,Dictionary<string, object> properties)| Field | Can be empty | Description |
|---|---|---|
| appId | No | APP ID obtained when registering the game |
| channel | Yes | Subcontracting channel, as introduced in 1.2. Glossary |
| gameVersion | Yes | The game version, when it is empty, the version of the game installation package is automatically obtained (Android is the versionName in AndroidManifest.xml, and iOS is the Version in the Xcode configuration) |
| properties | No | Custom properties, upload with initialization |
3.2. Login#
Record an account and call it when the account is logged in.
public static void setUser(string userId)public static void setUserWithProperties(string userId,Dictionary<string, object> properties)| Field | Can be empty | Description |
|---|---|---|
| userId | No | The length is greater than 0 and less than or equal to 256.It can only contain numbers, uppercase and lowercase letters, underscores (_), dashes (-), and user ID.Different accounts need to ensure the uniqueness of ID |
| properties | No | custom properties |
3.3. Account name#
Set the account name.
public static void setName(string name)| Field | Can be empty | Description |
|---|---|---|
| name | No | The length is greater than 0 and less than or equal to 256, account name |
3.4. Account Level#
Set the account level, which is called when the account is logged in or upgrade.
public static void setLevel(int level)| Field | Can be empty | Description |
|---|---|---|
| level | No | account level |
3.5. Account server#
Set the account zone server, which is called when the account is logged in or when the zone server is changed.
public static void setServer(string server)| Field | Can be empty | Description |
|---|---|---|
| server | No | Account server |
3.6. Recharge#
Called when the recharge is successful
remind:Due to the behavior of the client, it is inevitable that speculators will try to crack the recharge; if the server does not pass the verification, the data will be inaccurate. It is strongly recommended to use the server interface for recharge data callback.([4.2. Recharge](#42 Recharge))
public static void onChargeSuccess(string orderId, string product, Int32 amount, string currencyType, string payment)| Field | Can be empty | Description |
|---|---|---|
| orderId | No | Order ID |
| product | yes | product name |
| amount | No | Top-up amount (unit points, that is, no matter what currency, it needs to be multiplied by 100) |
| currencyType | Yes | Currency type, reference: RMB CNY, U.S. dollar USD; Euro EUR |
| payment | yes | payment method, such as: Alipay |
3.7. Logout#
When you log out, you need to call the following interface to clear user data.
public static void clearUser()
3.8. Custom Event#
(If you need to open a custom event, please contact technical support QQ:)
Called when a custom event needs to be sent, the eventName and properties of the custom event must be pre-configured in the metadata management before it can be sent using the SDK
public static void trackEvent(string eventName, Dictionary<string, object> properties)Users can upload custom events that need to be tracked by calling the trackEvent method.eventName is the event name of the custom event, which must start with'#'. For value rules, please refer to the custom attribute registration page.properties are the custom properties included in the custom event (stored in the form of Key: Value), where Key represents the property name of the custom property, and Value represents the value of the property.It should be noted here that the naming rules of Key are the same as eventName, and also need to ensure that it starts with'#'.The currently supported Value types are String, Number, Boolean.The String type supports a maximum length of 256.The value range of Number type is [-9E15, 9E15].Take the battle incident as an example:
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("#weapon", "axe");TapDB.trackEvent("#battle", properties);| Field | Can be empty | Description |
|---|---|---|
| eventName | No | Event code, which needs to be pre-configured in the control background |
| properties | Yes | Event properties, specific fields need to be pre-configured in the control background |
3.9. Event main operation (account, device)#
The event subject of TapDB is divided into account and device, which supports related operations on a certain attribute of the subject.
Device attribute initialization operation#
/// Initialize device attribute operation/// @param properties attribute dictionarypublic static void deviceInitialize(Dictionary<string, object> properties)If you need to initialize some properties of the device, you can call deviceInitialize to set it.If the corresponding attributes have been initialized before, the subsequent initialization operations for these attributes will be ignored.Take the first active server as an example:
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("firstActiveServer", "server1");TapDB.deviceInitialize(properties);// At this time, the "firstActiveServer" field value of the device table is "server1"
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("firstActiveServer", "server2");TapDB.deviceInitialize(properties);// At this time the "firstActiveServer" field value of the device table is still "server1"Device attribute update operation#
/// Update device attribute operation/// @param properties attribute dictionarypublic static void deviceUpdate(Dictionary<string, object> properties)If you need to update some properties of the device, you can call deviceUpdate to set it.The attributes uploaded through this interface will overwrite the original attribute values.Take the current points as an example:
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("currentPoints", 10);TapDB.deviceUpdate(properties);// At this time, the "currentPoints" field value of the device table is 10
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("currentPoints", 42);TapDB.deviceUpdate(properties);// At this time the "currentPoints" field value of the device table is 42Device attribute accumulation operation#
/// Device attribute accumulation operation/// @param properties The attribute dictionary only supports numeric attributes for the time beingpublic static void deviceAdd(Dictionary<string, object> properties)Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("totalPoints", 10);TapDB.deviceInitialize(properties);// At this time, the "totalPoints" field value of the device table is 10
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("totalPoints", -2);TapDB.deviceInitialize(properties);// At this time the "totalPoints" field value of the device table is 8Account attribute initialization operation#
/// Initialize account attribute operation/// @param properties attribute dictionarypublic static void userInitialize(Dictionary<string, object> properties)Account attribute update operation#
The usage method is the same as the device attribute update operation
/// Update account attribute operation/// @param properties attribute dictionarypublic static void userUpdate(Dictionary<string, object> properties)Account attribute accumulation operation#
The use method is the same as the accumulation operation of equipment attributes
/// Account attribute accumulation operation/// @param properties The attribute dictionary only supports numeric attributes for the time beingpublic static void userAdd(Dictionary<string, object> properties)3.10. Set general event properties#
For some important attributes that need to appear in each upload event, users can set these attributes as global common custom attributes, static common attributes are fixed values, these common attributes will be uploaded to TapDB after registration. In the event.Here you need to pay attention to the attribute priority> static general attribute priority passed in trackEvent, the attribute in trackEvent will overwrite the static general attribute with the same name.
Add static event properties#
/// Add static event attributes, each event will be sent/// @param staticProperties attribute dictionarypublic static void registerStaticProperties(Dictionary<string, object> properties)Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("channel", "TapDB");TapDB.registerStaticProperties(properties);// The static property "channel" is set, and the value is fixed as "TapDB"
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("#customEvent", "axe");TapDB.trackEvent("#custom1", custom);// Use the trackEvent method to upload a custom event, the uploaded event at this time has the public property "channel" set above, and the value is "TapDB"If the value of the general property that needs to be added is relatively fixed in all events, you can call the registerStaticProperties method to register the static general property
Delete a single static event attribute#
If you want to delete an added static general property and don't want it to appear in every subsequent event, you can call the unregisterStaticProperty method to delete the unnecessary static general property.
/// Delete a static event attribute added/// @param propertyName property Keypublic static void unregisterStaticProperty(string propertyName)Delete all static event attributes#
/// Delete the added static event attributepublic static void clearStaticProperties()4. Server push interface#
4.1. Number of people online#
Since the SDK cannot push accurate online data, here is a server-side online data push interface.The game server can count the number of online users every 5 minutes and push it to TapDB through the interface.TapDB performs data summary display.
Interface: https://se.tapdb.net/tapdb/onlineMethod: POSTFormat: jsonRequired header information: Content-Type: application/jsonRequest content:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| appid | string | APP ID of the game |
| onlines | array | Multiple online data (up to 100) |
The structure of the online array is
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| server | string | server.TapDB only accepts data once every 5 minutes for the same server |
| online | int | Number of people online |
| timestamp | long | The timestamp (in seconds) of the current statistics.TapDB will align data according to natural 5 minutes |
Example:
{ "appid": "gkjasd13bbsa1sdk", "onlines": [ { "server": "s1", "online": 123, "timestamp": 1489739590 }, { "server": "s2", "online": 188, "timestamp": 1489739560 } ]}Success judgment: when the returned HTTP Code is 200, the transmission is regarded as successful, otherwise it is regarded as a failure
4.2. Recharge#
Since the SDK push may be inaccurate, here is a method of recharge and push on the server side.Need to ignore the relevant recharge push interface in the SDK.
Interface: https://e.tapdb.net/eventContent (note that you need to deal with it later):
{ "module": "GameAnalysis", // fixed parameters "ip": "8.8.8.8", // Optional.Top-up user's IP "name": "charge", // fixed parameters "index": "APPID", // required.Note that APPID needs to be replaced with TapDB's appid "identify": "userId", // required.User ID.Must be the same as the userId passed in the SDK's setUser interface, and the user has been pushed through the SDK interface "properties": { "order_id": "100000", // Optional.The length is greater than 0 and less than or equal to 256.The order ID.Pass the order ID for re-weighting to prevent multiple calculations "amount": 100, // required.Greater than 0 and less than or equal to 100000000000.Recharge amount.Unit minutes, that is, no matter what currency, you need to multiply by 100 "virtual_currency_amount": 100, //The amount of virtual currency received, must be passed, can be 0 "currency_type": "CNY", // Optional.Currency type.The internationally accepted three-letter notation, the default is CNY when it is empty.Reference: Renminbi CNY, U.S. Dollar USD; Euro EUR "product": "item1", // Optional.The length is greater than 0 and less than or equal to 256.product name "payment": "alipay" // Optional.The length is greater than 0 and less than or equal to 256.Recharge channels }}Suppose the appid of the game is abcd1234.After constructing the json string, remove the spaces and line breaks, and then perform urlencode again.Push the result as POST data First replace the line breaks and spaces to become:
{"module":"GameAnalysis","name":"charge","index":"abcd1234","identify":"user_id","properties":{"order_id":"100000","amount":100,"virtual_currency_amount":100,"currency_type":"CNY","product":"item1","payment":"alipay"}}
Then urlencode becomes the following form.Some versions of urlencode may encode : and ,, which will not affect actual use.
%7B%22module%22:%22GameAnalysis%22,%22name%22:%22charge%22,%22index%22:%22abcd1234%22,%22identify%22:%22user_id%22,%22properties%22:%7B%22order_id%22:%22100000%22,%22amount%22:100,%22virtual_currency_amount%22:100,%22currency_type%22:%22CNY%22,%22product%22:%22item1%22,%22payment%22:%22alipay%22%7D%7D
Success judgment: when the returned HTTP Code is 200, the transmission is regarded as successful, otherwise it is regarded as a failure