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.

Environment Requirements​

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

Permission Description​

Preparation Before Integration​

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

SDK Integration​

Please download TapSDK and add the relevant dependencies.

If you only need to use TapEvent separately, you can import the dependency com.taptap.sdk.core.

External Dependency Integration​

The SDK internally uses some third-party libraries. Developers need to ensure that the external dependencies are properly integrated before using the SDK. The specific settings are as follows:

  1. The SDK uses the Newtonsoft-json library for JSON parsing. If this dependency is already integrated in the current project, no additional handling is needed. Otherwise, add the following dependency to Packages/manifest.json:
"com.unity.nuget.newtonsoft-json":"3.2.1"
  1. The SDK uses com.google.external-dependency-manager to manage Android and iOS dependencies. If this dependency is already integrated in the current project, no additional handling is needed. Otherwise, add the following dependency to Packages/manifest.json:
{
   "dependencies": {
      "com.google.external-dependency-manager": "1.2.179"
   },
   "scopedRegistries": [
      {
         "name": "package.openupm.com",
         "url": "https://package.openupm.com",
         "scopes": [
            "com.google.external-dependency-manager"
         ]
      }
  ]
}

Adding SDK Dependencies​

The SDK supports integration through Unity Package Manager and local file imports. Developers can choose one of these methods based on their needs, with remote dependencies being recommended.

Remote Dependency​

The SDK can be integrated via NPMJS or GitHub. Developers can choose one of these methods.

1. NPMJS Integration​

Add the following dependencies in the project's Packages/manifest.json file:

"dependencies":{
  "com.taptap.sdk.core":"4.5.4",
}

Note that you need to declare scopedRegistries at the same level as dependencies in Packages/manifest.json:

"scopedRegistries":[
  {
    "name": "NPMJS",
    "url": "https://registry.npmjs.org/",
    "scopes": ["com.taptap"]
  }
]
2. GitHub Integration​

Add the following dependencies in the project's Packages/manifest.json file:

"dependencies":{
 "com.taptap.sdk.core":"https://github.com/taptap/TapSDKCore-Unity.git#4.5.4",
}

In Unity's top menu, select Window > Package Manager to view packages installed in the project.

Local File Import​

  1. Download the corresponding unitypackage files for the modules from the Download Page and import them into the Unity project through Assets > Import Packages > Custom Packages, including:
  • TapSDK_Core.unitypackage TapSDK Core Library, Mandatory。
  1. If the current project has already integrated the Newtonsoft.Json dependency, skip this step. Otherwise, download the library file from NuGet.org Newtonsoft.Json by clicking "Download package" on the right, change the file extension from .nupkg to .zip, extract the file, and copy the Newtonsoft.Json.dll file to the Plugins directory under Assets. Additionally, to avoid deleting necessary data when exporting to the IL2CPP platform, create a link.xml file in the Assets directory (if it already exists, add the following content):
<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>
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.

SDK Initialization​

During TapSDK initialization, you can configure game package properties and the 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.CN,
// Channel, such as AppStore, GooglePlay
channel = "AppStore",
// Language, default is Auto, the default is zh_Hans for domestic and en for abroad
preferredLanguage = TapTapLanguageType.zh_Hans,
// Game version number, if not provided, the app's version number will be read by default
gameVersion = "1.1.0",
// 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\"}",
// CAID, only for domestic iOS
caid = "000-000-0000-00000",
// Whether to override built-in parameters, default is false
overrideBuiltInParameters = false,
// Whether to enable advertiser ID collection, default is false
enableAdvertiserIDCollection = true,
// Whether to enable automatic reporting of IAP events
enableAutoIAPEvent = true,
// OAID certificate, only for Android, used to report OAID, only effective for [TapTapRegion.CN]
oaidCert = null,
// Whether to enable logging, set to false for the Release version
enableLog = true
};
// TapSDK initialization
TapTapSDK.Init(coreOptions);


// If there are other TapTap module configurations, you can initialize them together using the following API
// Other module configuration items
TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
achievementOptions,
// ...
};
TapTapSDK.Init(coreOptions, otherOptions);

FieldNullableDescription
clientIdNoClient ID, obtained from the developer backend
clientTokenNoClient Token, obtained from the developer backend
regionNoRegion, CN for domestic, Overseas for abroad
preferredLanguageYesDefault is TapTapLanguageType.Auto, language
enableLogYesDefault is false, whether to enable logging, set to false for the Release version
channelYesChannel, such as AppStore, GooglePlay
gameVersionYesGame version number, if not provided, the app's version number will be read by default
propertiesJsonYesCustom parameters passed during initialization, will be reported in the device_login event
caidYesCAID, only for domestic iOS
overrideBuiltInParametersYesWhether to override built-in parameters, default is false
enableAdvertiserIDCollectionYesWhether to enable advertiser ID collection, only for iOS, default is false, enable requires adding project configuration
enableAutoIAPEventYesWhether to enable automatic reporting of IAP events
oaidCertYesOAID certificate, only for Android, used to report OAID, only effective for [TapTapRegion.CN]

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​

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.LogChargeEvent(
   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.

OAID (Android)​

Note: 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.