版本：v4

好友（含聊天）开发指南

本文介绍如何在游戏中加入好友&聊天系统。

权限说明

Unity
Android Java
Android Kotlin

该模块需要如下权限：

权限	使用目的	权限申请时机
网络权限	用于访问网络数据	用户首次使用该功能时会申请权限
网络状态权限	用于检查网络连接状态（如 Wi-Fi 或移动数据是否可用）	用户首次使用该功能时会申请权限
读取外部存储权限	用于读取设备上的文件和媒体内容	用户首次使用相关功能时会申请权限
写入外部存储权限	用于保存文件到设备存储	用户首次使用文件保存功能时会申请权限
管理外部存储权限	用于管理设备上的文件	用户首次使用文件管理功能时会申请权限
前台服务权限	用于在应用处于后台时保持某些功能运行	应用需要在后台运行服务时
相机权限	用于拍摄照片和视频通话	用户首次使用相机相关功能时会申请权限
振动权限	用于消息通知时的振动提醒	应用需要使用振动提醒时

该模块将在应用中添加如下权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />

该模块需要如下权限：

权限	使用目的	权限申请时机
网络权限	用于访问网络数据	用户首次使用该功能时会申请权限
网络状态权限	用于检查网络连接状态（如 Wi-Fi 或移动数据是否可用）	用户首次使用该功能时会申请权限
读取外部存储权限	用于读取设备上的文件和媒体内容	用户首次使用相关功能时会申请权限
写入外部存储权限	用于保存文件到设备存储	用户首次使用文件保存功能时会申请权限
管理外部存储权限	用于管理设备上的文件	用户首次使用文件管理功能时会申请权限
前台服务权限	用于在应用处于后台时保持某些功能运行	应用需要在后台运行服务时
相机权限	用于拍摄照片和视频通话	用户首次使用相机相关功能时会申请权限
振动权限	用于消息通知时的振动提醒	应用需要使用振动提醒时

该模块将在应用中添加如下权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />

集成前准备

参考准备工作创建应用、开启好友服务。

SDK 获取

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

第一步：添加 SDK 所需的外部依赖

SDK 内部使用了部分第三方库，开发者接入时需先确保 SDK 外部依赖库已正常接入，具体设置如下：

SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.1"

SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖，如果当前工程已接入该依赖库，则不需额外处理，否则需在 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"
         ]
      }
  ]
}

第二步：添加 SDK 依赖

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式，开发者根据需求选择其中一种即可，推荐使用远程依赖。

远程依赖

SDK 支持通过 NPMJS 及 GitHub 两种方式，开发者选择其中一种即可。

1. NPMJS 接入

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
   "com.taptap.sdk.core":"4.8.2",
   "com.taptap.sdk.login":"4.8.2",
   "com.taptap.sdk.relation":"4.8.2",
}

但需要注意的是，需在 Packages/manifest.json 中 dependencies 同级下声明 scopedRegistries：

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

2. GitHub 接入

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
   "com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.8.2",
   "com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.8.2",
   "com.taptap.sdk.relation":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Relation#4.8.2",
}

说明：自 4.7.2 起，Unity Packages 仓库已统一为大仓 tapsdk-unity-dist，所有包通过目录区分并使用 ?path= 指定子目录、# 指定版本标签。例如 Core 模块：
"com.taptap.sdk.core": "https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.7.2"

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

本地文件导入

在下载页下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：

TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
TapSDK_Login.unitypackage TapTapSDK 登录模块，必选。
TapSDK_Relation.unitypackage TapTapSDK 好友模块，必选。

如果当前项目已集成 Newtonsoft.Json 依赖，则忽略该步骤，否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧「Download package」下载库文件，并将下载的文件后缀从.nupkg 修改为 .zip，同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 Assets 的 Plugins 目录下，另外为了避免导出 IL2CPP 平台时删除必要数据，需在 Assets 目录下创建 link.xml 文件（如果已有该文件，则添加如下内容），其内容如下：

<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>

项目根目录的 build.gradle 添加仓库地址：

allprojects { 
    repositories {
        google()
        mavenCentral()
    }
}

app module 的 build.gradle 添加对应依赖：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.8.2'
  implementation 'com.taptap.sdk:tap-relation:4.8.2'
  implementation 'com.taptap.sdk:tap-login:4.8.2'
}

项目根目录的 build.gradle 添加仓库地址：

allprojects { 
    repositories {
        google()
        mavenCentral()
    }
}

app module 的 build.gradle 添加对应依赖：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.8.2'
  implementation 'com.taptap.sdk:tap-login:4.8.2'
  implementation 'com.taptap.sdk:tap-relation:4.8.2'
}

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapRelationSDK', '~> 4.8.2'

