营销安全lite版接入文档

更新时间：2020/01/13 访问次数：2104

营销安全lite版接入文档

接入流程

定义推荐列表：确定需要推荐的全量主体信息；
训练推荐模型：定制化训练模型，此环节可跳过，不进行模型训练，则使用冷启动模型。
推荐结果咨询：模型训练完成后，用户访问时，进行实时咨询，模型实时返回。
推荐效果回传：回传推荐的效果，用于进一步的模型优化；

主体信息说明

主体维度	字段名称	业务描述	示例
上文信息	context_info	用户来源，可以是其他APP或者小程序；或者上一级页面,营销活动	上一级小程序APPID：2088123412342345
用户信息	user_id,mobile_no	用户信息唯一标识，支付宝手机号或者用户手机号	用户手机号：18511893211
推荐主体信息	item_info	需要进行推荐的主体，例如商品或者广告信息	商品信息，标识商品ID即可；

接口基础说明

接口分为咨询接口和回传接口，咨询接口用来咨询需要展示的信息；回传接口用来将客户签约，业务效果告知支付宝，然后用来做模型的优化。

咨询接口：security.risk.customerrisk.query
回传接口：security.risk.customerrisk.send

咨询接口和回传接口都是蚂蚁的OPENAPI服务，SDK以及公有参数是相同的，只是业务入参biz_content以及返回结果不同。

接口请求地址

环境	HTTPS请求地址
正式环境	https://openapi.alipay.com/gateway.do

接口公共参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	支付宝分配给开发者的应用ID	2019072300007148
method	String	是	128	接口名称	alipay.security.risk.customerrisk.send 或者 alipay.security.risk.customerrisk.send
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA/RSA2。推荐使用RSA2	RSA2
sign	String	是	256	商户请求参数的签名串，详见签名（https://docs.open.alipay.com/200/105351）	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
notify_url	String	否	256	支付宝服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token	String	否	40	详见应用授权概述（https://docs.open.alipay.com/common/105193）
biz_content	String	是	-	请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档

接口业务参数说明

整体推荐环节分为4个阶段，在四个阶段调用不同的接口，接口的基础信息（请求地址和公共参数）都是相同的，只是业务参数biz_content不同；

四个环节请求信息如下：

定义推荐列表：需要同步蚂蚁全量需要推荐的主体信息，包括主体ID，特性信息等；如果在此环节不同步，则无法推荐。
训练推荐模型：回传用户样本数据，用来单独训练模型，如果不给用户样本信息，就按冷启动模型。数据包括用户信息、主体ID，标签（是否需要进行推荐）
推荐结果咨询：模型训练完成后，用户访问时，进行实时资讯，模型实时返回。根据用户信息和特征进行推荐；
推荐效果回传：回传推荐的效果，用于进一步的模型优化；主要是用户的行为数据，包括浏览、领券、下单支付或者收藏等信息。

定义推荐列表：

场景说明：需要将推荐的全量主体数据进行同步，推荐主体可以是一个小程序、商品或者营销活动；支付宝会根据接收的到推荐列表，最后做全局的推荐；

调用接口：alipay.security.risk.customerrisk.send

参数说明

参数	类型	是否必填	最大长度	描述	示例值
process_code	String	是	2	默认值22	22
service	String	是	128	默认值marketing_pro	marketing_pro
merchant_scene	String	是	128	业务场景：固定值：recall_list_info	recall_list_info
scene	String	是	128	服务场景权益换量：RISKGO_RIGHTS_RECOMM	RISKGO_RIGHTS_RECOMM
pid	String	是	128	客户PID，此处回传数立的PID	2088123412341234
item_recall_id	String	是	1024	推荐主体列表唯一id，若广告分发场景，则传广告主id，若多种主体列表，则分多次传输，若无则传_ALL_	2088123412341234
item_recall_type	String	是	1024	推荐场景主体类型，固定传riskgo	riskgo
item_info_list	String	是	1024	推荐主体信息列表集,包括item_id信息，公共ids信息（如无共同定义的id信息，可不传）	[ { "item_id": "app_id_1", "ids": {"pid": "pid_1", "app_id": "app_id_1"}, }, { "item_id": "app_id_2", "ids": {"pid": "pid_2", "app_id": "app_id_2"}, } ]

推荐主体信息item_info_list

参数	类型	是否必填	最大长度	描述	示例值
item_id	string	是	128	推荐主体ID，客户自定义即可，需要保证全局唯一	app_id_1
ids	string	是	1024	当推荐的item_id为蚂蚁域内 id 体系的信息。id 体系包含user_id/pid/app_id 等，key 必须按这个填写。如果item_id是蚂蚁外部数据，则此字段可以不传。	{"pid": "pid_1", "app_id": "app_id_1"}

