自定义活动逻辑(抽奖等)

> 通过自定义逻辑接口能力，可以实现活动过程与企业应用深度打通，定制符合客户业务场景的营销闭环。

# 自定义抽奖或游戏规则
1. 企业可以自定义防刷逻辑；
1. 企业可以根据用户画像按用户分区调整获奖比例；

## 使用步骤

1. 根据规范开发抽奖逻辑接口;
2. 登录控制台->应用管理->互动编辑器->自定义规则配置项中添加接口地址;
3. 在制作活动时，选择自定义抽奖逻辑;

## 接口开发说明

- 请求方式：POST
- Content-Type：application/json
- 请求参数
| 参数名 | 是否必须 | 参数类型 | 参数说明 |
| --- | --- | --- | --- |
| timestamp | 必须 | String | 请求时的时间戳 |
| nonce | 必须 | String | 随机字符串 |
| signature | 必须 | String | 请求签名 |
| msgEncrypt | 必须 | String | 加密后的消息 |

- msgEncrypt内容如下：
| 参数名 | 是否必须 | 参数类型 | 参数说明 |
| --- | --- | --- | --- |
| id | 必须 | String | 活动id |
| mobile | 否 | String | 手机号（参与类型为手机用户时） |
| openId | 否 | String | 参与用户为（微信、自定义渠道时） |
| unionId | 否 | String | 微信unionId，参与用户为（微信、自定义渠道时） |
|channelKey | 否 | String | 渠道key,内容为自定义访客用户信息返回 |
| drawNum | 否 | int | 连抽次数（开启连抽才会有） |
| corpOpenId | 否 | String | 企业openId，平台型企业使用 |
|  |  |  |  |

- msgEncrypt解密后内容如下：
```json
手机授权：
{
	"id":10086,
  	"code":"abcdefg",
  	"mobile":"183********" ,// 明文
  	"drawNum":3 // 只有连抽才有此参数
}
微信授权：
{
	"id":10086,
  	"code":"abcdefg",
  	"openId":"微信openid",
  	"nickName":"微信昵称",
  	"gender":"微信性别",
  	"city":"微信城市，非地理位置",
  	"country":"国家",
  	"drawNum":3 // 只有连抽才有此参数
}
自定义用户:
{
	"id":10086,
  	"code":"abcdefg",
  	"openId":"openid",// 对接方提供的用户唯一标识
  	"drawNum":3 // 只有连抽才有此参数
}
```

- 接口返回值
| 参数名 | 是否必须 | 类型 | 备注 |
| --- | --- | --- | --- |
| code | 是 | String | 返回200 表示成功 |
| msg | 否 | String | 错误信息 |
| lottery | 是 | int |  1：可参与抽奖或游戏 <br/> 2：不满足参与资格，给出引导信息和链接 <br/>3：不中奖，且无引导信息和链接(限抽奖) <br/>4：中奖并给出奖品等级(限抽奖) |
| winScope | 否 | array |  指定用户中奖范围，1对应一等奖，2对应二等奖，以此类推。当用户所中奖项等级不在该范围内则提示不中奖，在lottery为1时有效 |
|- |- |- |- |
| message | 否 | String | 不可参与提示信息. 当lottery字段为2时，该字段为必须（长度：弹窗内可展示119个字符超过后可滑动查看） |
| url | 否 | String | 不可参与引导链接，引导用户点击，不返回该字段则关闭提示不跳转 |
|- |- |- |- |
| prizeLevel | 否 | int | 中奖时的奖品等级；从0开始，0代表一等奖，1代表二等奖... |
| prizeCode | 否 | String | 奖品代码(各奖项配置的奖品代码) |
| prizeName | 否 | String | 奖品名称(优先展示返回的奖品名称，如果没有返回默认取奖品设置的名称) |
| dynData | 否 | JsonObject | 用户自定义返回参数,奖品兑奖方式为外部跳转时会携带跳转 |
|- |- |- |- |
| lotteryList | 否 | JsonArray | 连抽的多个中奖结果返回 |
| lotteryList[n].isWin | 是 | int | 1：中奖，0：不中奖 |
| lotteryList[n].prizeLevel | 否 | int | 中奖时的奖品等级 |
| lotteryList[n].prizeCode | 否 | String | 中奖时奖品代码(各奖项配置的奖品代码) |
| lotteryList[n].dynData | 否 | JsonObject |用户自定义返回参数,奖品兑奖方式为外部跳转时会携带跳转 |

- 说明：当接口响应超时或返回数据错误时，抽奖逻辑会中止，提示用户稍后再试。**lottery返回2的时候不会扣减用户的参与次数，返回3会扣减用户的参与次数。**
- 示例(单次抽奖)
```json
// 可以抽奖
{
	code: 200,
	msg: "ok",
	lottery:1,
	winScope: [2,3]
}
// 中奖并给出奖品等级
{
	code: 200,
	msg: "ok",
	prizeLevel:0, // 奖品等级：一等奖，1代表二等奖
	prizeCode:"xxxx", //奖品code
	dynData:{"rsWinNum":"123456"},//自定义参数
	lottery:4
}
// 不满足参与资格，给出引导信息和链接，见下图
{
	code: 200,
	msg: "ok",
	lottery:2,
	message:"非会员不可参与抽奖，请先注册!", // 不可为空
	url:"https://www.eqxiu.com/"  // url不为空则跳转指定的链接，为空不跳转，关闭弹框
}
// 不中奖，使用默认提示
{
	code: 200,
	msg: "ok",
	lottery:3
}
```
![](/media/202205/2022-05-26_185113_448076.png)

- 示例(连抽抽奖)
```json
// 可以抽奖
{
	code: 200,
	msg: "ok",
	lottery:4,
	lotteryList:[
		{
			isWin:0
		},
		{
			isWin:1,
			prizeLevel:0, // 奖品等级：一等奖，1代表二等奖
			prizeCode:"xxxx", //奖品code
			dynData:{"rsWinNum":"123456"}//自定义参数
		},
		{
			isWin:1,
			prizeLevel:0, // 奖品等级：一等奖，1代表二等奖
			prizeCode:"xxxx", //奖品code
		}
	]
}
```
## 配置说明
### 后台配置
管理员登录后，选择菜单 “控制台”-> "应用管理" -> "互动编辑器" -> “自定义抽奖规则”
点击添加或编辑
![](/media/202207/2022-07-11_165421_748048.png)

- **规则名称：**自定义抽奖的名称，以便于在编辑器内识别
- **接口地址：**用户在抽奖时，会请求此接口（如果有配置），根据接口返回的结果，决定用户是否可以参与抽奖
- **抽奖消耗：**可配置多个
-- 资源名称：资源的名称，以便于在编辑器内识别
-- 接口参数：在发送请求时，会携带参数
-- 默认值、最大值、最小值：参数值的范围
- **抽奖门槛：**可配置多个，分数值类、身份类，参数含义同抽奖消耗
-- 身份类可以选多个子分类
- **通过接口调用：**建议关闭，开启后则完全由自定义抽奖规则的接口控制奖品库存、中奖概率等，无法使用到内容中台的概率、库存等控制。

### 后台配置示例

![](/media/202205/2022-05-26_185139_143490.png)

### 编辑器内配置

![](/media/202205/2022-05-26_185150_813206.png)

此时，用户点击抽奖时，发送请求携带的参数msgEncrypt解密后会增加：
```json
{
	"jinpai":"3", 
	"param":"3"
}
```

# 自定义抽奖次数
开放抽奖次数控制能力，可以让抽奖与其他用户行为联动，实现“拉新促活”等运营目标。

## 使用步骤
1. 根据业务场景和接口规范开发调用程序；
1. 在用户生为发生时执行调用程序；
 
## 接口开发说明
- 方法类型：POST
- 请求方式：json
- 请求参数
| 参数名 | 是否必须 | 参数类型 | 参数说明 |
| --- | --- | --- | --- |
| timestamp | 必须 | String | 请求时的时间戳 |
| nonce | 必须 | String | 随机字符串 |
| signature | 必须 | String | 请求签名 |
| msgEncrypt | 必须 | String | 加密后的消息 |

