Skip to main content
Version: v4

Client Integration

Introduction​

TapSDK provides an API for game developers to collect account data. The system collects and analyzes account data to generate data reports, helping game developers analyze account behavior and optimize games.

Preparation Before Integration​

  1. Refer to Getting Ready to create an application and enable data analysis services;

Environment Requirements​

  • Unity 2019.4 or later
  • iOS 11 or later, Xcode version 16 or later
  • Android 5.0 (API level 21) or later

Permission Description​

The module requires the following permissions:

PermissionPurposeTiming of Permission Request
Get Network StatusTo check if the current network connection is validPermission is requested when the user first uses the feature
Network State PermissionTo check the network connection status (such as whether Wi-Fi or mobile data is available)Permission is requested when the user first uses the feature

For optional permissions, the SDK will not proactively request them and will only access the corresponding data if the user has granted the permission. Developers need to decide whether to request these permissions.

The module will add the following permissions to the application:

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

SDK Integration​

Please refer to Quick Start to complete the SDK basic dependency configuration for the corresponding platform

info

If you have used TapSDK's data analysis feature with version <3.6.3, and the region was set to International (IO) during initialization, you need to migrate the data before upgrading the SDK to version >=3.6.3. Please submit a ticket to contact us for data migration before upgrading.

Additional Initialization Configuration​

Before calling business interfaces, developers need to call the initialization interface to complete the application information configuration. You can also configure game package properties and current device information for event reporting. The specific usage is as follows:

using TapSDK.Core;

// Core configuration
TapTapSdkOptions coreOptions = new TapTapSdkOptions
{
    // Client ID, obtained from the developer backend
    clientId = "clientId",
    // Client Token, obtained from the developer backend
    clientToken = "clientToken",
    // Region, CN for domestic, Overseas for abroad
    region = TapTapRegionType.Overseas

};

// Data analysis related configuration
TapTapEventOptions eventOptions =  new TapTapEventOptions
{
    // Channel, such as AppStore, GooglePlay
    channel = "AppStore",
    // Custom parameters passed during initialization, will be reported in the device_login event
    propertiesJson = "{\"device_login_custom_key\": \"Data passed during initialization, will be reported in the device_login event\"}",
    // Whether to override built-in parameters, default is false
    overrideBuiltInParameters = false,
    // Whether to enable automatic reporting of IAP events
    enableAutoIAPEvent = true,
    // Whether to disable automatic device login event reporting, default is false, only effective on Android
    disableAutoLogDeviceLogin = false,
    // CAID, only for domestic iOS
    caid = "000-000-0000-00000",
    // Whether to enable advertiser ID collection, default is false
    enableAdvertiserIDCollection = true,
    // OAID certificate, only for Android, used to report OAID, only effective for [TapTapRegion.CN]
    oaidCert = "",
    // Whether to disable OAID reflection, default is true
    disableReflectionOAID = true
};


TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
    eventOptions,
};
TapTapSDK.Init(coreOptions, otherOptions);

Related parameter descriptions:

FieldNullableDescription
channelYesChannel, such as AppStore, GooglePlay
propertiesJsonYesCustom parameters reported in the device_login event
overrideBuiltInParametersYesWhether to override built-in parameters, default is false
enableAutoIAPEventYesWhether to enable automatic reporting of IAP events, default is true
disableAutoLogDeviceLoginYesWhether to disable automatic device login event reporting, Android only, default is false
caidYesCAID, only for domestic iOS
oaidCertYesOAID certificate, Android only, used to report OAID, only effective for domestic
disableReflectionOAIDYesWhether to disable OAID reflection, Android only, default is true
enableAdvertiserIDCollectionYesWhether to enable advertiser ID (IDFA) collection, iOS only, default is false, enable requires adding project configuration

Set Account​

Set Account ID​

Call this API to record an account when the account logs in.

After calling, an account login (user_login) event will be reported, and the has_user attribute of this device will be set to true.

