1 准备

1.1 准备环境

Csdk提供资源

• 1.0 [核心包]UE4V2 SDK 插件包下载见修订说明
• 2.0 GME和GVoice语音适配器插件包联系郑学强
• 3.0 联系郑学强获取AppID和AppKey

接入方提供

• 准备联网正常的的 PC 安卓设备
• 准备研发环境

• 研发环境支持平台

  平台	SDK 及兼容性
  编辑器	windows 10, macOS 10.12+
  编译构建	windows 10, macOS 10.12+
  Android	兼容 Android 4.0及以上
  iOS	兼容 XCode12 ~ XCode14

• 开发语言

  用途	语言	版本要求
  业务接入	Cpp	C++ 11
  构建接入	Cpp	C++ 11

1.2 接入参数

• 获取到 应用ID 和 应用密钥，准备接入必须要的各项参数

接入参数	参数描述	是否必须	例子
Url	网关服务 地址	是	服务器地址 聊天测试服地址：http://csdk-test.yingxiong.com/gateway
ProductId	应用ID	是	联系学强或者CSDK控制台 (opens new window)自行配置
ProductKey	应用密钥	是	联系学强或者CSDK控制台 (opens new window)自行配置
AppID	语音 SDK AppID 按功能确认是否需要语音	否	联系学强
AppKey	语音 SDK AuthKey 按功能确认是否需要语音	否	联系学强

WARNING

• 以上所有 参数 应用ID和应用密钥，初始化SDK客户端时需要设置，请谨慎保存
• 如为私有部署，则 网关服务 地址 和 网关服务 端口 需要部署完成后修改

1.3 接入步骤

获取资源

接入打包

开发调试

出包确认

1.4 接入流程

2.1 初始化SDK

因为涉及到UObject创建，请保证 SDK 所有接口都在主线程调用

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FCsdkInitResult,const int32, ErrorCode,const FString&, ErrorMsg);
UCLASS()
class CSDKRUNTIME_API UCsdkInitAction : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 
	 * @param WorldContextObject UObject上下文
	 * @param ProductId 产品Id
	 * @param ProductKey 产品Key
	 * @param Url 服务器地址
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Init")
	static UCsdkInitAction* CsdkInit(UObject* WorldContextObject,const FString& ProductId,const FString& ProductKey,const FString& Url);

	/** Execute the actual operation */
	virtual void Activate() override;

	/**
	 * @brief 初始化回调
	 */
	UPROPERTY(BlueprintAssignable)
	FCsdkInitResult Completed;

private:
	FString ProductId;
	FString ProductKey;
	FString Url;
};

2.2 角色登陆

• 调用

参数	是否必须	参数描述
UserId	是	角色唯一识别码，由RoleId和SeverId共同确认一个角色
RoleName	否	角色名
Gender	否	角色性别
AvatarUrl	否	角色头像
Extra	否	额外参数

• UserId介绍 | 属性 | 含义 | 说明 | | --- |------|----------------------------------------------------------------------------------------------------------------------| | RoleId | 角色ID | 当前区服玩家注册的角色ID |
  | ServerId | 区服ID | 接收者所在的区服ID |

• 回调

下标	类型	参数描述
0	int32	状态码 2000 为成功，其他见 状态码表
1	FString	返回描述

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FCsdkUserLoginCallBack,const int32,ErrorCode, const FString&, ErrorMsg);
UCLASS()
class CSDKRUNTIME_API UCsdkUserLogin : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 聊天用户登录
	 * @param WorldContextObject 上下文
	 * @param User 登录用户信息
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Login")
	static UCsdkUserLogin* CsdkUserLogin(UObject* WorldContextObject,const FCsdkUser& User);

	virtual void Activate() override;
	
	/**
	 * @brief 登录回调
	 */
	UPROPERTY(BlueprintAssignable)
	FCsdkUserLoginCallBack Completed;

private:
	FCsdkUser User;
};

2.3 角色登出

UFUNCTION(BlueprintCallable, Category = "CSDK|Login",meta = ( WorldContext="WorldContextObject"))
static  void CsdkLogout(UObject* WorldContextObject);

3 会话操作

3.1 监听会话变更

• 添加对话更新观察，在对话更新的时候会给最新的对话数据

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnSessionChanged,const ECsdkSessionChanged::Type, Type,UCsdkSession*,NewSession);
/**
* @brief 会话变更事件
*/
UPROPERTY(BlueprintAssignable,Category="CSDK|Session")
FOnSessionChanged OnSessionChanged;

3.2 查询最近会话列表

DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FCsdkGetSessionListResult, const int32, ErrorCode, const FString&, ErrorMsg,
                                               const TArray<UCsdkSession*>&, SessionList);

UCLASS()
class CSDKRUNTIME_API UCsdkGetSessionList : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 获取会话列表
	 * @param WorldContextObject 上下文环境
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Session")
	static UCsdkGetSessionList* GetSessionList(UObject* WorldContextObject);

	virtual void Activate() override;

	UPROPERTY(BlueprintAssignable)
	FCsdkGetSessionListResult Completed;

};

3.3 获取指定的最近会话

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

• FCsdkSessionId简介

属性	含义	说明
ReceiverId	接收者ID	接收者为用户，则为用户角色ID,接收者为聊天室，则为聊天室ID。同一个 ECsdkSessionType::Type下，ReceiverId必须唯一
ServerId	区服ID	接收者所在的区服ID，如果是跨服频道，则使用_CrossServer_这个特殊的ID
ECsdkSessionType::Type	会话类型	参见下表

	/**
	 * @brief 查找会话
	 * @param SessionId 会话唯一ID
	 * @return 会话对象，找不到此会话则为空
	 */
	UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
	static UCsdkSession* FindSession(const FCsdkSessionId& SessionId);

3.4 创建最近会话

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

   	/**
	 * @brief SDK 提供创建或查找会话的接口，必定可以获取一个会话实例
	 * @param SessionId 会话唯一ID
	 * @return 会话对象
	 */
	UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
	static UCsdkSession* CreateOrFindSession(const FCsdkSessionId& SessionId);

3.5 删除最近会话

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

• 回调

下标	参数	参数描述
0	int32	状态码 2000 为成功，其他见 状态码表
1	FString	返回描述

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FCsdkDeleteSessionResult, const int32, ErrorCode, const FString&, ErrorMsg);

/**#
 * 
 */
UCLASS()
class CSDKRUNTIME_API UCsdkDeleteSession : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 删除会话
	 * @param WorldContextObject 上下文
	 * @param UniqueId 会话Id
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Session")
	static UCsdkDeleteSession* DeleteSession(UObject* WorldContextObject,const FCsdkSessionId& UniqueId);
	
	virtual void Activate() override;
	
	/**
	 * @brief 回调
	 */
	UPROPERTY(BlueprintAssignable)
	FCsdkDeleteSessionResult Completed;
	
private:
	FCsdkSessionId SessionId;
};

4 消息收发模块

4.1 注册聊天更新监听

• 调用示例

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnNewMessagesReceived,const FCsdkSessionId&,SessionId,const TArray<UCsdkMessageBase*>&,NewMsgs);
/**
    * @brief 新消息通知
    */
UPROPERTY(BlueprintAssignable,Category="CSDK|Message")
FOnNewMessagesReceived OnNewMessagesReceived;

4.2 聊天数据获取

拉取消息历史（云端历史消息查询）

下标	参数类型	参数描述
0	int32	状态码 2000 为成功，其他见状态码表
1	FString	返回描述
2	struct	会话ID
3	struct数组	历史消息

DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FCsdkPullMsgResult,const int32, ErrorCode ,const FString&,ErrorMsg,const FCsdkSessionId&, SessionId, const TArray<UCsdkMessageBase*>&, Messages);
/**
 * 
 */
UCLASS()
class CSDKRUNTIME_API UCsdkPullMsg : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 拉取消息
	 * @param WorldContextObject 上下文
	 * @param SessionId 会话ID
	 * @param AnchorMsgId 锚点消息ID，如拉取最新消息，则为空
	 * @param DesiredPullCount 期望拉取数量
	 * @param Direction 方向
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Message")
	static UCsdkPullMsg* PullMsg(UObject* WorldContextObject, const FCsdkSessionId& SessionId, const FString& AnchorMsgId, const int32 DesiredPullCount = 30,
	                             const ECsdkMsgPullDirection Direction = ECsdkMsgPullDirection::Forward);

	virtual void Activate() override;
	UPROPERTY(BlueprintAssignable)
	FCsdkPullMsgResult Completed;
private:
	FCsdkSessionId SessionId;
	FString AnchorMsgId;
	int32 DesiredPullCount = 0;
	ECsdkMsgPullDirection Direction = ECsdkMsgPullDirection::Forward; 
};

4.3 聊天发送

• 发送流程

• 1 创建对应类型消息

/**
* @brief 创建一个待发送的客户端文本消息
* @param Content 文本内容
* @param Extra 扩展字段
* @return 文本消息
*/
UFUNCTION(BlueprintCallable,Category = "CSDK|Message")
static UCsdkTextMessage* NewTextMsg(const FString& Content, const TMap<FString, FString>& Extra);

/**
* @brief 创建一个待发送的客户端语音消息
* @param Url 语音文件Url
* @param Duration 语音时长
* @param Extra 扩展字段
* @return 语音消息
*/
UFUNCTION(BlueprintCallable,Category = "CSDK|Message")
static UCsdkVoiceMessage* NewVoiceMsg(const FString& Url,const float Duration, const TMap<FString, FString>& Extra);
/**
* @brief 创建一个待发送的客户端语音消息
* @param Title 用于敏感词检查的字段
* @param Data 自定义字符串
* @param Extra 扩展字段
* @return 自定义消息
*/
UFUNCTION(BlueprintCallable,Category = "CSDK|Message")
static UCsdkCustomMessage* NewCustomMsg( const FString& Title,const FString& Data, const TMap<FString, FString>& Extra);

• 2 发送消息

• 调用

参数	是否必须	参数描述
SessionId	是	会话ID
CsdkMessage	是	消息对象

• 回调

下标	参数类型	参数描述
0	int32	状态码 2000为成功，其他见状态码表
1	FString	错误码

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FCsdkSendMsgResult,const int32, ErrorCode, const FString&, ErrorMsg);
/**
 * 
 */
UCLASS()
class CSDKRUNTIME_API UCsdkSendMsg : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 发送消息到服务器
	 * @param WorldContextObject 上下文
	 * @param SessionId 会话ID
	 * @param CsdkMessage 消息对象
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Message|Send")
	static UCsdkSendMsg* SendMsg(UObject* WorldContextObject, const FCsdkSessionId& SessionId,UCsdkMessageBase* CsdkMessage);
	virtual void Activate() override;
	
	UPROPERTY(BlueprintAssignable)
	FCsdkSendMsgResult Completed;

private:
	FCsdkSessionId SessionId;
	UPROPERTY()
	UCsdkMessageBase* CsdkMessage;
};