执行 Pod install 下载对应依赖文件
将工程 Pods 目录下 TapTapRelationSDK/Frameworks/TapTapRelationResource.bundle 和 TapTapProfileSDK/Frameworks/TapTapProfileResource.bundle 等资源文件导入工程中

本地文件依赖

好友模块依赖于 Tap 登录模块，使用本地文件方式添加依赖时，需先参考入门指南和 TapTap 登录添加对应本地文件依赖项。

在下载页下载如下文件：

TapTapRelationSDK 好友依赖库
TapTapRelationResource.bundle 好友资源文件
TapTapProfileSDK 用户名片依赖库
TapTapProfileResource.bundle 用户名片资源文件

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件
SDK 内部使用了 Kingfisher 6.0 依赖库，开发者应提前通过远程或文件导入方式添加对应依赖。

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapRelationSDK', '~> 4.8.2'

执行 Pod install 下载对应依赖文件
将工程 Pods 目录下 TapTapRelationSDK/Frameworks/TapTapRelationResource.bundle 和 TapTapProfileSDK/Frameworks/TapTapProfileResource.bundle 等资源文件导入工程中

本地文件依赖

好友模块依赖于 Tap 登录模块，使用本地文件方式添加依赖时，需先参考入门指南和 TapTap 登录添加对应本地文件依赖项。

在下载页下载如下文件：

TapTapRelationSDK 好友依赖库
TapTapRelationResource.bundle 好友资源文件
TapTapProfileSDK 用户名片依赖库
TapTapProfileResource.bundle 用户名片资源文件

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件
SDK 内部使用了 Kingfisher 6.0 依赖库，开发者应提前通过远程或文件导入方式添加对应依赖。

SDK 初始化

详见 TapTapSDK 初始化文档。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

TapTapSdkOptions 详细参数见入门指南#快速开始

using TapSDK.Core;
using TapSDK.Relation;

// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// 设置屏幕方向：0-竖屏 1-横屏
coreOptions.screenOrientation = 1;
// TapSDK 初始化
TapTapSDK.Init(coreOptions, otherOptions);

import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
boolean enableLog = BuildConfig.DEBUG;
// 屏幕方向，横屏传ScreenOrientation.LANDSCAPE 竖屏传ScreenOrientation.PORTRAIT
int screenOrientation = ScreenOrientation.LANDSCAPE;
TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
        clientId, // 游戏 Client ID
        clientToken, // 游戏 Client Token
        TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
// 设置屏幕方向
tapSdkOptions.setScreenOrientation(screenOrientation);
tapSdkOptions.setEnableLog(enableLog);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions);

import com.taptap.sdk.core.TapTapSdk
import com.taptap.sdk.core.TapTapSdkOptions
import com.taptap.sdk.core.TapTapLanguage
import com.taptap.sdk.core.TapTapRegion

/* 必选配置 */
// 开发者中心对应 Client ID
val clientId = "";
// 开发者中心对应 Client Token
val clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
val enableLog = BuildConfig.DEBUG;
// 屏幕方向，横屏传ScreenOrientation.LANDSCAPE 竖屏传ScreenOrientation.PORTRAIT
val screenOrientation = ScreenOrientation.LANDSCAPE

TapTapSdk.init(
    context = context,
    sdkOptions = TapTapSdkOptions(
        clientId = clientId,
        clientToken = clientToken,
        region = TapTapRegion.CN,
        screenOrientation = screenOrientation,
        preferredLanguage = TapTapLanguage.ZH_HANS,
        enableLog = false
    )
)

import TapTapCoreSDK

// 核心配置项
let options = TapTapSdkOptions()
options.clientId = "your_client_id" // 必须，开发者中心对应 Client ID
options.clientToken = "your_client_token" // 必须，开发者中心对应 Client Token
options.region = .CN // .CN：中国大陆，.overseas：其他国家或地区
options.enableLog = enableLog.selectedSegmentIndex == 0 // 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
options.preferredLanguage = TapLanguageType.auto // 语言设置，默认跟随系统，当系统语言不支持时，国内为中文，海外为英文
options.screenOrientation = .landscape // 应用屏幕方向，.landscape 横屏， .portrait 竖屏
// 初始化 SDK
TapTapSDK.initWith(options)

#import "TapTapCoreSDK/TapTapSDK.h"

// 核心配置项
TapTapSdkOptions *options = [[TapTapSdkOptions alloc] init];
options.clientId = @"your_clientId"; // 必须，开发者中心对应 Client ID
options.clientToken = @"your_client_token"; // 必须，开发者中心对应 Client Token
options.region = TapTapRegionTypeCN; // CN：中国大陆，overseas：其他国家或地区
options.enableLog = YES; // 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
options.preferredLanguage = TapLanguageType_Auto; // 语言设置，默认跟随系统，当系统语言不支持时，国内为中文，海外为英文
options.screenOrientation = TapTapScreenOrientationLandscape; // 应用屏幕方向，TapTapScreenOrientationLandscape 横屏，TapTapScreenOrientationPortrait 竖屏
// 初始化 SDK
[TapTapSDK initWithOptions:options];

注册监听回调

好友聊天 SDK 中包含多个监听回调，分别会在未登录/有新增粉丝/有新增消息时被调用。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

RelationCallback callback = new RelationCallback();
TapTapRelation.RegisterRelationCallback(callback);
TapTapRelation.UnregisterRelationCallback(callback);

class RelationCallback : ITapTapRelationCallback
{

    public RelationCallback(){}

    public void OnMessengerCodeResult(int code)
    {
        // 处理好友聊天的状态码
        // code 400001 需要用户登录
    }

    public void OnNewFansCountChanged(int code, int newFansCount)
    {
        // 新增粉丝数量变化
        // newFansCount 新增粉丝数
    }

    public void OnUnreadMessageCountChanged(int code, int unreadMsgCount)
    {
        // 新增未读消息数量变化
        // unreadMsgCount 新增未读消息数
    }

}

import com.taptap.sdk.relation.TapTapRelationCallback;
import com.taptap.sdk.relation.TapTapRelation;
import com.taptap.sdk.relation.TapTapRelationMessengerCode;

TapTapRelationCallback callback = new TapTapRelationCallback(){

    @Override
    public void onMessengerCodeResult(int code) {
        // 处理好友聊天的状态码
        // code 400001 需要用户登录
    }
    
    @Override
    public void onNewFansCountChanged(int code, int fansCount) {
        // 新增粉丝数量变动
    }

@Override
    public void onUnreadMessageCountChanged(int code, int unreadMsgCount) {
        // 新增消息数量变动
    }
};
TapTapRelation.registerRelationCallback(callback);
TapTapRelation.unregisterRelationCallback(callback);

import com.taptap.sdk.relation.TapTapRelationCallback
import com.taptap.sdk.relation.TapTapRelation
import com.taptap.sdk.relation.TapTapRelationMessengerCode

private val callback = object : TapTapRelationCallback {
        override fun onMessengerCodeResult(code: Int) {
            when (code) {
                // 未登录
                NEED_LOGIN -> {
                }
            }
        }

        override fun onNewFansCountChanged(code: Int, fansCount: Int) {
        }

        override fun onUnreadMessageCountChanged(code: Int, unreadMsgCount: Int) {
        }
    }

TapTapRelation.registerRelationCallback(callback = callback)
TapTapRelation.unregisterRelationCallback(callback = callback)

import TapTapRelationSDK

class MyRelationDelegate: NSObject, TapTapRelationDelegate {
    
    func onMessengerCodeResult(code: Int) {
        // 处理好友聊天的状态码
        // code 400001 需要用户登录
    }
    
    func onNewFansCountChanged(code: Int, fansCount: Int) {
        // 新增粉丝数量变动
    }
    
    func onUnreadMessageCountChanged(code: Int, unreadMsgCount: Int) {
        // 新增消息数量变动
    }
    
}

let myRelationDelegate = MyRelationDelegate()

// 注册回调
TapTapRelation.registerRelationDelegate(delegate: myRelationDelegate)
// 移除回调
TapTapRelation.unregisterRelationDelegate(delegate: myRelationDelegate)

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

@interface GameMainController() <TapTapRelationDelegate>

@end
@implementation GameMainController

- (void) handleRelationDelegate {
    // 注册好友回调
    [TapTapRelation registerRelationDelegateWithDelegate:self];
    // 移除好友回调
    [TapTapRelation unregisterRelationDelegateWithDelegate:self];
}

- (void)onMessengerCodeResultWithCode:(NSInteger)code { 
    // 处理好友聊天的状态码
    // code 400001 需要用户登录
}

- (void)onNewFansCountChangedWithCode:(NSInteger)code fansCount:(NSInteger)fansCount { 
    // 新增粉丝数量变动
}

- (void)onUnreadMessageCountChangedWithCode:(NSInteger)code unreadMsgCount:(NSInteger)unreadMsgCount { 
    // 新增消息数量变动
}

准备阶段

进入聊天之前的一些准备工作。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