返回结果说明：alipay.security.risk.customerrisk.send接口成功调用只会返回Success；

训练推荐模型：

接口名：回传接口：alipay.security.risk.customerrisk.send

使用场景：用来回传参与活动的客户的用户样本信息，给客户冷启动定制模型。定制模型，样本数据至少1000条。

业务入参：

参数	类型	是否必填	最大长度	描述	示例值
process_code	String	是	2	默认值23	23
service	String	是	128	默认值marketing_pro	marketing_pro
merchant_scene	String	是	128	业务场景：固定值：sample_info	sample_info
scene	String	是	128	服务场景权益换量：RISKGO_RIGHTS_RECOMM	RISKGO_RIGHTS_RECOMM
pid	String	是	128	合作伙伴的PID，传当前咨询用户的PID	2088123412341234
user_id	String	是	1024	用户支付宝2088账号ID	2088501624560335
mobile_no	String	是	1024	用户手机号，如果是在支付宝端外，则手机号必传	18511893288
item_info	String	是	128	推荐主体id信息，包括item_id信息，公共ids信息（如无共同定义的id信息，可不传）	{ "item_id": "app_id_2", "ids": {"pid": "pid_2", "app_id": "app_id_2"}, }
context_info	String	否	128	上文信息
risk_label	String	是	128	样本标签；客户自定义	01
label_time	String	是	1024	每条样本定义的时间，如样本为权益领取用户，则此处时间为权益领取时间。	2019-01-01 00:00:00
extend_info	String	是	1024	拓展字段，其余特征信息如用户的ip、商户自由用户行为特征通过此字段进行传输：

返回结果说明：alipay.security.risk.customerrisk.send接口成功调用只会返回Success；

推荐结果咨询

接口名：咨询接口：alipay.security.risk.customerrisk.query

使用场景：用户实际链路中，咨询需要给当前用户推荐那些内容（服务或者商品）

业务入参：

参数	类型	是否必填	最大长度	描述	示例值
service	String	是	128	合作伙伴匹配服务类型,请按照示例值填写	固定传marketing_pro
risk_type	String	是	1024	风险策略类型，请按照示例值填写	固定传riskinfo_marketing_recomm
scene	String	是	128	服务场景	服务场景权益换量：RISKGO_RIGHTS_RECOMM
user_id	String	否	128	支付宝用户ID	2088111122223333
mobile_no	String	是	128	用于输入用户注册的手机号码。没有传’null’	13810935692
pid	String	是	128	申请业务合作伙伴ID，即数立pid	2088123412341234
item_recall_id	是			推荐主体列表唯一id，若广告分发场景，则传广告主id，若多种主体列表，则分多次传输，若无则传_ALL_
context_info	是			上文信息；	{ "ids": { "pid": "2088_2", "app_id": "app_id_2" } }
recomm_num	String	是	2048	期望推荐个数，大于0入参，最多推荐50个；	6
extended_info	String	否	2048	拓展字段，其余特征信息如用户的ip、商户自由用户行为特征通过此字段进行传输，如无可不传。

返回结果说明：根据咨询用户的信息，返回具体的推荐结果：返回结果如下：

参数说明：

