Skip to main content

Client Integration Guides

Introduction​

TapSDK provides an API for game developers to collect account data. The system will collect and analyze the account data, and eventually form a data report to help game developers analyze account behavior and optimize the game.

Please download TapSDK and add the relevant dependencies.

If you only need to use TapDB alone, you can import only the dependencies common and tapdb.

For Unity v3.7.1 and higher, you also need to import com.leancloud.storage.

"dependencies":{
    "com.taptap.tds.login":"https://github.com/TapTap/TapLogin-Unity.git#3.29.3",
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.29.3",
    "com.taptap.tds.bootstrap":"https://github.com/TapTap/TapBootstrap-Unity.git#3.29.3",
    "com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-2.3.0",
    "com.leancloud.storage": "https://github.com/leancloud/csharp-sdk-upm.git#storage-2.3.0",
    // Data analysis
    "com.taptap.tds.tapdb": "https://github.com/TapTap/TapDB-Unity.git#3.29.3",
}
info

If you were using a version of TapDB lower than 3.6.3 and the region selected for initialization was International (IO), then upgrading the SDK to 3.6.3 and higher will require migrating the data first.Please submit a ticket to contact us to migrate the data.

Initialize SDK​

Initialize the SDK and report a device login (device_login) event, access to this interface is a pre-requisite for using other interfaces and needs to be called early.

info

Depending on your use case, either of the following initialization options is acceptable.

Initialize TapSDK​

Synchronize the initialization of TapDB during TapSDK initialization.

using TapTap.Bootstrap; 

var config = new TapConfig.Builder()
    .ClientID("your_client_id")  // (Required) Client ID in the Developer Center.
    .ClientToken("your_client_token")  // (Required) Client Token in the Developer Center.
    .ServerURL("https://your_server_url")  // (Required) Developer Center > Your Game > Game Services > Configuration > Domain > API
    .RegionType(RegionType.IO)  // (Optional) CN for Mainland China; IO for international.
    .TapDBConfig(true, "gameChannel", "gameVersion", true)  // TapDB is automatically initialized based on the configuration of TapConfig.

    .ConfigBuilder();

TapBootstrap.Init(config);

TapDBConfig descriptions：

public Builder TapDBConfig(bool enable, string channel, string gameVersion, bool advertiserIDCollectionEnabled)
ParameterCan be nullDescriptions
enableNoWhether to open TapDB service.
channelYesSubcontracting channels, length not greater than 256.
versionYesGame version, when empty, automatically obtains the version of the game installation package. The length is not greater than 256.
advertiserIDCollectionEnabledNoIDFA switch, please refer to the Collect Device Fingerprint documentation.

TapDB Only​

When only using the TapDB without using the login functionality and without importing the TapBootstrap package, TapDB can be initialized as follows:

public static void Init(string clientId, string channel, string gameVersion, bool isCN)

TapDB.Init("clientId", "taptap", "gameVersion", false);
ParameterCan be nullDescriptions
clientIdNoClient ID in the Developer Center.
channelYesSubcontracting channels.
versionYesGame version, when empty, automatically obtains the version of the game installation package.
isCNYestrue: Chaina，false: Other countries or regions.

User Setting​

Set User ID​

This API records an account when it is called to log in an account. After calling, a user login (user_login) event will be reported, and the "has_user" attribute of the device will be set to true. Before restarting the app or calling clear User, the reported events will all have the account ID.

public static void SetUser(string userId)

TapDB.SetUser("userId");
ParameterCan be nullDescriptions
userIdNoThe unique string of the account, the string length is not greater than 256, and can only contain numbers, capital and lower case letters, underscores (_), and dashes (-). Developers need to ensure that the userId of different accounts are not the same.

Clear User ID​

Once the user logout, you can call clearUser to clear the account ID saved in the current SDK, subsequent events reported will not have the account ID, and no events will be reported by calling this interface.

public static void ClearUser()

TapDB.ClearUser();

Set User Name​

