Skip to main content
Version: v4

TapSDK Integration

This document introduces how to quickly integrate TapSDK.

Environment Requirements​

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

Project Configuration​

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"
         ]
      }
  ]
}
tip

If you need to integrate TapSDK for the Unity PC platform, you need to use the NuGet integration tool to integrate the K4os.Compression.LZ4 and protobuf-net libraries. The specific settings are as follows:

  • Add the following dependency in Packages/manifest.json:
"com.github-glitchenzo.nugetforunity": "https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity"

  • After adding, if the NuGet option does not appear in the top menu of Unity, restart the Unity editor, including the Unity Hub client.

  • In the top menu of Unity, select NuGet > Manage NuGet Packages, search for K4os.Compression.LZ4 and protobuf-net in the pop-up window, and install them.

    The final packages.config file in the Assets folder will automatically generate the following dependencies:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="K4os.Compression.LZ4" version="1.3.8" manuallyInstalled="true" />
  <package id="System.Collections.Immutable" version="7.0.0" />
  <package id="System.Runtime.CompilerServices.Unsafe" version="6.0.0" />
  <package id="protobuf-net" version="3.2.30" manuallyInstalled="true" />
  <package id="protobuf-net.Core" version="3.2.30" />
</packages>

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.4.0",
}

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.4.0",
 }

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:

    • TapTapSDK_Core.unitypackage TapTapSDK Core Module, Mandatory。

  2. 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>

Initialization​

When initializing TapSDK, you need to pass in application configuration information such as Client ID and region.

The new version of TapSDK provides unified initialization, and business modules (e.g., achievements, login, etc.) do not need separate initialization.

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,
   // Language, default is Auto, by default, zh_Hans for domestic, en for abroad
   preferredLanguage = TapTapLanguageType.zh_Hans,
   // Whether to enable logging, set to false for Release version
   enableLog = true
};
// TapSDK Initialization
TapTapSDK.Init(coreOptions);

// When you need to add initialization configuration items for other modules, such as compliance certification, achievements, etc., please use the following API
TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
    // Other module configuration items
};
TapTapSDK.Init(coreOptions, otherOptions);

During initialization, you must fill in client_id and client_token

  • client_id and client_token information can be found in Developer Center > Your Game > Game Services > Application Configuration.

Integration Features​

TapSDK provides numerous features. After initializing the SDK, refer to the documentation of the corresponding features and integrate them as needed for your project. Most games will integrate TapTap login, so we recommend starting with this feature.

Configure Signature Certificate​

Android and iOS applications need to go to the TapTap Developer Center, enter your game, and select Game Services > Application Configuration > Signature Certificate Configuration to configure the relevant information of the application (as shown below). Otherwise, when testing the login function for Android applications, a signature not match error message will be returned, and for iOS, a sdk_not_matched error message will be returned, making it impossible to use the TapTap login function normally.

Fill in the MD5 value at the Android signature. For details, please refer to: How to Obtain MD5 Value.

Next, you can package the application and test the TapTap login function.

Android Code Obfuscation​

TapSDK has already been obfuscated, and further obfuscation will lead to unexpected errors. Please add the following configuration to your project's obfuscation script to skip the obfuscation operation on TapSDK:

-keep class com.taptap.**{*;}

-keep class com.tapsdk.**{*;}

Packaging​

For Android or iOS, just follow the usual Android APK or iOS application packaging process. Here is an introduction to the Unity packaging process:

Packaging APK​

Step 1, configure package name and signature file:

Step 2, check File > Build Settings > Player Settings > Other Settings > Target API Level version. When the API Level is less than 29, you need to configure the manifest and add in the application node:

tools:remove="android:requestLegacyExternalStorage"

This is because the SDK internally defaults to android:requestLegacyExternalStorage = true, which will cause an error Android resource linking failed when targetSdkVersion < 29.

Export Xcode Project​

You need to configure the icon and BundleID:

Repackaging​

Initialization Failure Due to META-INF/services Merge Error​

tip

The implementation of TapSDK's initialization framework relies on auto-service, generating META-INF/services/xxx files (service implementation classes) through auto-service, and then using Java's service loader to load them.

The problem often appears as initialization failure, but the essential reason is that during repackaging, the game developer did not correctly merge the files in the META-INF folder.

Type 1: Excluded META-INF/services/com.taptap.sdk.internal.service.ITapAutoService File During Repackaging​

This type of problem is common, where developers often do not process all files under META-INF/services (exclude), leading to SDK initialization failure.

Type 2: Error in Merging META-INF/services/com.taptap.sdk.internal.service.ITapAutoService​

This means that the developer realized the need to process the files under META-INF/services, but an error occurred during the merge, leading to SDK initialization failure. This type of problem often arises because the developer adopted the override strategy rather than merge during repackaging, which means that when encountering the same file name META-INF/services/com.taptap.sdk.internal.service.ITapAutoService in multiple AARs, only one was retained, leading to SDK initialization failure.

Incorrect merge, as shown:

Correct merge, as shown: