From 3efc679efe0777a848bd37c697553e06470714a4 Mon Sep 17 00:00:00 2001 From: xiaoyi Date: Tue, 27 Jul 2021 17:50:47 +0800 Subject: [PATCH] feat: update doc , update unitypackage compile script , update push upm script --- CHANGELOG.md | 8 ++- Documentation/README.md | 133 ++++++++++++++++++++++++++++++++++++---- README.md | 133 ++++++++++++++++++++++++++++++++++++---- package.json | 4 +- 4 files changed, 252 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40874b9..24e376e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,16 @@ ## 3.1.0 +### New Feature + +- `TDSUser` 新增好友系统操作 + ### Dependencies - TapTap.Login v3.1.0 - TapTap.Common v3.1.0 -- LeanCloud.Storage v0.9.1 -- LeanCloud.Realtime v0.9.1 +- LeanCloud.Storage v0.9.2 +- LeanCloud.Realtime v0.9.2 ## 3.0.0 diff --git a/Documentation/README.md b/Documentation/README.md index ae629aa..201b76d 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -15,11 +15,11 @@ using TapTap.Bootstrap; ## 接口描述 -### 1.初始化 +## 1.初始化 -#### TapBootstrap 会根据 TapConfig 中的 TapDBConfig 配置来进行 TapDB 的自动初始化。 +TapBootstrap 会根据 TapConfig 中的 TapDBConfig 配置来进行 TapDB 的自动初始化。 -##### 开启 TapDB +### 开启 TapDB ```c# var config = new TapConfig.Builder() .ClientID("client_id") @@ -29,7 +29,7 @@ var config = new TapConfig.Builder() .TapDBConfig(true,"channel","gameVersion",true) .Builder(); ``` -##### 关闭 TapDB +### 关闭 TapDB ```c# var config = new TapConfig.Builder() .ClientID("client_id") @@ -40,44 +40,155 @@ var config = new TapConfig.Builder() .EnableTapDB(false) .Builder(); ``` -##### 初始化 +### 初始化 ```c# TapBootstrap.Init(config); ``` -### 2.账户系统 +## 2.账户系统 > 登陆成功之后，都会得到一个 `TDSUser` 实例 -#### 使用 TapTap OAuth 授权结果直接登陆/注册账户系统 +### 使用 TapTap OAuth 授权结果直接登陆/注册账户系统 ```c# var tdsUser = await TDSUser.LoginWithTapTap(); ``` -#### 游客登陆 +### 游客登陆 ```c# var tdsUser = await TDSUser.LoginAnonymously(); ``` -#### 使用第三方平台授权登录/注册账户 +### 使用第三方平台授权登录/注册账户 ```c# var tdsUser = await TDSUser.LoginWithAuthData(Dictionary authData, string platform, LCUserAuthDataLoginOption option = null); ``` -#### 绑定第三方平台授权 +### 绑定第三方平台授权 ```c# await TDSUser.AssociateAuthData(Dictionary authData, string platform); ``` -#### 退出登陆 +### 退出登陆 ```c# TDSUser.Logout(); ``` +## 3.好友系统 +### 申请成为好友 + +```c# +TDSUser tom, jerry; +await tom.ApplyFriendship(jerry); +``` +申请成功的回调中，我们会得到一个 LCFriendshipRequest 的实例，这个实例中包含了两个用户： +- sourceUser，指请求的发起方，上面的例子中就是 `tom`。 +- friend，指请求的目的方，上面的例子中就是 `jerry`。 + +tom 也可以在申请好友的时候，添加更多的属性，例如 tom 希望加 jerry 为好友的时候，也设定一个名为 cat 的圈子，可以这样操作： + +```cs +Dictionary attrs = new Dictionary { + { "group", "cat" } +}; +await tom.ApplyFriendship(jerry, attrs); +``` + +### 获取好友申请列表 +好友申请有三种状态： + +- `pending`，对方没有回应，还处于等待中。 +- `accepted`，对方已经接受，现在双方成为好友。 +- `declined`，对方已经拒绝。 + +好友请求创建之后默认是 `pending` 状态。 + +jerry 这里可以通过 `friendshipRequestQuery` 来查找不同状态的请求。例如 jerry 想看看新的好友请求，可以这样操作： + +```cs +LCQuery query = jerry.GetFriendshipRequestQuery(LCFriendshipRequest.STATUS_PENDING, false, true); +ReadOnlyCollection reqs = await query.Find(); +foreach (LCFriendshipRequest req in reqs) { + Console.WriteLine(req); +} +``` + +### 处理好友申请 + +jerry 对于新的好友请求，可以同意或者拒绝，也可以什么都不做，无视这些请求，甚至直接删除。这些操作我们都是支持的，请看下面的示例： + +```cs +LCFriendshipRequest tomRequest, tuffyRequest, otherRequest; +await jerry.AcceptFriendshipRequest(tomRequest); +await jerry.DeclineFriendshipRequest(tuffyRequest); +await jerry.DeleteFriendshipRequest(otherRequest); +``` + +注意： +* 在 jerry 拒绝了 tom 的好友请求之后，如果 tom 再次请求成为 jerry 的好友，tom 在执行 applyFriendshipInBackground 时会直接得到错误的应答，表明 jerry 不想和 ta 成为好友。 +* jerry 同意了 tuffy 的好友请求之后，它们就成为了好友，之后两个人中任何一人再次调用 applyFriendshipInBackground 申请横位好友时，也会直接得到错误的应答，表明它们已经是好友无需再次申请。 +* jerry 删除陌生人的好友请求后，对方还可以再次发起请求。 + +### 响应好友变化通知 + +TDS 好友模块支持客户端监听好友状态变化，在游戏中实时给玩家提示。好友状态变化的接口包括 + +```cs +public class FriendshipNotification { + public Action OnNewRequestComing { get; set; } + public Action OnRequestAccepted { get; set; } + public Action OnRequestDeclined { get; set; } +} +``` + +其中： +- onNewRequestComing 表示有其他人申请成为当前用户的好友，通过调用 `LCFriendshipRequest#getSourceUser()` 方法可以获得发起方用户信息。 +- onRequestAccepted 表示当前用户的好友申请被对方通过，通过调用 `LCFriendshipRequest#getFriend()` 方法可以获得对方用户信息。 +- onRequestDeclined 表示当前用户的好友申请被对方拒绝，通过调用 `LCFriendshipRequest#getFriend()` 方法可以获得对方用户信息。 + +开发者可以通过 `TDSUser#registerFriendshipNotification` 来注册通知接收器，通过调用 `TDSUser#unregisterFriendshipNotification` 来取消通知接收器。 + +### 获取好友列表 + +调用 `TDSUser#friendshipQuery()` 可以得到查询好友的 `LCQuery` 实例，之后调用 `LCQuery#findInBackground()` 方法就可以得到好友列表。示例如下： + +```cs +LCQuery query = jerry.GetFirendshipQuery(); +``` + +LCFriendship 里面会包含两个用户： + +- `LCFriendship#getLCUser(LCFriendship.ATTR_USER)` 得到的是 jerry 自己； +- `LCFriendship#getLCUser(LCFriendship.ATTR_FOLLOWEE)` 得到的就是另一方的用户信息。 + +### 删除好友 + +成为好友关系的两个用户，之后也可以单方面删除好友。例如 jerry 不想再和 tom 成为好友，那只需要在自己的好友列表中删除包含 tom 的那条 LCFriendship 记录即可： + +```cs +await friendship.Delete(); +``` + +### 查询好友关系 + +我们使用 LCQuery 可以单独查询两个用户是否为好友关系。 + +```cs +LCQuery query = jerry.GetFirendshipQuery(); +query.whereEqualTo("followee", tom); +int count = await query.Count(); +if (count > 0) { + // tom is a friend of jerry. +} else { + // tom isn't a friend of jerry. +} +``` + +这一查询是通过网络发送到服务端执行的，一般情况下，我们推荐开发者在游戏启动时拉取一次当前登录用户的好友列表，然后缓存在本地，以后需要检查另外玩家是否为当前用户的好友时，直接从缓存中查询即可。如果担心好友数据变化，缓存没有得到及时更新，可以调用前面「响应好友变化通知」的方法，对好友数据更新进行监听，这样在绝大部分时候数据同步都是可以保证的。 \ No newline at end of file diff --git a/README.md b/README.md index 92acc9d..8f69957 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,11 @@ using TapTap.Bootstrap; ## 接口描述 -### 1.初始化 +## 1.初始化 -#### TapBootstrap 会根据 TapConfig 中的 TapDBConfig 配置来进行 TapDB 的自动初始化。 +TapBootstrap 会根据 TapConfig 中的 TapDBConfig 配置来进行 TapDB 的自动初始化。 -##### 开启 TapDB +### 开启 TapDB ```c# var config = new TapConfig.Builder() .ClientID("client_id") @@ -29,7 +29,7 @@ var config = new TapConfig.Builder() .TapDBConfig(true,"channel","gameVersion",true) .Builder(); ``` -##### 关闭 TapDB +### 关闭 TapDB ```c# var config = new TapConfig.Builder() .ClientID("client_id") @@ -40,44 +40,155 @@ var config = new TapConfig.Builder() .EnableTapDB(false) .Builder(); ``` -##### 初始化 +### 初始化 ```c# TapBootstrap.Init(config); ``` -### 2.账户系统 +## 2.账户系统 > 登陆成功之后，都会得到一个 `TDSUser` 实例 -#### 使用 TapTap OAuth 授权结果直接登陆/注册账户系统 +### 使用 TapTap OAuth 授权结果直接登陆/注册账户系统 ```c# var tdsUser = await TDSUser.LoginWithTapTap(); ``` -#### 游客登陆 +### 游客登陆 ```c# var tdsUser = await TDSUser.LoginAnonymously(); ``` -#### 使用第三方平台授权登录/注册账户 +### 使用第三方平台授权登录/注册账户 ```c# var tdsUser = await TDSUser.LoginWithAuthData(Dictionary authData, string platform, LCUserAuthDataLoginOption option = null); ``` -#### 绑定第三方平台授权 +### 绑定第三方平台授权 ```c# await TDSUser.AssociateAuthData(Dictionary authData, string platform); ``` -#### 退出登陆 +### 退出登陆 ```c# TDSUser.Logout(); ``` +## 3.好友系统 +### 申请成为好友 + +```c# +TDSUser tom, jerry; +await tom.ApplyFriendship(jerry); +``` +申请成功的回调中，我们会得到一个 LCFriendshipRequest 的实例，这个实例中包含了两个用户： +- sourceUser，指请求的发起方，上面的例子中就是 `tom`。 +- friend，指请求的目的方，上面的例子中就是 `jerry`。 + +tom 也可以在申请好友的时候，添加更多的属性，例如 tom 希望加 jerry 为好友的时候，也设定一个名为 cat 的圈子，可以这样操作： + +```cs +Dictionary attrs = new Dictionary { + { "group", "cat" } +}; +await tom.ApplyFriendship(jerry, attrs); +``` + +### 获取好友申请列表 +好友申请有三种状态： + +- `pending`，对方没有回应，还处于等待中。 +- `accepted`，对方已经接受，现在双方成为好友。 +- `declined`，对方已经拒绝。 + +好友请求创建之后默认是 `pending` 状态。 + +jerry 这里可以通过 `friendshipRequestQuery` 来查找不同状态的请求。例如 jerry 想看看新的好友请求，可以这样操作： + +```cs +LCQuery query = jerry.GetFriendshipRequestQuery(LCFriendshipRequest.STATUS_PENDING, false, true); +ReadOnlyCollection reqs = await query.Find(); +foreach (LCFriendshipRequest req in reqs) { + Console.WriteLine(req); +} +``` + +### 处理好友申请 + +jerry 对于新的好友请求，可以同意或者拒绝，也可以什么都不做，无视这些请求，甚至直接删除。这些操作我们都是支持的，请看下面的示例： + +```cs +LCFriendshipRequest tomRequest, tuffyRequest, otherRequest; +await jerry.AcceptFriendshipRequest(tomRequest); +await jerry.DeclineFriendshipRequest(tuffyRequest); +await jerry.DeleteFriendshipRequest(otherRequest); +``` + +注意： +* 在 jerry 拒绝了 tom 的好友请求之后，如果 tom 再次请求成为 jerry 的好友，tom 在执行 applyFriendshipInBackground 时会直接得到错误的应答，表明 jerry 不想和 ta 成为好友。 +* jerry 同意了 tuffy 的好友请求之后，它们就成为了好友，之后两个人中任何一人再次调用 applyFriendshipInBackground 申请横位好友时，也会直接得到错误的应答，表明它们已经是好友无需再次申请。 +* jerry 删除陌生人的好友请求后，对方还可以再次发起请求。 + +### 响应好友变化通知 + +TDS 好友模块支持客户端监听好友状态变化，在游戏中实时给玩家提示。好友状态变化的接口包括 + +```cs +public class FriendshipNotification { + public Action OnNewRequestComing { get; set; } + public Action OnRequestAccepted { get; set; } + public Action OnRequestDeclined { get; set; } +} +``` + +其中： +- onNewRequestComing 表示有其他人申请成为当前用户的好友，通过调用 `LCFriendshipRequest#getSourceUser()` 方法可以获得发起方用户信息。 +- onRequestAccepted 表示当前用户的好友申请被对方通过，通过调用 `LCFriendshipRequest#getFriend()` 方法可以获得对方用户信息。 +- onRequestDeclined 表示当前用户的好友申请被对方拒绝，通过调用 `LCFriendshipRequest#getFriend()` 方法可以获得对方用户信息。 + +开发者可以通过 `TDSUser#registerFriendshipNotification` 来注册通知接收器，通过调用 `TDSUser#unregisterFriendshipNotification` 来取消通知接收器。 + +### 获取好友列表 + +调用 `TDSUser#friendshipQuery()` 可以得到查询好友的 `LCQuery` 实例，之后调用 `LCQuery#findInBackground()` 方法就可以得到好友列表。示例如下： + +```cs +LCQuery query = jerry.GetFirendshipQuery(); +``` + +LCFriendship 里面会包含两个用户： + +- `LCFriendship#getLCUser(LCFriendship.ATTR_USER)` 得到的是 jerry 自己； +- `LCFriendship#getLCUser(LCFriendship.ATTR_FOLLOWEE)` 得到的就是另一方的用户信息。 + +### 删除好友 + +成为好友关系的两个用户，之后也可以单方面删除好友。例如 jerry 不想再和 tom 成为好友，那只需要在自己的好友列表中删除包含 tom 的那条 LCFriendship 记录即可： + +```cs +await friendship.Delete(); +``` + +### 查询好友关系 + +我们使用 LCQuery 可以单独查询两个用户是否为好友关系。 + +```cs +LCQuery query = jerry.GetFirendshipQuery(); +query.whereEqualTo("followee", tom); +int count = await query.Count(); +if (count > 0) { + // tom is a friend of jerry. +} else { + // tom isn't a friend of jerry. +} +``` + +这一查询是通过网络发送到服务端执行的，一般情况下，我们推荐开发者在游戏启动时拉取一次当前登录用户的好友列表，然后缓存在本地，以后需要检查另外玩家是否为当前用户的好友时，直接从缓存中查询即可。如果担心好友数据变化，缓存没有得到及时更新，可以调用前面「响应好友变化通知」的方法，对好友数据更新进行监听，这样在绝大部分时候数据同步都是可以保证的。 \ No newline at end of file diff --git a/package.json b/package.json index 901c8c8..96b8f74 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "dependencies": { "com.taptap.tds.common": "https://github.com/TapTap/TapCommon-Unity.git#3.1.0", "com.taptap.tds.login": "https://github.com/TapTap/TapLogin-Unity.git#3.1.0", - "com.leancloud.storage": "https://github.com/leancloud/csharp-sdk-upm.git#storage-0.9.1", - "com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-0.9.1" + "com.leancloud.storage": "https://github.com/leancloud/csharp-sdk-upm.git#storage-0.9.2", + "com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-0.9.2" } }