开放接口需求 #

#lfeng/wellplay/客户端集成/Android

开放接口指WellplaySDK作为三方库直接开放的接口，提供给SDK调用方使用的公开接口。

本节需求以描述业务需求为目的，由于语言特性及设计特点，附带iOS的代码仅供参考，如有疑问请及时沟通。

关于文档中Error类型，请参考Android中的常规实现，可以描述清楚原因即可。

1、初始化 #

1.1、配置密钥（自动）。 #

应用初始化时，设置默认的APPID和APPSecret，并在需要时自动完成通讯签名。

APPID：string，应用的ID
APPSecret：string，应用的密钥

[WPlay registerWPlayWithAppID:@"your_app_id" appSecret:@"your_app_secret"];

1.2、配置密钥（手动） #

应用初始化时，配置默认的APPID，并提供一个回调接口，在应用需要签名时，总是由SDK拼接好需要签名的字符串，通过回调接口返回需要使用APPSecret进行签名的原始字符串StrToSign，由开发者根据签名算法自行使用APPSecret对StrToSign进行签名，并将签名结果返回，以便WellplaySDK可以继续运行。

APPID：string，应用的ID
CustomSignCallback：string function(strToSign string)，需要签名时的回调接口
- strToSign：string，待签名的字符串
  - return：string，自行完成签名后的字符串

[WPlay registerWithAppID:@"your_app_id" customSignBlock:^NSString *(NSString * strToSign) 		{
	// 开发者自行完成签名过程（例如交给自己的服务器完成）
	signedStr = [YourLib yourSignMethod:strToSign];

	// 返回签名结果
	return signedStr
}];

自动签名和手动签名仅一个生效，如果设置了自动签名（APPSecret），则不会调用手动签名的接口。

2、一般配置 #

给出合适的设置接口（如属性）即可。

isScreenLandscape：bool，需在社区被打开前配置好，控制社区横屏显示还是竖屏显示，默认竖屏（False）。
isShowWithFullScreen：bool，社区是否全屏显示，默认窗口（False）。
isHideReward：bool，是否在个人中心隐藏奖励入口，默认显示（False）。
isHideFeedback：bool，是否在个人中心隐藏反馈入口，默认隐藏（False）。

3、登录 #

3.1、登录成功回调 #

设置当用户成功登录社区后会触发的回调：

OnLoginCallback：用户登录成功时触发回调。
- UserID：string，当前登录成功的用户ID。
  - return：无返回值。

[WPlay didLoginWPlay:^(NSString *userID) {
	// 已登录社区
	// userID: 由Wellplay生成的当前用户的唯一编号，为36位以内的字符串。
}];

3.2、注销成功回调 #

当用户成功注销登录时触发的回调：

OnLogoutCallback：用户注销登录时触发回调。
- return: 无返回值

[WPlay didLogoutWPlay:^{
    // 已退出登录社区
}];

3.3、强制注销 #

强制注销当前用户的登录状态：

/**
 退出登录
*/
[WPlay logout];

4、社区 #

4.1、展示社区 #

调用后会展示社区界面。

[WPlay show];

第一次展示社区前应配置好社区的初始化设置。

4.2、隐藏社区 #

调用后会隐藏社区窗口。

[WPlay dissmiss];

4.3、社区隐藏后回调 #

社区窗口被隐藏后触发的回调：

OnDismissedCallback：窗口隐藏时触发回调。
- return: 无返回值

[WPlay didDismissedWPlay:^{
		// 已经消失后的回调
}];

5、角色 #

5.1、获取当前玩家登陆的角色回调 #

如果使用了Wellplay社区中涉及角色的功能，每当需要获取当前登录角色时，SDK总是会回调该接口，以确保获取最新的角色ID：

OnGetRoleIDCallback：需要获取角色ID时触发回调
- RoleID：string，角色的ID。
  - return: 无返回值

[WPlay giveRoleID:^NSString *{
		// 可以返回nil表示当前未登录角色
		return @"your_wellplay_role_id";
}];

如果返回nil，表示当前未登录角色，与角色相关的界面、列表（如签到界面、奖励列表）会无法打开，以避免误操作。

5.2、创建角色 #

在Wellplay中创建一个角色，并初始化其属性。

PropertyMap：map<string, string>，角色默认初始化的属性键值对。
OnSuccessCallback：成功时的回调
- RoleID：string，新建角色的ID。
- SuccessPropertyMap：map<string, string>，设置成功的属性键值对。
- FailurePropertyMap：map<string, string>，设置失败的属性键值对
OnFailureCallback：失败时回调
- Error：服务器返回的错误。

[WPlay createRoleWithPropertyMap:@{@"PropertyKey":@"PropertyValue"}
	success:^(NSString * roleID，NSDictionary* succPropertyMap, NSDictionay* failurePropertyMap) {
		// 创建成功回调
	}
	failure:^(id error) {
		// 创建失败回调
	}
];

5.3、修改角色属性 #

