五、最佳实践 #

#lfeng/wellplay/能力综述/奖励系统

本章节将介绍几种发奖场景。

1、简单发奖（推式） #

不使用回调策略，直接发放奖励。

1.1、打开奖励管理-奖励发放（推式），填写奖励说明并选择一个奖品，或者直接选择一个已有的奖励模板填充后再修改。 #

1.2、选择要发送奖励发出的目标角色（可以选择多个），并提交表单。 #

1.3、在游戏的社区中可以在奖励列表中看到奖励记录。 #

1.4、点击领取后，会触发SDK的回调，开发者可以根据实际情况处理业务。 #

// 监听领奖状态
[WPlay listenReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
    	// 用户点击领奖时回调
	    NSLog(@"%@",awardBody);
	    // "{"Reason":"Level","Comment":"AwardBody会完整的传给客户端"}"
	    // 来自控制台配置的奖励包体（AwardBody）
	    // 此时奖励尚未正式下发

		// 返回值表示回调配置中的自定义变量取值。
	    // 之后Wellplay会与后端服务器通讯确认发奖。

	    // 这里因为后台没有配置回调，所以可以直接返回nil。
		return nil;
	}
	getAwardBodyError:^NSString *(id error) {
		NSLog(@"getAwardBodyError == %@",errorDic);

		// return: 返回nil会弹出默认的错误提示。
		return @"self_define_msg";
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// 领奖成功时回调
		NSLog(@"returnBoby == %@",returnBoby);
		// 本次因为没有配置返回值，所以returnBody为空字符串。
	}
	rewardError:^NSString *(id error) {
		NSLog(@"rewardError == %@",errorDic);

		// return: 返回nil会弹出默认的错误提示。
		return @"self_define_msg";
	}
];

2、简单发奖（推式+返回包体） #

通过设置返回包体，返回包体中可以设置魔法变量和自定义变量，以便在客户端获得额外的数据。

2.1、打开奖励管理-奖励发放（推式），填写奖励说明并选择一个奖品，或者直接选择一个已有的奖励模板填充后再修改。 #

配置可以参考下图：

打开发奖回调配置，并选择ReturnBody，填入{"RewardID"="$(Reward.ID)"}，注意ReturnBody必须是合法的JSON字符串。

2.2、选择要发送奖励发出的目标角色（可以选择多个），并提交表单。 #

2.3、在游戏的社区中可以在奖励列表中看到奖励记录。 #

2.4、点击领取后，会触发SDK的回调，开发者可以根据实际情况处理业务。 #

// 监听领奖状态
[WPlay listenReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
		// 用户点击领奖时回调
		NSLog(@"%@",awardBody);
		// "{"Reason":"Level","Comment":"AwardBody会完整的传给客户端"}"
		// 来自控制台配置的奖励包体（AwardBody）
		// 此时奖励尚未正式下发

		// 返回值表示回调配置中的自定义变量取值。
		// 之后Wellplay会与后端服务器通讯确认发奖。

		// 这里后台配置的returnBody中没有自定义变量，所以仍然返回空即可。
		return nil;
	}
	getAwardBodyError:^NSString *(id error) {
		NSLog(@"getAwardBodyError == %@",errorDic);

		// return: 返回nil会弹出默认的错误提示。
		return @"self_define_msg";
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// 领奖成功时回调
		NSLog(@"returnBoby == %@",returnBoby);
		// "{"RewardID"="1330262728704003"}"
		// 由控制台配置的ReturnBody，填充了魔法变量后生成。
	}
	rewardError:^NSString *(id error) {
		NSLog(@"rewardError == %@",errorDic);

		// return: 返回nil会弹出默认的错误提示。
		return @"self_define_msg";
	}
];

3、回调发奖（推式+回调） #

回调发奖会在用户领奖时通知游戏服务器，由游戏服务器最终决定是否发奖。

3.1、打开奖励管理-奖励发放（推式），填写奖励说明并选择一个奖品，或者直接选择一个已有的奖励模板填充后再修改。 #

