版本：v3

好友指南

TDS 提供了两种好友模型：

开发者可根据游戏项目需求，选择其中一种模型。注意：

只能选择一种模型，同一游戏无法混用两种模型。
选定一种模型后，后续无法变更为另一种模型。

此外，还支持获取第三方平台的好友关系（此功能需要通过工单申请开通）。

我们建议开发者按照以下顺序入手：

了解 TDS 内建账户系统，好友功能依赖内建账户，下文中的玩家、用户均指 TDSUser。
阅读本文，了解如何初始化 SDK。
根据游戏项目需求，选定游戏将采用的好友模型，然后阅读相应的开发指南：
- 好友模式
- 关注模式

环境要求

Unity
Android
iOS
UE4

Unity 2019.4 或更高版本
iOS 11 或更高版本，Xcode 版本 14.1 或更高版本
Android 5.0（API level 21）或更高版本

集成前准备

参考准备工作创建应用、开启好友服务、绑定 API 域名；

SDK 获取

由于好友功能依赖内建账户，所以集成好友功能所需 SDK 依赖库需要在内建账户依赖库的基础上，在下载页获得 TapSDK，另外添加 TapFriends 模块：

Unity
Android
iOS

SDK 可以通过 Unity Package Manager 导入或手动导入，二者任选其一。请根据项目需要选择。

方法一：使用 Unity Package Manager

NPMJS 安装

从 3.25.0 版本开始，TapSDK 支持了 NPMJS 安装，优势是只需要配置版本号，并且支持嵌套依赖。

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

"dependencies":{
    "com.taptap.tds.friends":"3.28.3",
}

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

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

GitHub 安装

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

"dependencies":{
    "com.taptap.tds.login":"https://github.com/TapTap/TapLogin-Unity.git#3.28.3",
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.28.3",
    "com.taptap.tds.bootstrap":"https://github.com/TapTap/TapBootstrap-Unity.git#3.28.3",
    "com.taptap.tds.friends":"https://github.com/TapTap/TapFriends-Unity.git#3.28.3",
    "com.leancloud.realtime":"https://github.com/leancloud/csharp-sdk-upm.git#realtime-2.3.0",
    "com.leancloud.storage":"https://github.com/leancloud/csharp-sdk-upm.git#storage-2.3.0",
}

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

方法二：手动导入

在下载页找到 TapSDK Unity 和 LeanCloud C# SDK 下载地址，分别下载 TapSDK-UnityPackage.zip 和 LeanCloud-SDK-Realtime-Unity.zip。
在 Unity 项目中依次转到 Assets > Import Packages > Custom Packages，从解压后的 TapSDK-UnityPackage.zip 中，选择希望在游戏中使用的 TapSDK 包导入，其中：
- TapTap_Bootstrap.unitypackage TapSDK 启动器，必选。
- TapTap_Common.unitypackage TapSDK 基础库，必选。
- TapTap_Login.unitypackage TapTap 登录，必选。
- TapTap_Friends.unitypackage TapTap 好友，必选。
解压后的 LeanCloud-SDK-Realtime-Unity.zip 为 Plugins 文件夹，拖拽至 Unity 即可。

repositories{
    flatDir {
        dirs 'libs'
    }
}
dependencies {
    ...
    implementation (name:'TapFriend_3.28.3', ext:'aar')
}

TapFriendResource.bundle
TapFriendSDK.framework
TapFriendUISDK.framework

SDK 初始化

参考内建账户的初始化方法，初始化内建账户服务会同步初始化游戏好友服务；

提示

如需使用富信息功能，请先在 开发者中心 > 游戏服务 > 云服务 > 好友 > 设置 开启 富信息接口数据实时同步。并调用配置富信息字段的 REST API 接口设置需要使用的富信息字段。

富信息 REST API

下面我们介绍富信息相关的 REST API 接口。开发者可以自行编写程序或脚本调用这些接口在服务端进行管理性质的操作。

请求格式

对于 POST 和 PUT 请求，请求的主体必须是 JSON 格式，而且 HTTP Header 的 Content-Type 需要设置为 application/json。

请求的鉴权是通过 HTTP Header 里面包含的键值对来进行的，参数如下表：

Key	Value	含义	来源
`X-LC-Id`	`{{appid}}`	当前应用的 `App Id`（即 `Client Id`）	可在控制台查看
`X-LC-Key`	`{{appkey}}`	当前应用的 `App Key`（即 `Client Token`）	可在控制台查看

管理接口需要使用 Master Key：X-LC-Key: {{masterkey}},master。 Master Key 即 Server Secret，同样可在控制台查看。

详见文档关于应用凭证的说明。

Base URL

REST API 请求的 Base URL（下文 curl 示例中用 {{host}} 表示）即应用绑定的 API 自定义域名，可以在控制台绑定、查看。详见文档关于域名的说明。