修改或设置Wellplay中的指定角色的属性值。

RoleID：要修改的角色的ID。
PropertyMap：map<string, string>，角色默认初始化的属性键值对。
OnSuccessCallback：成功时的回调
- SuccessPropertyMap：map<string, string>，设置成功的属性键值对。
- FailurePropertyMap：map<string, string>，设置失败的属性键值对
OnFailureCallback：失败时回调
- Error：服务器返回的错误。

[WPlay updateRoleWithRoleID:@"your_wellplay_role_id"
	propertyMap:@{@"PropertyKey":@"PropertyValue"}
	success:^(NSDictionary* succPropertyMap, NSDictionay* failurePropertyMap) {
		// 修改角色属性成功时回调
	}
	failure:^(id error) {
		// 修改角色属性失败时回调
	}
];

5.4、删除角色 #

删除Wellplay中的指定角色。

RoleID：要删除的当前用户的角色ID。
OnSuccessCallback：执行成功。
OnFailureCallback：执行失败。

[WPlay deleteRoleWithRoleID:@"your_wellplay_role_id"
	success:^{
		// 删除角色成功时回调
	}
	failure:^(id error) {
		// 删除角色失败时回调
	}
];

6、奖励 #

6.1、普通奖励回调 #

监听并处理Wellplay社区中，奖励列表的领取奖励业务的回调。

OnRewardCallback：玩家请求领奖时回调（调用/reward/get/info成功）
- AwardBody：string，控制台配置的关于本次奖励的参数
  - return：map<string, string>，设置了回调接口，可以通过该字典返回自定义变量
OnRewardErrorCallback：请求领奖失败时回调（调用/reward/get/info失败时）
- Error: 调用失败的异常
OnAcceptCallback：服务器确认发奖后回调（调用/reward/accept/by/role成功）
- ReturnBodyMap：map<string, string>，接口返回的参数键值对。
  - return：无返回值
OnAcceptErrorCallback：请求服务器确认发奖失败时回调（调用/reward/accept/by/role失败）
- Error: 调用失败的异常

[WPlay listenReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
		// 玩家请求领奖时回调

		// awardBody: 控制台配置的关于本次奖励的参数
		// 由服务器透传到客户端，可以辅助客户端响应

		// 注意：此接口被回调时，仅表示玩家请求领奖
		// 便于客户端做一些前期准备，此时奖励尚未确认发放（服务器记录未更新）

		// return: 如果设置了回调接口，可以通过该字典返回自定义变量
		return @{@"callback_self_defined_key":@"callback_self_defined_value"};
	}
	getAwardBodyError:^NSString *(id error) {
		// 请求领奖失败时回调

		// 如果返回非空的字符串，则会替换默认提示玩家领奖失败的消息内容
		return @"msg_display_to_player";
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// 服务器确认发奖后回调

		// returnBoby: 如果控制台配置了returnBody，则该值由控制台配置的returnBody决定。
		// 如果控制台配置了Callback方法，则该值为回调游戏服务器后，由游戏服务器返回的JSON解码结果。

		// 客户端可以在该回调中将奖励发放给玩家
	}
	rewardError:^NSString *(id error) {
		// 确认领奖失败时回调

		// 如果返回非空的字符串，则会替换默认提示玩家领奖失败的消息内容
		return @"msg_display_to_player";
	}
];

7、签到 #

7.1、展示签到界面 #

弹出签到界面。

[WPlay showCheckInView:^(id error) {
	// 如果展示界面失败则触发回调
}];

7.2、处理签到奖励回调 #

7.2.1、处理普通签到奖励回调 #

OnCheckInRewardCallback：玩家请求签到领奖时回调（调用/check_in/get/info/by/role成功）
- AwardBody：string，控制台配置的关于本次奖励的参数
  - return：map<string, string>，设置了回调接口，可以通过该字典返回自定义变量
OnCheckInRewardErrorCallback：请求领奖失败时回调（调用/check_in/get/info/by/role失败时）
- Error: 调用失败的异常
OnAcceptCheckInRewardCallback：服务器确认发奖后回调（调用/check_in/create/by/role成功）
- ReturnBodyMap：map<string, string>，接口返回的参数键值对。
  - return：无返回值
OnAcceptCheckInRewardErrorCallback：服务器确认发奖失败（调用/check_in/create/by/role失败）
- Error: 调用失败的异常

