一、奖励系统综述 #
#lfeng/wellplay/能力综述/奖励系统
应用场景 #
奖励系统是Wellplay提供给开发者用于实现游戏中发奖的可选模块。
奖励系统可以帮助开发者实现将特定的奖品展示并发给特定（或者符合某些条件）的角色的问题。
开发者可以通过在Wellplay的管理后台中通过发送奖品给指定角色的方式将消息发给SDK，玩家在SDK中触发领奖操作时，Wellplay会根据开发者的配置把相关的数据回调给游戏客户端或者游戏服务器，开发者需要在相关回调中自行处理相关的逻辑。
目前，若要使用
奖励系统，则必须启用角色系统。
核心流程图 #
角色（Role） #
角色是定义发奖目标最小单位，开发者可以根据自己游戏的实际情况，将一个角色直接看做游戏中玩家的某个区服中的角色，没有区服角色概念的游戏也可以给该玩家的账户默认创建一个角色作为发奖目标。
奖励系统中的奖品是发给角色的，所以希望使用奖励系统的开发者应确保在业务中已经设计角色的创建/维护逻辑，以便奖励系统可以正常运作。
一个玩家可以有多个角色，每个角色都可以独立领奖，由开发者自行维护。
关于角色的更多说明请参考角色系统综述
奖品（Reward） #
奖品是为了便于奖励发放而设计的基本单位，一种奖品可以表现为游戏中的一件物品，也可以是一个礼包，奖品的实际内容需要由开发者自己实现。
一个奖品的
标题、图片属性，会展示给玩家。
查看奖品 #
开发者可以在控制台查看已有奖品的配置。
| 字段名 | 说明 |
|---|---|
| 奖品标题 | 玩家在前端部分界面看到的奖品名称；长度为1~16位以下的合法UTF8字符 |
| 奖品图片 | 一个奖品最多可以附带9张图片，会在查看奖励时展示给玩家 |
| 奖品备注 | 允许备注对该奖品的说明，仅可在后台查看；长度应为0~1000位以下的合法UTF8字符 |
| 奖励包体（AwardBody） | 默认的奖励包体，开发者自定义的字符串，会在玩家领奖时完整地透传传给客户端，便于客户端知道即将收到的奖品内容，仅可在后台查看，发奖时作为默认值使用，可以修改；长度应为0~1000位以下的合法UTF8字符 |
创建奖品 #
开发者可以在控制台创建新的奖品。
修改奖品 #
开发者可以在控制台修改已有奖品的标题、备注、图片和奖励包体，修改会立即生效并影响所有与该奖品相关的发奖记录。
删除奖品 #
开发者可以在控制台删除已有的奖品，被删除的奖品不会影响已领取的奖励，但会导致所有与该奖品有关的奖励无法再领取。
奖励 #
奖励描述的是一次具体的发奖行为，一种奖品可以被不同的奖励所引用。
奖励一般参数说明 #
奖励一般发奖时填写的参数。
| 参数 | 说明 |
|---|---|
| 奖励名 | 在客户端的奖励列表中展示的标题 |
| 奖励正文 | 在客户端的奖励列表中，展示的对本次奖励的介绍 |
| 生效时间 | 允许领取本次奖励的时间 |
| 过期时间 | 本次发放的奖励过期的时间 |
| 奖励包体（AwardBody） | 请求领奖时，由Wellpaly透传给客户端的参数；长度在1000以内的合法utf8字符 |
| 返回包体（ReturnBody） | 确认领奖后，自定义Wellpaly最终返回給客户端的数据；支持 ~魔法变量~ 和 ~自定义变量~；ReturnBody 要求是合法的 JSON 文本。例如：{"Hello":"$(x:Hello)","RoleID":"$(Role.ID)"} |
回调参数说明 #
回调参数仅在开发者需要Wellpaly在玩家每次领奖时，回调游戏服务器时配置。
| 参数 | 说明 |
|---|---|
| CallbackURL | 确认领奖时，Wellpaly向游戏服务器发送POST请求的URL；必须是公网上可以正常进行 POST 请求并能响应 HTTP/1.1 200 OK 的有效 URL；另外，为了给客户端有一致的体验，我们要求 CallbackURL 返回包 Content-Type 为 application/json，即返回的内容必须是合法的 JSON 文本。出于高可用的考虑，本字段允许设置多个 CallbackURL（用英文符号 ; 分隔），在前一个 CallbackURL 请求失败的时候会依次重试下一个 CallbackURL。一个典型例子是：http://<ip1>/callback;http://<ip2>/callback，并同时指定下面的 CallbackHost 字段。在 CallbackURL 中使用 ip 的好处是减少对 dns 解析的依赖，可改善回调的性能和稳定性。指定 CallbackURL，必须指定 CallbackBody，且值不能为空 |
| CallbackHost | 确认领奖时，Wellpaly向游戏服务器发送POST请求的Host值；与 CallbackURL 配合使用，仅当设置了 CallbackURL 时才有效 |
| CallbackBody | 确认领奖时，Wellpaly向业务服务器发送Content-Type: application/x-www-form-urlencoded的 POST 请求。业务服务器可以通过直接读取请求的 query 来获得该字段；支持 ~魔法变量~ 和 ~自定义变量~；CallbackBody 要求是合法的 url query string。例如Hello=$(x:Hello)&Foo=$(Role.ID)。如果CallbackBodyType指定为application/json，则CallbackBody应为JSON格式，例如：{“Hello":"$(x:Hello)","RoleID":"$(Role.ID)"} |
| CallbackBodyType | 确认领奖时，Wellpaly向业务服务器发送回调通知CallbackBody的Content-Type。默认为application/x-www-form-urlencoded，也可设置为 application/json |
注意事项：
- 所有文本参数必须采用合法的UTF8编码，否则可能导致无法正常工作。
回调参数和ReturnBody参数不能同时使用，如果采用了回调策略，则由请求CallbackURL返回的内容会作为ReturnBody透传给客户端。
参考效果 #
发奖 #
发奖是指将指定的某种奖品发给指定角色的行为过程，Wellplay提供一些基本的规则，以便开发者可以快速实现发奖的业务，也提供了接口允许开发者根据自己业务情况细化定制发奖逻辑。
奖励 #
奖励是一次奖品发放的记录，包括本次的奖品、发奖的规则、涉及的角色等信息。
推式发奖 #
推式发奖允许开发者从当前应用的角色列表中筛选指定的角色进行发奖，一般适用于小规模的发奖场景，给予明确的目标角色以奖励，如参加游戏活动的获奖玩家。
只有发奖过程中选中的角色可以在SDK的奖励列表中看到奖励记录，玩家可以在
奖励生效周期内领取奖励，单次推式发奖的角色数量有上限。
目前一个角色最多允许有30个未领取的推式奖励，如果需要更多，可以联系客服。
拉式发奖 #
拉式发奖适合更通用的发奖场景，允许开发者定义多个基于角色属性的奖品领取条件，在奖励生效期间，所有角色都可以看到该奖励记录，但只有符合条件的角色可以点击领取按钮领取该奖励。
发奖条件 #
拉式发奖提供对角色属性的基础比较方法，包括==、!=、>、<、>=、<=。其中==和!=可以用于比较所有类型的属性值（包括int64和string），其他运算符仅支持int64。
如果业务上有比较复杂的发奖逻辑，请在业务接口中自行实现。