Before restarting the application or calling clear account ID (clearUser), events reported will carry this account ID.

FieldNullableDescription
userIdNoA unique string for the account, with a length of no more than 160, can only contain numbers, uppercase and lowercase letters, underscores (_), hyphens (-), plus signs (+), forward slashes (/), equal signs (=), periods (.), commas (,), colons (:). Developers need to ensure that userId is different for different accounts.
propertiesYesEvent properties for account login (user_login)
using TapSDK.Core

// Custom properties
var dict = new Dictionary<string, string>();
dict.Add(key, value);
dict.Add(key2, value2);
string properties = dict.toJson();

// Set User ID and account login event properties
TapTapEvent.SetUserID(userId, properties);

Clear Account ID​

When the user logs out, you can call clearUser to clear the account ID saved in the current SDK. Subsequent reported events will not carry the account ID, and calling this interface will not report any events.

using TapSDK.Core

TapTapEvent.ClearUser();

Report Recharge Records​

tip

After integrating TapPayments, there is no need to manually report TapPayments recharge data to avoid duplicate statistics.

After a user recharges, you can call this interface to report recharge information. After calling, a charge event will be reported, and the parameters passed will be used as the event's properties.

using TapSDK.Core

TapTapEvent.LogPurchasedEvent(
   orderID: orderID,
   productName: productName,
   amount: amount,
   currencyType: currencyType,
   paymentMethod: paymentMethod,
   properties: properties
);
FieldNullableDescription
orderIDNoOrder ID
productNameNoProduct Name
amountNoRecharge amount (in cents, regardless of currency, multiply by 100)
currencyTypeNoCurrency type, following ISO 4217 standard. Reference: CNY for RMB, USD for US dollars, EUR for Euros
paymentMethodNoPayment method, such as Alipay
propertiesNoEvent properties for recharge (charge)