名称	类型	描述	示例
riskResult	String	风险识别结果：	详见代码示例
riskResultDesc	String	风险信息描述	{\"rank2\":\"等级2\"}

riskResult字段说明

riskResult字段后期可以根据业务需求进行拓展，会输出新的字段，建议考虑拓展性。

名称	描述	详细说明以及枚举值
riskinfo_marketing_recomm	风险识别结果：	rank0信息不足或提供的参数有误请检查入参信息 rank1用户风险低，建议展示推荐列表 rank2用户作弊风险中，建议观察后投放权益。 rank3用户作弊风险为高，建议不投放任何权益
riskinfo_marketing_recomm_infocode	推荐的结果信息	Infocode将会以数字串的方式返回，代表具体风险类型，此处为默认值，业务可以忽略
riskinfo_marketing_recomm_items	推荐的结果信息	根据入参信息模型返回的推荐结果

riskinfo_marketing_recomm_items字段说明

名称描述	描述	示例
item_id	推荐主体ID	12345
index	推荐结果顺序，数字越小优先级约高。0代表最高优先级	1
scm	推荐结果唯一标识，后续回传效果数据需要带上返回。	1.0b276d0415752566115894467e1271.2019071165845265

推荐效果回传

接口名：回传接口：alipay.security.risk.customerrisk.send

使用场景：回传推荐的效果，用于进一步的模型优化；主要是用户的行为数据，包括浏览、领券、下单支付或者收藏等信息。在每次用户产生动作时回传即可；同一用户针对同一推荐主体的动作可以进行多次回传。

业务入参：

参数	类型	是否必填	最大长度	描述	示例值
process_code	String	是	2	默认值24	24
service	String	是	128	默认值marketing_pro	marketing_pro
merchant_scene	String	是	128	业务场景，传固定值; activity_scene	activity_scene
scene	String	是	128	服务场景：固定值权益换量：RISKGO_RIGHTS_RECOMM	RISKGO_RIGHTS_RECOMM
pid	String	是	128	合作伙伴的PID，传当前回传用户的PID，即数立pid	2088123412341234
user_id	String	是	1024	用户支付宝2088账号ID	2088501624560335
mobile_no	String	是	1024	用户手机号，如果是在支付宝端外，则手机号必传	18511893288
gmt_create	String	是	1024	样本时间，形如 yyyy-mm-dd hh:mi:ss	2019-10-01 00:00:09
context_info	是			上文信息；	{ "ids": { "pid": "2088_2", "app_id": "app_id_2" } }
extended_info	String	是	1024	item_id、item顺序、scm、是否曝光、是否点击，是否领取，是否使用，标签label，item特征，按JSON数组格式回传	[{ "item_id": "2018062711112222", "index": "0", "scm": "0a6e404f15679057219423630e253e.2018062711112222", "is_shown": "1", "is_clicked ": "0", " risk_label ": "0" }, { "item_id": "2018062711113333", "index": "1", "scm": "0a6e404f15679057219423630e098e.2018062711113333", "is_shown": "1", "is_clicked ": "1", "risk_label ": "1" }]

extended_info信息说明

用户对推荐结果的操作行为：主要包括推荐结果主体信息，推荐顺序，推荐时算法唯一标示，用户动作，以及用户最终标签。

参数	类型	是否必填	最大长度	描述	示例值
item_id	string	是	128	推荐主体id	2019041163832467
index	string	是	128	推荐顺序	1
scm	string	是	128	咨询结果唯一标示	1.0b276d0415752566115894467e1271.2019071165845265
is_shown	string	是	128	是否曝光；1、已展示；0、未展示	1
is_clicked	string	否	128	是否点击；1、有点击；0、无点击；	1
is_sent	string	否	128	是否领取；1、用户已领取；0、用户未领取	1
is_used	string	否	128	是否核销；1、已核销；0未核销	1
risk_label	string	是	128	样本标签；客户自定义

返回结果说明：alipay.security.risk.customerrisk.send接口成功调用只会返回Success；

代码示例：

SEND接口响应示例

{

"alipay_security_risk_customerrisk_send_response": {

"code": "10000",

"msg": "Success"

"sign": "O43jc4YR3H0PFPQ=="

}

query接口请求示例

{

"biz_content": {

"service": "marketing_pro",

"risk_type": "riskinfo_marketing_recomm",

"pid": "null",

"mobile_no": "null",

"opposing_app_id": "2019041163832467",

"user_id": "2088002000528050",

"scene": "RISKGO_RIGHTS_RECOMM",

"recomm_num": "3",

"ip": "null",

"extended_info": "RISKGOTEST",

"item_recall_type": "riskgo"

}

query接口响应示例

{

"alipay_security_risk_customerrisk_query_response": {

"code": "10000",

"msg": "Success",

"risk_result_desc": "{\"rank1\":\"等级1\"}",

"risk_result": "{\"riskinfo_marketing_recomm\":\"rank1\",

\"riskinfo_marketing_recomm_items\":\"[{\\\\\"item_id\\\\\":\\\\\"2017122801293372\\\\\",\\\\\"index\\\\\":\\\\\"0\\\\\",\\\\\"scm\\\\\":\\\\\"1007.-1.0b276d0415752566115894467e1271.2017122801293372\\\\\"},{\\\\\"item_id\\\\\":\\\\\"2019071165845265\\\\\",\\\\\"index\\\\\":\\\\\"1\\\\\",\\\\\"scm\\\\\":\\\\\"1007.-1.0b276d0415752566115894467e1271.2019071165845265\\\\\"},{\\\\\"item_id\\\\\":\\\\\"2018081661067609\\\\\",\\\\\"index\\\\\":\\\\\"2\\\\\",\\\\\"scm\\\\\":\\\\\"1007.-1.0b276d0415752566115894467e1271.2018081661067609\\\\\"}]\",\"riskinfo_marketing_recomm_infocode\":\"2278,2280\"}"

"sign": "lum582uvBB6isSRRZa/W/Cwsm+Q=="

}

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

RiskGo安全合作平台文档

营销安全lite版接入文档

FAQ