- msgEncrypt内容如下：
| 参数名 | 是否必须 | 参数类型 | 参数说明 |
| --- | --- | --- | --- |
| id | 必须 | String | 活动id |
| mobile | 否 | String | 手机号（参与类型为手机用户时） |
| openId | 否 | String | 参与用户为（微信、自定义渠道时） |
| corpOpenId | 否 | String | 企业openId，平台型企业使用 |
| customLotteryParams | 否 | obj | 如果同时启用了自定义规则且设置了消耗和门槛，这里会携带所设置的参数 |
|  |  |  |  |

- msgEncrypt解密后内容如下：
```json
手机授权：
{
	"id":10086,
	"code":"abcdefg",
	"prizeCode":"奖品代码",
	"amont":"奖品数量", // 非奖品总数
	"mobile":"183********", // 明文
	"customLotteryParams":{
		"points": "1",
	}
}
微信授权：
{
	"id":10086,
	"code":"abcdefg",
	"prizeCode":"奖品代码",
	"amont":"奖品数量", // 非奖品总数
	"openId":"微信openid",
	"nickName":"微信昵称",
	"gender":"微信性别",
	"city":"微信城市，非地理位置",
	"country":"国家",
	"customLotteryParams":{
		"points": "1",
	}
}
自定义用户:
{
	"id":10086,
	"code":"abcdefg",
	"prizeCode":"奖品代码",
	"amont":"奖品数量", // 非奖品总数
	"openId":"openid",// 对接方提供的用户唯一标识
	"customLotteryParams":{
		"points": "1",
	}
}
```

- 接口返回值
| 参数名 | 是否必须 | 类型 | 备注 |
| --- | --- | --- | --- |
| code | 是 | String | 200请求成功 |
| success | 是 | Boolean | true请求成功 |
| msg | 否 | String | 异常信息，提示给用户 |
| obj.count | 是 | int | 剩余次数 |
| obj.message | 否 | String | 次数提示信息，count为0时展示弹框 |
| obj.url | 否 | String | count为0时，点击弹框确定，跳转url |

- 说明：当接口响应超时或返回数据错误时，抽奖逻辑会中止，提示用户稍后再试。同时会通过[“自定义抽奖规则错误”](https://hc.eqxiu.cn/doc/52/ "“自定义抽奖规则错误”")事件通知。
- 示例
```json
{
	"code":200,
	"success":true,
	"obj":{
		"count": 0,
		"message": "您还不是会员，请先升级会员！",
		"url":"https://www.eqxiu.cn/vip"
	}
}
```
## 最佳实践
为了确保抽奖次数的实时性，建议在实现自定义抽奖次数接口时，同时实现[自定义抽奖规则](https://hc.eqxiu.cn/doc/53/ "自定义抽奖规则")。通过自定义抽奖规则，当用户进行抽奖时，系统会根据自定义抽奖规则中的扣减逻辑，立即减少其可用的抽奖次数，避免因延迟而导致的次数统计不准确的问题。如果在自定义抽奖规则中没有其他逻辑需要执行，只需返回参数 lottery 的值为1，即可允许用户进行抽奖。

# 自定义兑奖码

## 使用步骤
1. 有自己的核销体系，希望用户中奖后展示自己的兑奖码；
 
## 接口开发说明
- 方法类型：POST
- 请求方式：json
- 请求参数
| 参数名 | 是否必须 | 参数类型 | 参数说明 |
| --- | --- | --- | --- |
| timestamp | 必须 | String | 请求时的时间戳 |
| nonce | 必须 | String | 随机字符串 |
| signature | 必须 | String | 请求签名 |
| msgEncrypt | 必须 | String | 加密后的消息 |

- msgEncrypt内容如下：
不携带参数，可通过signature验签保障接口的安全性。

- 接口返回值
| 参数名 | 是否必须 | 类型 | 备注 |
| --- | --- | --- | --- |
| code | 是 | String | 200请求成功 |
| success | 是 | Boolean | true请求成功 |
| msg | 否 | String | 异常信息，提示给用户 |
| obj | 是 | String | 兑奖码，小于16位的唯一字符串，需对接方保障唯一性 |

- 示例
```json
{
	"code":200,
	"success":true,
	"obj": "J7G2zX9b0Y4C"
}
```
# 自动兑奖
通过监听用户中奖事件，自动完成兑奖动作，如发送优惠券、增加积分等。
事件监听参见 [数据推送](https://hc.eqxiu.cn/doc/24/)；