Note: It is recommended to use the server-side recharge statistics interface when possible. Please refer to [Server-side Integration Document](/sdk/tapdb/sdk/server-side-integration#2.2.Report Recharge Records)

Custom Events​

Report Event​

After SDK initialization is complete, you can use this interface to report events.

using TapSDK.Core

var dict = new Dictionary<string, string>
{
  { key, value },
  { key2, value2 }
};
string properties = dict.toJson();
TapTapEvent.LogEvent(name, properties);
FieldNullableDescription
nameNoEvent Name
propertiesNoEvent properties JSONString

Note:

  • Event names support reporting preset events and custom events, where custom events should start with #
  • The key value of the event properties is the name of the property, supporting NSString type
  • The value of the event properties is the name of the property, supporting NSString (maximum length 256), NSNumber (value range is [-9E15, 9E15]) types
  • Event properties support reporting preset attributes and custom attributes, where custom attributes should start with #
  • When passing preset attributes to event properties, the default collected preset attributes of the SDK will not be overridden. This can be controlled by modifying the configuration overrideBuiltInParameters during initialization.

Set Universal Event Properties​

For properties that all events need to carry, it is recommended to use universal event properties.

Add Static Universal Event Properties​

using TapSDK.Core

// Add a single property
var key = kv["key"];
var value = kv["value"];
TapTapEvent.AddCommonProperty(key, value);

// Add multiple properties
var key = kv["key"];
var value = kv["value"];
var key2 = kv["key2"];
var value2 = kv["value2"];
var dict = new Dictionary<string, string>
{
  { key, value },
  { key2, value2 }
};
string properties = dict.toJson();
TapTapEvent.AddCommon(properties);
FieldNullableDescription
propertiesNoEvent properties JSONString

Delete Part of Static Universal Event Properties​

using TapSDK.Core

// Delete a single property
TapTapEvent.ClearCommonProperty(key);

// Delete multiple properties
var key1 = kv["key"];
var key2 = kv["value"];
var keysToClear = new string[] { key1, key2 };
TapTapEvent.ClearCommonProperties(keysToClear);

Clear All Static Universal Properties​

using TapSDK.Core

TapTapEvent.ClearAllCommonProperties();

Register Dynamic Universal Event Properties​

For universal event properties that may change at any time, you can register dynamic universal event property callbacks. This callback will be triggered every time it is called, and the calculated properties will be added to the event properties reported this time.

using TapSDK.Core;

// Subsequent reported events will carry the #currentTime property, whose value is the value of the variable currentTime at the time of event reporting
TapTapEvent.RegisterDynamicProperties(() =>
{
    string currentTime = DateTime.Now.ToString("o");
    Debug.Log("RegisterDynamicProperties currentTime" + currentTime);
    return $"{{ \"currentTime\": \"{currentTime}\" }}";
});

Note:

When using the same property name in reported events or universal properties, there will be a phenomenon of property overwriting. The priority of property overwriting from high to low is: event properties, dynamic universal event properties, static universal event properties, preset properties (for example, the event properties set in trackEvent will overwrite the same-name properties in dynamic universal event properties, static universal event properties, and preset properties).

Modify User Properties​

TapDB supports two types of user entities: devices and accounts. You can use the following interfaces to operate on the properties of these two types of users.

Modify Device Properties​

Device Property Initialization​

For properties that need to be effective only when set for the first time, you can use this interface to perform assignment operations. The assignment operation will only be effective if the current value is empty. If the current value is not empty, the assignment operation will be ignored.

using TapSDK.Core;

string properties = "{\"firstActiveServer\":\"server1\"}";
TapTapEvent.DeviceInitialize(properties);
// At this time, the value of the "#firstActiveServer" field in the device table is "server1"

string properties2 = "{\"firstActiveServer\":\"server2\"}";
TapTapEvent.DeviceInitialize(properties2);
// At this time, the value of the "#firstActiveServer" field in the device table is still "server1"

Device Property Update​

For regular device properties, you can use this interface to perform assignment operations. The new property value will directly overwrite the old property value.


using TapSDK.Core;

string properties = "{\"currentPoints\":10}";
TapTapEvent.DeviceUpdate(properties);
// At this time, the value of the "currentPoints" field in the device table is 10

properties = "{\"currentPoints\":42}";
TapTapEvent.DeviceUpdate(properties);
// At this time, the value of the "currentPoints" field in the device table is 42

Device Property Accumulation​

For numerical properties, you can use this interface to perform accumulation operations. After calling, TapDB will save the result value after accumulating the original property value.

using TapSDK.Core;

string properties = "{\"totalPoints\":10}";
TapTapEvent.DeviceAdd(properties);
// At this time, the value of the "totalPoints" field in the device table is 10

properties = "{\"totalPoints\":-2}";
TapTapEvent.DeviceAdd(properties);
// At this time, the value of the "totalPoints" field in the device table is 8

In the above code examples, the property value is an integer. Accumulation operations also support floating-point numbers, but floating-point addition has precision issues, and developers should be aware of this.

Modify Account Properties​

Account Property Initialization​

The usage is the same as the device property initialization operation.

using TapSDK.Core;

string properties = "{\"firstActive\":\"active\"}";
TapTapEvent.UserInitialize(properties);

Account Property Update​

The usage is the same as the device property update operation.

using TapSDK.Core;

string properties = "{\"firstActive\":\"activeNew\"}";
TapTapEvent.UserUpdate(properties);

Account Property Accumulation​

The usage is the same as the device property accumulation operation.

using TapSDK.Core;

string properties = "{\"conut\":1}";
TapTapEvent.UserAdd(properties);

Collect Device Fingerprint​

Allow the SDK to collect device fingerprints for auxiliary data analysis and advertising attribution, which will make the statistical results more accurate.

info

Please initialize the SDK after permission requests, setting IDFA switches, and other operations to ensure that device fingerprints can be reported normally.

We strongly recommend that developers use the manual OAID setting method instead of relying on SDK automatic retrieval. This avoids OAID-related compatibility issues and improves stability and performance. The setup method is as follows:

  1. Disable related automatic features during initialization:

    • Set disableReflectionOAID = true to disable reflection-based OAID retrieval (default is true)
    • Set disableAutoLogDeviceLogin = true to disable automatic device login event reporting (default is false)

  2. Manually call the relevant APIs to complete the setup:

using TapSDK.Core

// Manually set OAID (Android platform only)
TapTapEvent.SetOAID("your_oaid_value");

// Manually report device login event
TapTapEvent.LogDeviceLoginEvent();

OAID Auto Retrieval (Android Deprecated)​

Note: To improve compatibility and performance, the SDK has disabled automatic OAID retrieval by default (disableReflectionOAID = true). We strongly recommend using the "Manually Set OAID" approach. If you still need to use automatic OAID retrieval, you can enable it by setting disableReflectionOAID = false during initialization, but be aware that this may cause compatibility issues.

SDK version 3.28.2 and above supports OAID version 1.0.5 ~ 2.4.0; 3.15.0 ~ 3.28.0 supports OAID version 1.0.5 ~ 2.1.0; 3.14.0 and below supports OAID version 1.0.5 ~ 1.0.25

When the TapDB SDK integrates the OAID third-party library, it will carry this parameter (key is device_id4) when sending related events. The currently supported version of the third-party library is 1.0.5 ~ 2.4.0. Due to significant changes in different versions, the instructions for integration for different versions are as follows:

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

For version 1.0.26 ~ 2.4.0, in addition to adding the corresponding third-party library, the following processing is required:

1. Set Certificate Information and Configuration File​

The certificate information is the content of the .cert.pem file applied by the application through the Mobile Security Alliance email [email protected], and this file corresponds to the package name. Currently, two settings are supported:

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

Choose one of the above two methods. When both are used at the same time, the certificate information set through the interface takes precedence.

The configuration file is supplierconfig.json. The application needs to modify the content corresponding to the internal appid to the application ID of the application in the corresponding app store, and other parts do not need to be modified. Copy the modified file to the assets directory.

2. Load the Corresponding Library File in the Application Project​

The library file names corresponding to different versions of the OAID third-party library are as follows:

VersionLibrary Name
1.0.30 ~ 2.4.0msaoaidsec
1.0.29nllvm1632808251147706677
1.0.27nllvm1630571663641560568
1.0.26nllvm1623827671

Add the code to load the third-party library in the onCreate method of the custom Application class in the Android project. For example, when the application integrates OAID version 1.2.1, it is as follows:

System.loadLibrary("msaoaidsec");

Common Problem Handling​

When the OAID library is introduced in the project, but the device OAID information is still not found during reporting, check the following items:

  1. Is the device time normal?
  2. For version 1.0.26 and above, is the package name corresponding to the certificate consistent with the current package name?
  3. For version 1.0.26 and above, is the library file loaded, and is the library file name consistent with the version?
  4. If the application reports an error java.lang.UnsatisfiedLinkError on Android 12 and the application's minSdkVersion is greater than or equal to 23, it is recommended to add android:extractNativeLibs="true" to the application tag in the AndroidManifest.xml file.

IMEI (Android)​

Add the following entry to AndroidManifest.xml, and after the user agrees to the permission request, the SDK will automatically collect the Android IMEI.


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

IDFA (iOS)​

Since obtaining IDFA requires a pop-up window for user confirmation on systems above iOS14.5, the SDK does not obtain IDFA by default. You can enable IDFA acquisition by calling the interface.

Ensure that the permission request description text is added to info.plist, and the SDK will automatically pop up the permission request window during initialization.

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

Set enableAdvertiserIDCollection in TapTapSdkOptions to true during initialization to enable the IDFA acquisition switch.