配置可以参考下图：

CallbackBodyType选择WWW_FORM_URL_ENCODED，Host填写play.example.com，CallbackURL填写https://play.example.com/reward/accept/callback，CallbackBody填写RewardID=$(Reward.ID)&Hello=$(x:Hello)&Foo=Bar

3.2、选择要发送奖励发出的目标角色（可以选择多个），并提交表单。 #

3.3、在游戏的社区中可以在奖励列表中看到奖励记录。 #

3.4、点击领取后，会触发SDK的回调，开发者可以根据实际情况处理业务。 #

因为加入了回调体系，这里会再模拟出被回调方（游戏方）服务器收到请求的情况。

// 监听领奖状态
[WPlay listenReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
    // 用户点击领奖时回调
    NSLog(@"%@",awardBody);
    // "{"Reason":"Level","Comment":"AwardBody会完整的传给客户端"}"
    // 来自控制台配置的奖励包体（AwardBody）
    // 此时奖励尚未正式下发

    // 返回值表示回调配置中的自定义变量取值。
    // 之后Wellplay会与后端服务器通讯确认发奖。

    // 这里后台配置的CallbackBody中有自定义变量$(x:Hello)，所以可以填充Hello的取值。
    return @{@"Hello":@"World"};
	getAwardBodyError:^NSString *(id error) {
		// ...暂时省略...
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// ...暂时省略...
	}
	rewardError:^NSString *(id error) {
		// ...暂时省略...
	}
];

3.5、这一部分应由开发服务器实现，以下仅模拟此时被回调方此时会收到请求的伪代码： #

func Reward(reqBody []byte) string{
		// 签名验证略
		// 根据Base64URL解码
		bodyData = make([]byte, base64.URLEncoding.DecodedLen(len(reqBody)))
		_, err = base64.URLEncoding.Decode(bodyData, reqBody)
		string content = string(bodyData)
		// 此时content = "RewardID=123456-654321&Hello=World&Foo=Bar"
		// 其中‘123456-654321’是Wellplay填充的魔法变量。
		// ‘World’是SDK回调中返回的自定义变量。

		// ......
		// ... 游戏服自身的业务逻辑
		// ......

		// 游戏服希望返回给客户端的消息（必须是JSON格式的字符串）
		return `{"MayDay":"July"}`
}

关于回调的详细说明请参考奖励回调通知

3.6、此时SDK的响应会回调rewardBlock部分。 #

// 监听领奖状态
[WPlay listenReward:^NSDictionary<NSString *,NSString *> *(NSString *awardBody) {
		// ...暂时省略...
	getAwardBodyError:^NSString *(id error) {
		// ...暂时省略...
	}
	rewardBlock:^(NSDictionary *returnBoby) {
		// 领奖成功时回调
		NSLog(@"returnBoby == %@",returnBoby);
		// `{"MayDay":"July"}`
		// 由游戏方服务器直接返回的结果（透传）
	}
	rewardError:^NSString *(id error) {
		// ...暂时省略...
	}
];

4、拉式发奖 #

拉式发奖通过设置领取条件的方式给游戏中的所有角色发奖，当角色满足条件时，可以领奖。

拉式发奖的奖励策略配置项与推式完全相同，这里不额外赘述了。

4.1、打开奖励管理-奖励发放（拉式），填写奖励说明并选择一个奖品，奖励策略配置与推式完全一样。 #

4.2、设置领取条件为属性名`Level`，比较类型`>=`，值`100`。 #

3、游戏社区中可以看到奖励列表中有该奖励。

由于当前角色的Level属性不满100，所以领取按钮是灰色的无法领取。
可以通过SDK接口或者控制台修改该角色的属性到满足条件。

4、当角色满足领奖条件时，奖励列表效果如下：

由于领取条件的判定是领取时判定的，所以如果当前角色曾经满足条件，但由于某些原因后续又不满足条件了，则后续不满足条件时是无法领取奖励的。