Unity SDK 文檔
1.SDK 集成#
1.1.系統要求#
適用於 Unity 開發的遊戲，支持.NET 3.x 及以上、Android 5.0 及以上的系統版本、iOS 9.0 及以上的系統版本。
Unity SDK 中包含的 Android SDK 目前沒有使用到 API 19 以上的特性，可以在 AndroidManifest 中添加 <uses-sdk tools:overrideLibrary="com.tds.tapdb"/> 覆蓋 minSdkVersion，但仍然建議盡快提高 minSdkVersion 到 20 以上。
1.2.導入 SDK#
請下載最新的 SDK，將 TapDB.unitypackage 導入到 Unity 工程中。
注意：Unity SDK 中的 Android TapDB SDK 支持獲取 OAID (需要手動添加 OAID 的 SDK)，使歸因更加精準
當前支持 OAID SDK 1.0.5 ~ 1.0.25 版本，當集成 OAID SDK 後，TapDB SDK 會自動獲取 OAID 並進行上報。OAID SDK 可以自行從 OAID 官網下載，也可以從此處下載OAID 1.0.25。
1.3.各平台配置#
iOS 添加依賴
需要為導出的 Xcode 工程引入下列依賴的框架或庫
| 名詞 | 含義 | 備註 |
|---|---|---|
| AdSupport.framework | 用來獲取設備廣告標識，跟踪設備 | |
| AdService.framework | 廣告框架 | optional |
| AppTrackingTransparency.framework | iOS 14 新增 app 追踪框架（若無需在 iOS 14 以上追踪 IDFA 可不添加該依賴） | optional |
| SystemConfiguration.framework | ||
| CoreMotion.framework | ||
| Security.framework | 用來持久化存儲設備 ID | |
| libc++.tdb | ||
| libresolv.tbd | ||
| libz.tbd | ||
| libsqlite3.0.tbd |
Android 配置 AndroidManifest.xml 權限
<!--必选权限--><uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!--强烈建议 SDK 获取 IMEI 时会需要此权限；获取不到不影响功能正常使用，IMEI 用于辅助数据分析、广告归因，使统计结果更加精确--> <uses-permission android:name="android.permission.READ_PHONE_STATE" />1.4.初始化#
注意：Unity TapDB SDK 中的 iOS SDK 默認不會收集廣告標識符（IDFA），若需要對 IDFA 進行收集，請在初始化前調用以下接口並在info.plist 中配置NSUserTrackingUsageDescription 及描述文案，如「請允許 xxx 獲取並使用你的 IDFA ，來為你提供更好的服務。」
TapDB.enableAdvertiserIDCollection(true);初始化 TapDB SDK 並上報一個設備登錄（ device_login ）事件，調用這個接口是使用其它接口的先決條件，需要儘早調用。
public static void onStart(string appId, string channel, string gameVersion);public static void onStartWithProperties(string appId, string channel, string gameVersion,Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| appId | 否 | 創建遊戲時獲得的 APPID |
| channel | 是 | 分包渠道 |
| version | 是 | 遊戲版本，為空時，自動獲取遊戲安裝包的版本 |
| properties | 是 | 設備登錄（ device_login ）的事件屬性，可以傳入預置屬性覆蓋 SDK 的默認取值，也可以傳入在後台配置過的自定義屬性 |
2.設置賬號#
2.1.設置賬號 ID#
當用戶進行賬號登錄時，可調用設置賬號 ID （ setUser ）接口在記錄該賬號 ID。調用後會上報一個賬號登錄（ user_login ）事件，並將這個設備的是否有用戶註冊過（ has_user ） 屬性置為true。在重啟應用或調用清除賬號 ID （ clearUser ） 前，上報的事件都會帶有該賬號 ID。
public static void setUser(string userId)public static void setUserWithProperties(string userId,Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| userId | 否 | 長度大於 0 並小於等於 256。只能包含數字、大小寫字母、下劃線(_)、橫線(-)，用戶 ID。不同用戶需要保證 ID 的唯一性 |
| properties | 是 | 賬號登錄（ user_login ）的事件屬性 |
2.2.清除賬號 ID#
當用戶進行登出時，可調用 clearUser 清除當前 SDK 中保存賬號 ID，後續上報的事件將不會帶有賬號 ID，調用該接口不會上報任何事件。
public static void clearUser()2.3.設置賬號名稱#
在用戶進行賬號登錄後，可調用該接口設置該賬號的名稱，調用後將更新賬號的賬號名稱（ user_name ）屬性。
public static void setName(string name)| 字段 | 可為空 | 說明 |
|---|---|---|
| name | 否 | 長度大於 0 並小於等於 256，賬號名 |
2.4.設置賬號等級#
在用戶進行賬號登錄後，可調用該接口設置該賬號的等級，調用將更新賬號的賬號等級（ level ）屬性。
public static void setLevel(int level)| 字段 | 可為空 | 說明 |
|---|---|---|
| level | 否 | 賬號等級 |
2.5.設置賬號區服#
在用戶進行賬號登錄後，可調用該接口設置該賬號的區服信息，調用將初始化賬號的首次區服（ first_server ）屬性、更新賬號的當前區服（ current_server ）屬性。
public static void setServer(string server)| 字段 | 可為空 | 說明 |
|---|---|---|
| server | 否 | 賬號服務器 |
3.上報充值#
在用戶進行充值後，可調用該接口上報充值信息，調用後將上報charge 事件，並將傳入的參數作為事件的屬性。
public static void onChargeSuccess(string orderId, string product, Int32 amount, string currencyType, string payment)| 字段 | 可為空 | 說明 |
|---|---|---|
| orderId | 否 | 訂單 ID |
| product | 是 | 產品名稱 |
| amount | 否 | 充值金額（單位分，即無論什麼幣種，都需要乘以 100） |
| currencyType | 是 | 貨幣類型，參考：人民幣 CNY，美元 USD；歐元 EUR |
| payment | 是 | 支付方式，如：支付寶 |
| properties | 是 | 充值（ charge ）的事件屬性 |
注意:在條件允許的情況下推薦使用服務端充值統計接口，請參考服務端接入文檔
4.上報事件#
4.1.上報事件#
在 SDK 初始化完成後可使用該接口上報事件
public static void trackEvent(string eventName, Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| eventName | 否 | 事件的名稱 |
| properties | 是 | 事件的屬性 |
注意:
- 事件名支持上報預置事件和自定義事件，其中自定義事件應以
#開頭 - 事件屬性的 key 值為屬性的名稱，支持 string 類型
- 事件屬性的 value 值為屬性的名稱，支持 string（
256）、數值（取值區間為[-9E15， 9E15]）類型 - 事件屬性支持上報預置屬性和自定屬性，其中自定義屬性應以
#開頭 - 事件屬性傳入預置屬性時，SDK 默認採集的預置屬性將被覆蓋
4.2.設置通用事件屬性#
對於一些所有事件都要攜帶的屬性，建議使用通用事件屬性實現。
添加靜態通用事件屬性
public static void registerStaticProperties(Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| properties | 否 | 靜態通用事件屬性字典 |
示例：
//當設置了靜態通用事件屬性#current_channel，值固定為 TapDB 後Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("#current_channel", "TapDB");TapDB.registerStaticProperties(properties);
//使用事件上報時[TapDB trackEvent:@"#customEventName" withProperties:@{@"#customPropertyName":@"customPropertyValue")}];
//等效於在事件屬性中添加了#current_channel，即Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("#customPropertyName", "customPropertyValue");TapDB.trackEvent("#customEventName", custom);刪除單個靜態通用事件屬性
public static void unregisterStaticProperty(string propertyName)| 字段 | 可為空 | 說明 |
|---|---|---|
| propertyName | 否 | 靜態通用屬性名 |
清空全部靜態通用屬性
public static void clearStaticProperties()註冊動態通用事件屬性
Unity SDK 暫不支持
注意:
- 在上報事件或通用屬性中使用相同屬性名會出現屬性覆蓋的現象，屬性覆蓋的優先級從高到低依次為：事件屬性、動態通用事件屬性、靜態通用事件屬性、預置屬性（例如
trackEvent中設置的事件屬性將覆蓋動態通用事件屬性、靜態通用事件屬性、預置屬性中的同名屬性）
5.修改用戶屬性#
TapDB 支持兩種用戶模型：設備和賬號，你可以通過如下接口對這兩種用戶的屬性進行操作。
設備屬性更新操作
對於常規的用設備屬性，可使用改接口進行賦值操作，新的屬性值將會直接覆蓋舊的屬性值
public static void deviceUpdate(Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| properties | 否 | 屬性字典 |
例如:
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("currentPoints", 10);TapDB.deviceUpdate(properties);// 此時設備表的"currentPoints" 字段值為 10
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("currentPoints", 42);TapDB.deviceUpdate(properties);// 此時設備表的"currentPoints" 字段值為 42 設備屬性初始化操作
對於需要保證只有首次設置時有效的屬性，可以使用該接口進行賦值操作，僅當前值為空時賦值操作才會生效，如當前值不為空，則賦值操作會被忽略。
public static void deviceInitialize(Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| properties | 否 | 屬性字典 |
例如： 記錄用戶首次登陸的區服，客戶端無法得知該屬性是否已經被設置過，使用該接口保證僅第一次的設置會生效。
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("firstActiveServer", "server1");TapDB.deviceInitialize(properties);// 此時設備表的"#firstActiveServer" 字段值為"server1"
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("firstActiveServer", "server2");TapDB.deviceInitialize(properties);// 此時設備表的"#firstActiveServer" 字段值還是為"server1" 設備屬性累加操作
對於數值類型的屬性，可以使用該接口進行累加操作，調用後 TapDB 將對原屬性值進行累加後保存結果值
public static void deviceAdd(Dictionary<string, object> properties)| 字段 | 可為空 | 說明 |
|---|---|---|
| properties | 否 | 屬性字典，value 僅支持數值類型 |
例如：
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("totalPoints", 10);TapDB.deviceInitialize(properties);// 此時設備表的"totalPoints" 字段值為 10
Dictionary<string, object> properties = new Dictionary<string, object>();properties.Add("totalPoints", -2);TapDB.deviceInitialize(properties);// 此時設備表的"totalPoints" 字段值為 8
賬號屬性更新操作
使用方法同設備屬性更新操作
public static void userUpdate(Dictionary<string, object> properties)賬號屬性初始化操作
public static void userInitialize(Dictionary<string, object> properties)賬號屬性累加操作
使用方法同設備屬性累加操作
public static void userAdd(Dictionary<string, object> properties)