Once the user logs in, this interface can be called to set the user name, which will update the user name property (user_name).

public static void SetName(string name)

TapDB.SetName("Tarara");
ParameterCan be nullDescriptions
nameNoUser name. Length greater than 0 and less than or equal to 256.

Set User Level​

Once the user logs in, this interface can be called to set the user level, which will update the user level property ( user_name ).

public static void SetLevel(int level)

TapDB.SetLevel(5);
ParameterCan be nullDescriptions
levelNoUser level.

Set User Server​

Once the user logs in, this interface can be called to set the user server, which will update the user server properties (first_server and current_server).

public static void SetServer(string server)

TapDB.SetServer("1 Server");
ParameterCan be nullDescriptions
serverNoUser server.

Report Charge​

This interface can be called to report charge information after a user has made a charge. After the call, the charge event will be reported and the incoming parameters will be used as properties of the event.

public static void OnCharge(string orderId, string product, long amount, string currencyType, string payment)

public static void OnCharge(string orderId, string product, long amount, string currencyType, string payment,
            string properties)

TapDB.OnCharge("0xueiEns", "game name", "100", "CNY", "wechat", "{\"on_sell\":true}");
ParameterCan be nullDescriptions
orderIdNoOrder ID
productYesProduct name
amountNoCharge amount
currencyTypeYesCurrency type, following ISO 4217 standard. Reference: CNY; USD; EUR
paymentYesPayment method
propertiesYesThe charge event properties

Tips:It is recommended to use the server-side recharge statistics interface under conditions that permit it. Please refer to the server-side integration documentation.

Custom Events​

Report Events​

This interface can be used to report events after the SDK has been initialized:

public static void TrackEvent(string eventName, string properties)

TapDB.TrackEvent("eventName", "{\"weapon\":\"axe\"}");
ParameterCan be nullDescriptions
eventNameNoEvent name
propertiesYesEvent properties

Tips:

  • The eventName supports reporting of preset events and custom events, where custom events should start with #.
  • The key of the event property supports NSString type.
  • The value of the event property supports NSString (maximum length 256) and NSNumber (range of values [-9E15, 9E15]) types.
  • The event property supports reporting of preset properties and custom properties, where custom properties should start with #.
  • When passing in preset properties for the event properties, the preset properties collected by default by the SDK will be overwritten.

Sets Generic Event Properties​

For properties that need to be carried for all events, it is recommended to use a generic event property implementation.

Add Static Generic Event Properties​

public static void RegisterStaticProperties(string staticProperties)

//When the static generic event property `#current_channel` is set to `TapDB`, using event reporting is equivalent to adding a `#current_channel` to the event property.
string properties = "{\"#current_channel\":\"TapDB\"}";
TapDB.RegisterStaticProperties(properties);
ParameterCan be nullDescriptions
staticPropertiesNoStatic generic event property dictionary

Delete A Single Static Generic Event Property​

public static void UnregisterStaticProperty(string propertyName)

TapDB.UnregisterStaticProperty("#current_channel");
ParameterCan be nullDescriptions
propertyNameNoStatic generic event property name

Delete All Static Generic Event Properties​

public static void ClearStaticProperties()

TapDB.ClearStaticProperties();

Register Dynamic Generic Event Properties​

For generic event properties that may change at any time. You can register a dynamic generic event property callback to add the calculated property to this reported event property.

public static void RegisterDynamicProperties(IDynamicProperties properties)

// All subsequent events will carry the #currentLevel property, which contains the value of level at the time the event was reported.
public class TapDBDynamicPropertiesImpl : IDynamicProperties
{
        public Dictionary<string, object> GetDynamicProperties()
        {
                Dictionary<string, object> dic = new Dictionary<string, object>();
                dic["#currentLevel"] = level;
                return dic;
        }
}
TapDB.RegisterDynamicProperties(new TapDBDynamicPropertiesImpl());
ParameterCan be nullDescriptions
dynamicPropertiesNoDynamic generic event properties compute callbacks

