# 游戏服务-好友系统

## 一、模块说明

本模块功能自运营 SDK `3.13.0` 开始提供

SDK 提供的好友系统 API，将游戏盒好友关系迁移至游戏中，为4399代理的游戏提供好友系统功能，并且支持调用功能接口，  
包括获取安卓游戏盒的好友关系列表，提供完整的添加、删除、查找和邀请好友等功能接口，帮助游戏减少开发成本。

## 二、集成流程

在正式接入好友系统前，接入方需要确认以下流程已完善：
- 已经在 4399 平台注册好游戏，并完善了平台所要求的配置
- 已经按照一般流程引入了 4399 运营SDK，具体流程参考 [SDK 客户端接入文档](./online_java_guide.html)


## 三、接口调用

### 0、前置接口

在调用本服务相关接口前，游戏应先调用下面前置接口：
- [初始化](./online_java_guide.html)
- [登录](./online_java_guide.html)

### 1、用户自身信息

`Friendship.getPtUser`，获取用户自身信息

```java
/**
  * 获取自身用户信息
  *
  * @return 用户id，昵称，头像地址
  */
public static PtUser getPtUser() {
    return PtUserProvider.provide();
}
```

`PtUser`，好友系统中定义的数据模型，描述玩家信息  
*具体信息在本文档后文的 API 详情部分，接口示例中涉及的其他类也是如此*

调用示例：

```java
PtUser user = Friendship.getPtUser();
```

### 2、好友关系列表
`Friendship.list`，获取好友关系列表
```java
/**
 * 获取好友关系列表
 *
 * @param type     需要获取的某一列表，包含 {@value FOLLOW},{@value FOLLOWER},{@value MUTUAL},{@value BLACK}
 * @param page     分页页码，仅当获取粉丝列表时参数有效，其他类型列表可传默认值 1
 * @param listener 回调对象 
 */
public static void list(int type, int page, OpeDataListener<FriendshipModel> listener); 
```

`OpeDataListener`，通用泛型回调接口，接入方调用方法后通过接口方法接收并处理调用结果

参数`type`详解：

| 列表类型参数| 含义|
|:------------------------------|:--------|
|`Friendship.FOLLOW`, `int`,  0 | 关注用户列表 |
|`Friendship.FOLLOWER`, `int`,  1 | 粉丝用户列表 |
|`Friendship.MUTUAL`,`int`,  2 | 互关用户列表 |
|`Friendship.BLACK`,`int`,  3 | 黑名单列表   |

调用示例
```java
// page：分页页码，获取粉丝列表时可分页，默认为 1
Friendship.list(Friendship.FOLLOW, page, new OpeDataListener<FriendshipModel>() {
    @Override
    public void onFinished(int code, @Nullable String message, @Nullable FriendshipModel data) {
        // 根据回调结果进行处理，如使用data.follows
    }
});
```

### 3、关注

`Friendship.follow`，当前用户关注其他用户
```java
/**
  * 当前用户关注其他用户
  *
  * @param uids     被关注用户uid,多个以英文逗号隔开
  * @param listener 回调对象
  */
 public static void follow(String uids, OpeDataListener<Void> listener);
```

调用示例：
```java
// uids：被关注用户uid，多个以英文逗号隔开
Friendship.follow(uids, new OpeDataListener<Void>() {
    @Override
    public void onFinished(int code, @Nullable String message, @Nullable Void data) {
        // 根据code进行判断是否关注成功 
    }
});
```

**接口 code 列表**

| code        | 含义              |
|-------------|-------------------|
| `98`        | 被关注用户非游戏盒用户        |
| `99`        | 当前用户非游戏盒用户          |


### 4、取消关注

`Friendship.unfollow`，当前用户取消关注其他用户
```java
/**
 * 当前用户取消关注其他用户
 *
 * @param uid      被取消关注用户uid
 * @param listener 回调对象
 */
public static void unfollow(String uid, OpeDataListener<Void> listener);
```

调用示例：
```java
// uid：被取消关注用户uid
Friendship.unfollow(uid, new OpeDataListener<Void>() {
    @Override
    public void onFinished(int code, @Nullable String message, @Nullable Void data) {
        // 根据code进行判断是否取消关注成功   
    }
});
```

**接口 code 列表**

| code        | 含义              |
|-------------|-------------------|
| `99`        | 已取消关注        |


### 5、搜索玩家

`Friendship.search`，当前用户使用精确uid搜索用户

```java
/**
 * 当前用户使用精确uid搜索用户
 *
 * @param uid      被搜索用户uid，4399 账号系统中的用户标识
 * @param listener 回调对象
 */
public static void search(String uid, OpeDataListener<FriendshipModel> listener);
```

调用示例：
```java
// uid：被搜索用户uid
Friendship.search(uid, new OpeDataListener<FriendshipModel>() {
    @Override
    public void onFinished(int code, @Nullable String message, @Nullable FriendshipModel data) {
        // 根据code进行判断是否获取到搜索结果，使用data.searchList
    }
});
```

### 6、私信邀请

`Friendship.invite`, 当前用户向指定用户发送私信邀请，私信内容目前支持由服务端配置
```java
/**
 * 当前用户向指定用户发送私信邀请
 *
 * @param activity Activity对象
 * @param uid      接收方用户uid
 * @param listener 回调对象
 */
public static void invite(Activity activity, String uid, OpeDataListener<Void> istener); 
```

调用示例：
```java
// uid：接收方用户uid
Friendship.invite(activity, uid, new OpeDataListener<Void>() {
    @Override
    public void onFinished(int code, @Nullable String message, @Nullable Void data) {
       // 根据code进行判断是否发送成功     
    }
});
```


## 四、API 详情

### OpeDataListener

```java

/**
 * 数据监听器
 */
public interface OpeDataListener<T> {
    /**
     * @param code    0为请求成功，并返回数据, 其他code均为失败，失败时数据可能为空
     * @param message 说明文案
     * @param data    返回数据
     */
    void onFinished(int code, @Nullable String message, @Nullable T data);
}
```


#### 通用 code 列表

| code        | 含义              |
|-------------|-------------------|
| `0`         | 成功，通用code    |
| `3`         | 失败，通用code    |
| `184`       | 网络问题          |

### FriendshipModel及其内部类

`FriendshipModel`及其内部类定义了好友系统中的数据模型

```java
public class FriendshipModel {
    /** 关注列表或者互关列表 */
    public List<Follow> follows = new ArrayList<>();
    /** 粉丝列表 */
    public List<Follower> followers = new ArrayList<>();
    /** 黑名单列表 */
    public List<PtUser> blackLists = new ArrayList<>();
    /** 搜索结果列表 */
    public List<Search> searchList = new ArrayList<>();
    /** 列表里的数据总数 */
    public int count;
    /** 是否有更多 0 否 1 是 */
    public boolean more;

    public static class Follow extends PtUser {
        /** 是否互关 0 否 1 是 */
        public boolean isFriend;
        /** 新增时间 */
        public String dateline;
        /** 头像更新时间 */
        public String facetime;
    }

    public static class Follower extends PtUser {
        /** 是否互关 0 否 1 是 */
        public boolean isFriend;
        /** 头像更新时间 */
        public String facetime;
    }

    public static class Search extends PtUser {
        /** 好友关系 1 我关注他 2 他关注我 3=2+1 互关 -1 自己 0 互不关注 */
        public int rela;
    }

    public class PtUser {
        /** 平台用户 id */
        public final String ptUid;
        /** 头像地址 */
        public final String sFace;
        /** 昵称 */
        public final String nick;
    }
}
```