TapTapRelation.Prepare();

import com.taptap.sdk.relation.TapTapRelation;
TapTapRelation.prepare();

import com.taptap.sdk.relation.TapTapRelation
TapTapRelation.prepare()

import TapTapRelationSDK

TapTapRelation.prepare()

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

[TapTapRelation prepare];

开始聊天

打开聊天页面，根据初始化参数 screenOrientation 会有不同的动画表现。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

TapTapRelation.StartMessenger();

import com.taptap.sdk.relation.TapTapRelation;
TapTapRelation.startMessenger();

import com.taptap.sdk.relation.TapTapRelation
TapTapRelation.startMessenger()

import TapTapRelationSDK

TapTapRelation.startMessenger()

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

[TapTapRelation startMessenger];

邀请好友上线

打开邀请好友页面，向选中好友发送邀请上线消息。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

TapTapRelation.InviteGame();

import com.taptap.sdk.relation.TapTapRelation;
TapTapRelation.inviteGame();

import com.taptap.sdk.relation.TapTapRelation
TapTapRelation.inviteGame()

import TapTapRelationSDK

TapTapRelation.inviteGame()

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

[TapTapRelation inviteGame];

邀请好友组队

打开邀请好友页面，向选中好友发送邀请组队消息，需要传组队相关参数teamId。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

string teamId = "";
TapTapRelation.InviteTeam(teamId);

import com.taptap.sdk.relation.TapTapRelation;
String teamId = "";
TapTapRelation.inviteTeam(teamId);

import com.taptap.sdk.relation.TapTapRelation
val teamId = ""
TapTapRelation.inviteTeam(teamId = teamId)

import TapTapRelationSDK

let teamId = ""
TapTapRelation.inviteTeam(teamId)

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

NSString * teamId = @"";
[TapTapRelation inviteTeam:teamId];

获取新增粉丝数

获取当前用户新增粉丝的数量，也可在callback中处理。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

TapTapRelation.GetNewFansCount((count) =>
{
    Log($"新粉丝数量: {count}");
});

import com.taptap.sdk.relation.TapTapRelation;
int fansCount = TapTapRelation.getNewFansCount();

import com.taptap.sdk.relation.TapTapRelation
val fansCount = TapTapRelation.getNewFansCount()

import TapTapRelationSDK

let fansCount = TapTapRelation.getNewFansCount()

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

NSInteger fansCount = [TapTapRelation getNewFansCount];

获取新增消息数

获取当前用户新增消息的数量，也可在callback中处理。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

TapTapRelation.GetUnreadMessageCount((count) =>
{
    Log($"未读消息数量: {count}");
});

import com.taptap.sdk.relation.TapTapRelation;
int unreadMessageCount = TapTapRelation.getUnreadMessageCount();

import com.taptap.sdk.relation.TapTapRelation
val unreadMessageCount = TapTapRelation.getUnreadMessageCount()

import TapTapRelationSDK

let unreadMessageCount = TapTapRelation.getUnreadMessageCount()

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

NSInteger unreadMessageCount = [TapTapRelation getUnreadMessageCount];

展示 TapTap 用户名片

展示指定用户的名片弹窗，可用于关注/取关用户，传入用户的openId或者unionId。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Relation;

string openId = "";
string unionId = "";
TapTapRelation.ShowTapUserProfile(openId, unionId);

import com.taptap.sdk.relation.TapTapRelation;
// openId unionId二选一即可
String openId = "";
String unionId = "";
TapTapRelation.showTapUserProfile(openId, unionId);

import com.taptap.sdk.relation.TapTapRelation
// openId unionId二选一即可
val openId = "";
val unionId = "";
TapTapRelation.showTapUserProfile(openId = openId, unionId = unionId)

import TapTapRelationSDK

let openId = ""
let unionId = ""

// openId unionId二选一即可
TapTapRelation.showTapUserProfile(openId: openId)

TapTapRelation.showTapUserProfile(unionId: unionId)

#import "TapTapRelationSDK/TapTapRelationSDK-Swift.h"

// openId unionId二选一即可
NSString * openId = @"";
NSString * unionId = @"";
[TapTapRelation showTapUserProfileWithOpenId:openId unionId:unionId];

国际化

TapTapRelation 支持设置语言：目前只支持简体中文

权限说明​

集成前准备​

SDK 获取​

第一步：添加 SDK 所需的外部依赖​

第二步：添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

SDK 初始化​

注册监听回调​

准备阶段​

开始聊天​

邀请好友上线​

邀请好友组队​

获取新增粉丝数​

获取新增消息数​

展示 TapTap 用户名片​

国际化​