[WPlay listenCheckInReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
		// 玩家请求领奖时回调

		// awardBody: 控制台配置的关于本次奖励的参数
		// 由服务器透传到客户端，可以辅助客户端响应

		// 注意：此接口被回调时，仅表示玩家请求领奖
		// 便于客户端做一些前期准备，此时奖励尚未确认发放（服务器记录未更新）

		// return: 如果设置了回调接口，可以通过该字典返回自定义变量
		return @{@"callback_self_defined_key":@"callback_self_defined_value"};
	}
	getAwardBodyError:^NSString *(id error) {
		// 请求领奖失败时回调

		// 如果返回非空的字符串，则会替换默认提示玩家领奖失败的消息内容
		return @"msg_display_to_player";
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// 服务器确认发奖后回调

		// returnBoby: 如果控制台配置了returnBody，则该值由控制台配置的returnBody决定。
		// 如果控制台配置了Callback方法，则该值为回调游戏服务器后，由游戏服务器返回的JSON解码结果。

		// 客户端可以在该回调中将奖励发放给玩家
	}
	rewardError:^NSString *(id error) {
		// 确认领奖失败时回调

		// 如果返回非空的字符串，则会替换默认提示玩家领奖失败的消息内容
		return @"msg_display_to_player";
	}
];

7.2.2、处理额外签到奖励回调

OnExtraCheckInRewardCallback：玩家请求签到领奖时回调（调用/check_in/get/info/by/role成功）
- AwardBody：string，控制台配置的关于本次奖励的参数
  - return：map<string, string>，设置了回调接口，可以通过该字典返回自定义变量
OnExtraCheckInRewardErrorCallback：请求领奖失败时回调（调用/check_in/get/info/by/role失败时）
- Error: 调用失败的异常
OnAcceptExtraCheckInRewardCallback：服务器确认发奖后回调（调用/check_in/accept/reward/by/role成功）
- ReturnBodyMap：map<string, string>，接口返回的参数键值对。
  - return：无返回值
OnAcceptExtraCheckInRewardErrorCallback：服务器确认发奖失败（调用/check_in/accept/reward/by/role失败）
- Error: 调用失败的异常

[WPlay listenExtraCheckInReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
		// 玩家请求领奖时回调

		// awardBody: 控制台配置的关于本次奖励的参数
		// 由服务器透传到客户端，可以辅助客户端响应

		// 注意：此接口被回调时，仅表示玩家请求领奖
		// 便于客户端做一些前期准备，此时奖励尚未确认发放（服务器记录未更新）

		// return: 如果设置了回调接口，可以通过该字典返回自定义变量
		return @{@"callback_self_defined_key":@"callback_self_defined_value"};
	}
	getAwardBodyError:^NSString *(id error) {
		// 请求领奖失败时回调

		// 如果返回非空的字符串，则会替换默认提示玩家领奖失败的消息内容
		return @"msg_display_to_player";
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// 服务器确认发奖后回调

		// returnBoby: 如果控制台配置了returnBody，则该值由控制台配置的returnBody决定。
		// 如果控制台配置了Callback方法，则该值为回调游戏服务器后，由游戏服务器返回的JSON解码结果。

		// 客户端可以在该回调中将奖励发放给玩家
	}
	rewardError:^NSString *(id error) {
		// 确认领奖失败时回调

		// 如果返回非空的字符串，则会替换默认提示玩家领奖失败的消息内容
		return @"msg_display_to_player";
	}
];

本接口结构与普通签到奖励基本一致，仅底层API接口有变动。

8、帮助 #

8.1、打开帮助主视图 #

打开帮助视图的首页。

[WPlay showHelpView];

8.2、打开指定路径的帮助

帮助文档采用树形结构管理，开发者可以通过指定目录路径的方式打开指定文档。

CategoryList：[]string，按顺序传入x级目录路径，如果目录下存在文档，则打开文档；如果不存在文档，则打开对应的目录列表。
OnFailureCallback：异常时触发的回调
- Error：调用失败的异常

[WPlay showHelpDetailViewWithCatalogueArray:@[@"新手教程", @"注册说明"]
	failure:^(id error) {
		// 未能打开预期的目录（可能是目录名填错了，或者后台删除了某个目录）
	}];

8.2.1、例子

假设当前已在后台配置如下目录结构的帮助文档：

—— 新手教程
|—— 注册说明
|—— 登录说明
—— 游戏规则
|—— 技能系统

如果想打开新手教程：

// 此时会转跳到"新手教程"的子目录列表
[WPlay showHelpDetailViewWithCatalogueArray:@[@"新手教程"]
	failure:^(id error) {

	}];

如果想打开注册说明：

// 此时会转跳到"注册说明"对应的文档。
[WPlay showHelpDetailViewWithCatalogueArray:@[@"新手教程", @"注册说明"]
	failure:^(id error) {

	}];

如果输入错误（后台并未配置请求的二级目录，但一级目录存在）：

[WPlay showHelpDetailViewWithCatalogueArray:@[@"新手教程", @"不知道什么"]
	failure:^(id error) {
		// 此时“新手教程”存在
		// 实际打开“新手教程”，并回调异常
	}];

如果输入错误（后台并未配置请求的一级目录）：

[WPlay showHelpDetailViewWithCatalogueArray:@[@"无敌教程", @"登录说明"]
	failure:^(id error) {
		// 此时“无敌教程”不存在
		// 实际打开帮助文档首页，并回调该异常。
	}];

9、公告 #

9.1、展示公告 #

尝试更新并弹出公告窗体。

[WPlay showAnnouncement];