Skip to main content
Version: v4

Development Guide

Permissions Description​

Preparing to Integrate the SDK​

  1. Refer to Preparation Work to create an application, enable application configuration;
  2. Refer to Quick Start to configure the package name and signature certificate;

Obtaining the SDK​

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",
    "com.taptap.sdk.login":"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",
   "com.taptap.sdk.login":"https://github.com/taptap/TapSDKLogin-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。
    • TapTapSDK_Login.unitypackage TapTapSDK Login 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>

iOS Configuration​

Create a TDS-Info.plist file in the Assets/Plugins/iOS/Resource directory, copy the following code, and replace ClientId within it.

tip

When copying the content below, please remove empty lines and comments to avoid XML parsing errors, such as ApplicationException: expected a key node.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>taptap</key>
    <dict>
        <key>client_id</key>
        <string>ClientId</string>
    </dict>
</dict>
</plist>

SDK Initialization​

TapTap login module depends on TapTapSDK initialization, please refer to TapSDK Integration for details.

using TapSDK.Core;
 
// Core configuration, detailed parameters see [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TapSDK Initialization
TapTapSDK.Init(coreOptions);

Login​

tip

When the user starts the game, you can first check the user's login status. If the player is already logged in, do not display the login button and allow the player to enter the game directly.

using TapSDK.Login;
using System.Threading.Tasks;

// Define authorization scopes
List<string> scopes = new List<string>();
scopes.Add(TapTapLogin.TAP_LOGIN_SCOPE_PUBLIC_PROFILE);

// Initialize login request Task
Task<TapTapAccount> task = TapTapLogin.Instance.LoginWithScopes(scopes.ToArray());
var result = await task;

// Check login result
if (task.IsCompleted)
{
    // Login successful
} 
else if (task.IsCanceled)
{
    // Login canceled
}
else
{
    // Login failed
    Debug.Log($"Login failed: {task.Exception.Message}");
}

Different Authorization Scopes​

The TapTap authorization login interface supports selecting different authorization scopes and supports any combination, but must include either public_profile or basic_info, otherwise openid and unionid cannot be obtained. The TapTap authorization login interface can pass an array of String types as parameters, and developers can add different permissions as elements of the array according to their business needs.

PermissionDescription
public_profileObtain openid, unionid, user nickname, user avatar
user_friendsObtain permission to access TapTap friend-related data
basic_infoObtain openid and unionid
emailObtain email and emailVerified data

Obtaining User Information​

After TapTap user login is successful, developers can obtain detailed information about the TapTap authorization result as follows:

The Profile class obtained here varies according to the authorization scopes requested by the game.

It may contain the following information:

ParameterDescription
nameThe player's nickname on the TapTap platform
avatarThe player's avatar URL on the TapTap platform
openidA unique user identifier generated through user information and game information, each player's openid in each game is different
unionidA unique user identifier generated through user information and vendor information, unionid is the same for a player in all games under the same vendor, different under different vendors
emailThe email used by the user to register on the TapTap platform
emailVerifiedWhether the email used by the user to register on the TapTap platform has been verified

openid and unionid are encoded using standard Base64 (with Padding) and contain characters A-Za-z0-9+/=. The maximum length of openid and unionid is 50 characters.

info

Since unionid is strongly related to the vendor of the game, unionid is suitable for scenarios such as: the vendor uses a test server for paid deletion tests, and the official server needs to provide benefits to old players who participated in the tests before. This is because the same player has an unchanged unionid in all games under the same vendor. A user's unionid will change after a game is transferred to another vendor. If a game uses unionid, TDS technical support will confirm the relevant data processing plan with the game developer through a ticket before the transfer to ensure that user data is not confused before and after the transfer.

Check Login Status and User Information​

The login status and user information are stored in local cache, re-logging will reset it, and logging out will clear it.

using TapSDK.Login;

try {
    TapTapAccount account = await TapTapLogin.Instance.GetCurrentTapAccount();
    if (account == null) {
        // User not logged in
    } else {
        // User logged in
    }
} catch (Exception e) {
    Debug.Log($"Failed to obtain user information {e.Message}");
}

Logout​

using TapSDK.Login;

TapTapLogin.Instance.Logout();

Unity PC Login Configuration​

tip

The SDK supports QR code login by default, extra configuration is needed for redirecting to browser login, refer to the following sections for details.

PC Login

Windows Platform​

To use the browser login feature on Windows, the registry needs to be configured accordingly:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]
@="{Game Name}"
"URL Protocol"="{Program.exe installation path}}"

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]
@="{Game Name}"

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]

[HKEY_CLASSES_ROOT\open-taptap-{client_id}\Shell\Open]

[HKEY_CLASSES_ROOT\open-taptap-{client_id}\Shell\Open\Command]
@="\"{Program.exe installation path}\" \"%1\""

macOS Platform​

On macOS, the SDK will automatically configure CFBundleURLTypes.

Please confirm the configuration is correct by following these steps:

  • In Unity, open BuildSetting, select PC, Mac & Linux Standalone Platform, and set Target Platform to macOS.
  • Check Create XCode Project and choose to output the XCode project for compilation.
  • Open the output XCode Project, select Target, click Info, expand URL Types, and check if the following URL Scheme is automatically added: TapWeb : open-taptap-{clientId}. If not, add it manually:
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>TapWeb</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>open-taptap-{client_id}</string>
        </array>
    </dict>
</array>