Tips:

  • Using the same property name in the reported event or generic property will result in property overwriting. The priority overwriting is from highest to lowest: event property, dynamic generic event property, static generic event property, and preset property. For example, an event property set in trackEvent will override a dynamic generic event property, a static generic event property, or a preconfigured property with the same name.

Modify User Attributes​

TapDB supports two kinds of objects: devices and accounts, and you can manipulate the properties of these two users through the following interfaces.

Modify Device Properties​

Device Property Initialization​

This interface can be used to make only the first value valid. Only if the current value is null, the assignment will take effect, if the current value is not null, the assignment will be ignored.

public static void DeviceInitialize(string properties)

string properties = "{\"firstActiveServer\":\"server1\"}";
TapDB.DeviceInitialize(properties);
// The value of "#firstActiveServer" in the device table is "server1".

string properties = "{\"firstActiveServer\":\"server2\"}";
TapDB.DeviceInitialize(properties);
// The value of "#firstActiveServer" in the device table is still "server1".
ParameterCan be nullDescriptions
propertiesNoProperties Dictionary

Device Property Updates​

For regular device properties, this interface can be used to assign values, and the new property values will directly overwrite the old ones.

public static void DeviceUpdate(string properties)

string properties = "{\"currentPoints\":10}";
TapDB.DeviceUpdate(properties);
// "currentPoints" in the device table is 10.

properties = "{\"currentPoints\":42}";
TapDB.DeviceUpdate(properties);
// "currentPoints" in the device table is 42.
ParameterCan be nullDescriptions
propertiesNoProperties dictionary

Device Property Accumulation​

Properties of numeric type can use this interface for accumulation operation, after calling TapDB will accumulate the original property value and save the result value.

public static void DeviceAdd(string properties)

string properties = "{\"totalPoints\":10}";
TapDB.DeviceAdd(properties);
// "totalPoints" in the device table is 10.


properties = "{\"totalPoints\":-2}";
TapDB.DeviceAdd(properties);
// "totalPoints" in the device table is 8.
ParameterCan be nullDescriptions
propertiesNoProperty dictionary, only supports numeric types

In the above code example, the property value is an integer. The accumulation operation also supports floating point numbers, but there is a precision problem with floating point summation, so developers need to pay attention to it.

Modify User Properties​

User Property Initialization​

Use the same method as "Device Property Initialization" operations.

public static void UserInitialize(string properties)

TapDB.UserInitialize(properties);

User Property Updates​

Use the same method as "Device Property Updates" operations.

public static void UserUpdate(string properties)

TapDB.UserUpdate(properties);

User Property Accumulation​

Use the same method as "Device Property Accumulation" operations.

public static void UserAdd(string properties)

TapDB.UserAdd(properties);

Collecting Device Fingerprints​

Allows the SDK to capture device fingerprints to aid in data analysis, ad attribution and make statistical results more accurate.

info

Please initialize the SDK after the operation such as permission application and setting IDFA switch to ensure the device fingerprint can be reported properly.

OAID（Android）​

Note: SDK version 3.15.0 and above support OAID version 1.0.5 ~ 1.2.1; 3.14.0 and below support OAID version 1.0.5 ~ 1.0.25.

TapDB SDK will carry this parameter (key is device_id4) in sending related events when the application accesses OAID third-party library. The supported versions of this third-party library are 1.0.5 ~ 1.2.1, because different versions change a lot, so the instructions for accessing different versions are as follows.

For 1.0.5 ~ 1.0.25 no additional configuration is needed, just add the dependency of the corresponding third-party library to the application.

For 1.0.26 ~ 1.2.1, in addition to adding the corresponding third-party libraries, you need to add the following processing.

1. Set certificate information and profile​

The certificate is a "cert.pem" file applied through the Mobile Security Alliance mailbox [email protected], which corresponds to the package name. Two types of settings are supported.

  1. Copy the cert.pem file to the application assets directory, and note that the file name should be set to packageName.cert.pem, packageName is the current application package name.
  2. Set the contents of the certificate file via the SDK interface setOAIDCert.

One of the two options is sufficient, and when both are used, the certificate information set through the interface is preferred.

The configuration file is' supplierconfig.json '. The application needs to change the contents corresponding to the internal appid to the application ID of the app market, and the other parts do not need to be modified.

2. Load the corresponding library file in the application project​

The library file names for different versions of OAID third-party libraries are as follows：

VersionsLibraries Name
1.0.30 ~ 1.2.1msaoaidsec
1.0.29nllvm1632808251147706677
1.0.27nllvm1630571663641560568
1.0.26nllvm1623827671

In the 'onCreate' method of the custom 'Application' class in the Android project, add the code to load third-party libraries, for example, when the application integrates OAID version 1.2.1 as follows: The library file names of different versions of OAID third-party libraries are as follows.

System.loadLibrary("msaoaidsec");

FAQ​

When the OAID library has been integrated in the project but the device OAID information is still not found when reporting, check the following items:

  1. Whether the device time is normal.
  2. For version 1.0.26 and above, does the package name of the certificate correspond to the current package name.
  3. For version 1.0.26 and above, whether the library file is loaded and whether the library file name is the same as the version.
  4. The application in Android 12 reports an error as: java.lang.UnsatisfiedLinkError, and the application minSdkVersion is greater than or equal to 23, it is recommended to add in the application tag of AndroidManifest.xml: android:extractNativeLibs="true".

IMEI（Android）​

After adding the following item in 'AndroidManifest.xml' and the user agrees to the permission application, the SDK will automatically collect the Android IMEI.

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

IDFA（iOS）​

For iOS14.5 and above, getting IDFA requires a popup window with user confirmation. SDK does not get IDFA by default, you can call the interface to enable IDFA fetching.

Please make sure the permission request description text is added to info.plist, the SDK will automatically pop up the permission request window during initialization. 

<key>NSUserTrackingUsageDescription</key>
<string>This item will be used to suggest personalized ads (or other descriptions) to you</string>

If you are using TapSDK initialization, please pass true to advertiserIDCollectionEnabled in TapDBConfig to turn on the IDFA collection switch.

If you are using TapDB SDK alone, please call the following interface to enable the IDFA acquisition switch:

TapDB.AdvertiserIDCollectionEnabled(true);

Diagnosis​

info

TapSDK 3.14.0 and above can access this feature.

The UE4 SDK does not support diagnostic access at this time.

Add Dependencies​

The SDK can be imported via Unity Package Manager or imported manually, either way.

If you choose UPM import, you can add to the project's Packages/manifest.json file.

"dependencies":{
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.29.3",
    "com.taptap.tds.tapdb": "https://github.com/TapTap/TapDB-Unity.git#3.29.3",
    "com.taptap.tds.themis": "https://github.com/taptap/TapThemis-Unity.git#3.2.3-3",
}

If you choose to import manually：

  • Find the TapSDK Unity download address on the download page, download TapSDK-UnityPackage.zip and unzip it, then import the TapTap_Common, TapTap_TapDB and TapTap_Themis modules.

Namespace​

using TapTap.TapDB;

Interface Description​

Set the log reporting level​

TapDB.ConfigAutoReportLogLevel(LogSeverity.LogError);

The default level is LogError, which will be reported automatically when the application log level is higher than the set level.

Set whether to exit on exception​

TapDB.ConfigAutoQuitApplication(true);

Set whether to exit automatically when an uncaught exception occurs.

Register Log Callback​

TapDB.RegisterLogCallback(logcallback);
public void logcallback(string condition, string statckTrace, LogType type ){

}

Register the application log Callback. Callback processing is invoked when the application outputs logs.

Remove Log Listening​

TapDB.UnRegisterLogCallback(logcallback);

Reporting Exception​

TapDB.ReportException(new Exception("crash test from unity"),"crashMessage desc");

Proactive reporting an exception.