获取富信息配置

curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "X-LC-Session: {{sessionToken}}" \
  https://{{host}}/friend/v1/rich-presence/config

返回结果示例：

{
  "clientId": "YOUR CLIENT ID",
  "enabled": 1,
  "richMsgEnabled": true,
  "onlineMsgEnabled": true,
  "webSocketUrl": "wss://XXX.ws.tds1.tapapis.cn/ws/leancloud/v1",
  "richPresenceFields": [
    {
      "key": "display",
      "type": "token"
    },
    {
      "key": "leadboard",
      "type": "token"
    },
    {
      "key": "inviteable",
      "type": "variable"
    },
    {
      "key": "score",
      "type": "variable"
    },
    {
      "key": "rank",
      "type": "variable"
    }
  ],
  "richPresenceMultiLang": [
    {
      "key": "display",
      "lang": "zh_CN",
      "content": {
        "#playing": "游戏中",
        "#idle": "在线",
        "#room": "准备中",
        "#matching": "组队中"
      }
    },
    {
      "key": "display",
      "lang": "en_US",
      "content": {
        "#playing": "Playing",
        "#idle": "Idle",
        "#room": "Room",
        "#matching": "Matching"
      }
    },
    {
      "key": "leadboard",
      "lang": "zh_CN",
      "content": {
        "#score": "%score% 分,排名为 %rank%",
        "#rank": "%rank% 名"
      }
    },
    {
      "key": "leadboard",
      "lang": "en_US",
      "content": {
        "#score": "%score% score",
        "#rank": "%rank% rank"
      }
    }
  ]
}

配置富信息字段

可以通过 REST API 设置游戏的富信息字段，需要指定各字段的名称和类型。这是管理接口，鉴权需要 Master Key：

curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{
    "enableRichMsg":true,
    "enableOnlineMsg":true,
    "richPresenceFields":[
        {"key":"display","type":"token"},
        {"key":"leadboard","type":"token"},
        {"key":"inviteable","type":"variable"},
        {"key":"score","type":"variable"},
        {"key":"rank","type":"variable"}
    ]
  }' \
  https://{{host}}/friend/v2/rich-presence/config/base-info

enableRichMsg 和 enableOnlineMsg 分别用于设置是否启用富信息通知、是否启用好友上下线通知，建议两者均指定为 true。注意，这个接口 URL 地址中的版本号是 v2，和其他接口的 v1 不同。

返回结果示例：

{
  "appId": "YOUR CLIENT ID"
}

请求失败返回结果示例：

{
  "code": 400,
  "error": "Missing request header"
}

配置多语言内容

配置富信息字段的多语言内容。这是管理接口，鉴权需要 Master Key：

curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{
    "action":"save",
    "config":[
        {
            "key": "display",
            "lang": "zh_CN",
            "content": {
                "#playing": "游戏中",
                "#idle": "在线",
                "#room": "准备中",
                "#matching": "组队中"
            }
        },
        {
            "key": "display",
            "lang": "en_US",
            "content": {
                "#playing": "Playing",
                "#idle": "Idle",
                "#room": "Room",
                "#matching": "Matching"
            }
        },
        {
            "key": "leadboard",
            "lang": "zh_CN",
            "content": {
                "#score": "%score% 分,竞技排名为 %rank%",
                "#rank": "%rank% 名"
            }
        },
        {
            "key": "leadboard",
            "lang": "en_US",
            "content": {
                "#score": "%score% score",
                "#rank": "%rank% rank best"
            }
        }
    ]
  }'
  https://{{host}}/friend/v1/rich-presence/config/lang-info

返回结果同上节的配置富信息字段接口。

获取玩家的富信息

可以一次性获取多个玩家的富信息（传入逗号分隔的 objectId 列表）：

curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "X-LC-Session: {{sessionToken}}" \
  -G --data-urlencode 'ids={userObjectId,anotherUserObjectId}'
  https://{{host}}/friend/v1/rich-presence/users

返回结果示例：

{
  "results": [
    {
      "online": false,
      "richPresence": {
        "score": "15",
        "leadboard": "15 分,排名为 150",
        "rank": "150"
      }
    },
    {
      "online": false,
      "richPresence": {}
    }
  ]
}

环境要求​

集成前准备​

SDK 获取​

方法一：使用 Unity Package Manager​

NPMJS 安装​

GitHub 安装​

方法二：手动导入​

SDK 初始化​

富信息 REST API​

请求格式​

Base URL​

获取富信息配置​

配置富信息字段​

配置多语言内容​

获取玩家的富信息​

环境要求

集成前准备

SDK 获取

方法一：使用 Unity Package Manager

NPMJS 安装

GitHub 安装

方法二：手动导入

SDK 初始化

富信息 REST API

请求格式

Base URL

获取富信息配置

配置富信息字段

配置多语言内容

获取玩家的富信息