# 外部应用分析 API 接口
# 一、获取渠道参数配置
接口名称：GetExternalChannelAdParasConf
功能描述：获取渠道参数配置
注意事项：调用凭据请使用 获取稳定版接口调用凭据 接口获取。
调用地址：请使用GET HTTP请求：
https://api.weixin.qq.com/publisher/stat?action=get_external_channel_ad_paras_conf&access_token=
返回数据示例：
{
"base_resp": {
"err_msg": "ok",
"ret": 0
},
"conf_list": [
{
"ad_hierarchy_fields": ["ksCampaignId", "ksUnitId"],
"appid": "xxx",
"channel_recognize_fields": ["ksCampaignId", "ksUnitId"],
"external_channel_name": "快手"
},
{
"ad_hierarchy_fields": ["project_id", "promotion_id"],
"appid": "xxx",
"channel_recognize_fields": ["project_id", "promotion_id"],
"external_channel_name": "抖音"
}
]
}
请求参数：无
返回参数：
| 字段 | 类型 | 说明 |
|---|---|---|
| ret | int | 错误码，0表示成功，非0表示失败，具体含义见错误码说明 |
| err_msg | string | 错误信息，成功为"ok"，失败时返回具体错误描述 |
| conf_list | array<object(ConfItem)> | 渠道配置列表 |
# ConfItem
单个渠道的参数配置。
| 字段 | 类型 | 说明 |
|---|---|---|
| channel_recognize_fields | array<string> | 渠道识别字段 |
| appid | string | appid |
| ad_hierarchy_fields | array<string> | 广告层级字段（按序第0位为计划识别字段，第1位为广告识别字段） |
| external_channel_name | string | 渠道名称 |
错误码示例
| 错误码 | 错误码说明 | 解决方案 |
|---|---|---|
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 1700 | 参数错误 | 查看返回的错误信息，检查输入参数是否正确 |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |
# 二、获取外渠广告列表
接口名称：GetExtChanValidAdList
功能描述：获取外渠广告列表
注意事项：调用凭据请使用 获取稳定版接口调用凭据 接口获取。
调用地址：请使用GET HTTP请求：
https://api.weixin.qq.com/publisher/stat?action=get_ext_chan_valid_ad_list&access_token=&start_time=&end_time=&channel_recognize_fields_str=
返回数据示例：
{
"ad_hierarchy_fields_jsons": ["{\"project_id\":\"4783\",\"promotion_id\":\"2432\"}"],
"aid_hierarchy_fields": ["project_id", "promotion_id"],
"base_resp": {
"err_msg": "ok",
"ret": 0
}
}
请求参数：
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| start_time | string | 是 | 起始日期yyyy-mm-dd，该日期为用户注册日期 |
| end_time | string | 是 | 结束日期yyyy-mm-dd，该日期为数据截止日期 |
| channel_recognize_fields_str | string | 是 | 渠道识别字段 （按逗号分隔，例如"ksCampaignId,ksUnitId"） |
返回参数：
| 字段 | 类型 | 说明 |
|---|---|---|
| ret | int | 错误码，0表示成功，非0表示失败，具体含义见错误码说明 |
| err_msg | string | 错误信息，成功为"ok"，失败时返回具体错误描述 |
| aid_hierarchy_fields | array<string> | 广告层级字段（按序第0位为计划识别字段，第1位为广告识别字段） |
| ad_hierarchy_fields_jsons | array<string> | 识别出的广告ID（按广告层级字段拼接给出） |
错误码示例：
| 错误码 | 错误码说明 | 解决方案 |
|---|---|---|
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 1700 | 参数错误 | 查看返回的错误信息，检查输入参数是否正确 |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |
# 三、获取外渠实时ROI数据
接口名称：GetExtChanRealTimeRoiTrace
功能描述：获取外渠广告列表实时ROI数据，以小时维度聚合回传
注意事项：调用凭据请使用 获取稳定版接口调用凭据 接口获取。
调用地址：请使用GET HTTP请求：
https://api.weixin.qq.com/publisher/stat?action=get_ext_chan_real_time_roi&access_token=&start_time=&end_time=&channel_recognize_fields_str=&ad_hierarchy_fields_jsons_str=&query_mode=
返回数据示例：
{
"base_resp": {
"err_msg": "ok",
"ret": 0
},
"real_time_roi_data_list": [ {
"ad_arpu": 0.0835741320,
"ad_roi": 0.0,
"advertise_ad_clk_cnt": 0,
"advertise_ad_clk_ratio": 0.0,
"advertise_ad_cost": 0.0,
"advertise_ad_exp_cnt": 0,
"advertise_ecpm": 0.0,
"advertise_reg_uv": 478,
"advertise_total_uv": 995,
"aid": "24232",
"cid": "53432",
"ds": "2024-11-12",
"ds_hour": "2024-11-12",
"monetize_ad_income": 39.94,
"monetize_ecpm": 20.98,
"reg_paid": 0.0
}]
}
请求参数：
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| start_time | string | 是 | 起始日期 天维度：yyyy-mm-dd 小时维度：yyyy-mm-dd HH:MM:SS |
| end_time | string | 是 | 结束日期 天维度：yyyy-mm-dd 小时维度：yyyy-mm-dd HH:MM:SS （注意：当天最后一个小时的数据分区时间为yyyy-mm-dd 23:00:00） |
| channel_recognize_fields_str | string | 是 | 渠道识别字段 （按逗号分隔，例如"ksCampaignId,ksUnitId"） |
| ad_hierarchy_fields_jsons_str | string | 否 | 查询所识别出的广告ID 注意： (1)多个按竖线符号"|"拼接 (2)根据GetExtChanValidAdList接口所返回的ad_hierarchy_fields_jsons 值拼接 注意参数需要做url编码 例如原始的参数为： {"project_id":"a","promotion_id":"b"}|{"project_id":"c","promotion_id":"d"} url编码后的参数为： %7B%22project_id%22%3A%22a%22%2C%22promotion_id%22%3A%22b%22%7D%7C%7B%22project_id%22%3A%22c%22%2C%22promotion_id%22%3A%22d%22%7D%0A |
| query_mode | int | 否 | 查询方式： 0:按天, 1:支持单日按小时下钻 |
返回参数：
| 字段 | 类型 | 说明 |
|---|---|---|
| ret | int | 错误码，0表示成功，非0表示失败，具体含义见错误码说明 |
| err_msg | string | 错误信息，成功为"ok"，失败时返回具体错误描述 |
| real_time_roi_data_list | array<object(RealTimeRoiData)> | 实时ROI数据列表，按小时维度聚合 |
# RealTimeRoiData
单条实时ROI数据。
| 字段 | 类型 | 说明 |
|---|---|---|
| ad_arpu | double | 广告ARPU |
| ad_roi | double | 广告ROI |
| advertise_ad_clk_cnt | uint64 | 买量广告点击数 |
| advertise_ad_clk_ratio | double | 买量广告点击率 |
| advertise_ad_cost | double | 买量广告消耗 |
| advertise_ad_exp_cnt | uint64 | 买量广告曝光数 |
| advertise_ecpm | double | 买量广告ecpm |
| advertise_reg_uv | uint64 | 买量注册uv |
| advertise_total_uv | uint64 | 买量总uv（包含注册回流） |
| aid | string | 广告ID |
| cid | string | 计划ID |
| ds | string | 天时间 |
| ds_hour | string | 小时时间 |
| monetize_ad_income | double | 变现广告收入 |
| monetize_ecpm | double | 变现ecpm |
| reg_paid | double | 买量注册成本 |
错误码：
| 错误码 | 错误码说明 | 解决方案 |
|---|---|---|
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 1700 | 参数错误 | 查看返回的错误信息，检查输入参数是否正确 |
| 2003 | 查询失败 | 校验输入参数或一段时间后重试 |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |
# 四、获取外渠T+1长效数据
接口名称：GetExtChanTrace
功能描述：获取外渠T+1长效数据
注意事项：调用凭据请使用 获取稳定版接口调用凭据 接口获取。
调用地址：请使用GET HTTP请求：
https://api.weixin.qq.com/publisher/stat?action=get_ext_chan_trace&access_token=&start_time=&end_time=&channel_recognize_fields_str=&ad_hierarchy_fields_jsons_str=
返回数据示例：
{
"base_resp": {
"err_msg": "ok",
"ret": 0
},
"list": [{
"ad_roi": 0.0,
"advertise_ad_cost": 0.0,
"day_delta": 0,
"monetize_ad_income": 1429.9858450,
"reg_ds": "20241212",
"user_retention_cnt": 19580,
"user_retention_ratio": 1.0,
"user_total_cnt": 19580
}]
}
请求参数：
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| start_time | string | 是 | 起始日期 天维度：yyyy-mm-dd 小时维度：yyyy-mm-dd HH:MM:SS |
| end_time | string | 是 | 结束日期 天维度：yyyy-mm-dd 小时维度：yyyy-mm-dd HH:MM:SS （注意：当天最后一个小时的数据分区时间为yyyy-mm-dd 23:00:00） |
| channel_recognize_fields_str | string | 是 | 渠道识别字段 （按逗号分隔，例如"ksCampaignId,ksUnitId"） |
| ad_hierarchy_fields_jsons_str | string | 否 | 查询所识别出的广告ID 注意： (1)多个按竖线符号"|"拼接 (2)根据GetExtChanValidAdList接口所返回的ad_hierarchy_fields_jsons 值拼接 注意参数需要做url编码 例如原始的参数为： {"project_id":"a","promotion_id":"b"}|{"project_id":"c","promotion_id":"d"} url编码后的参数为： %7B%22project_id%22%3A%22a%22%2C%22promotion_id%22%3A%22b%22%7D%7C%7B%22project_id%22%3A%22c%22%2C%22promotion_id%22%3A%22d%22%7D%0A |
返回参数：
| 字段 | 类型 | 说明 |
|---|---|---|
| ret | int | 错误码，0表示成功，非0表示失败，具体含义见错误码说明 |
| err_msg | string | 错误信息，成功为"ok"，失败时返回具体错误描述 |
| list | array<object(TraceItem)> | T+1长效数据列表 |
# TraceItem
单条注册日追踪数据。
| 字段 | 类型 | 说明 |
|---|---|---|
| reg_ds | string | 注册日期 |
| day_delta | uint32 | 与注册日期的日期差 |
| user_total_cnt | uint64 | 首日启动人数 |
| user_retention_cnt | uint64 | 用户留存数 |
| user_retention_ratio | double | 用户留存率 |
| advertise_ad_cost | double | 买量消耗(元) |
| monetize_ad_income | double | 变现收入(元) |
| ad_roi | double | 广告roi |
错误码示例：
| 错误码 | 错误码说明 | 解决方案 |
|---|---|---|
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 1700 | 参数错误 | 查看返回的错误信息，检查输入参数是否正确 |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |
# 五、回传外部渠道买量数据
接口名称：UploadPublisherExternalChannelAdvertiseData
功能描述：该接口用于帮助小游戏开发者上传外渠买量的实时广告级数据，包括渠道识别字段、时间、买量成本、曝光、点击等，以便用于计算广告粒度的外渠买量 ROI、注册成本等数据，在「商业化工具箱 - 外部应用分析 - 实时ROI看板」查看完整数据。
注意事项：调用凭据请使用 获取稳定版接口调用凭据 接口获取。
调用方式：POST
https://api.weixin.qq.com/publisherupload/publisher_upload?action=data_upload&access_token=
请求数据示例：
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "data_type=1&upload_time=&data_ds=2024062510&channel_recognize_fields_str=project_id%2Cpromotion_id&ad_hierarchy_fields_val_str=project_id%3D(替换真实值)%26promotion_id%3D(替换真实值)&advertise_ad_cost=123&ad_name=买量广告&uid=741&exp_cnt=20&clk_cnt=30" https://api.weixin.qq.com/publisherupload/publisher_upload?action=data_upload\&access_token=
返回数据示例
{
"errcode": 2,
"errmsg": "missing necessary fields"
}
请求参数：
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| data_type | NUMBER | 是 | 上传的数据类型：固定为1，代表外渠买量变现数据 |
| upload_time | NUMBER | 是 | 数据上传unix时间戳 说明：平台会依赖该字段取某个data_ds最近一次所上传的数据作为最终数据，建议设置上报频次为5-10分钟 |
| data_ds | NUMBER | 是 | 数据的日期yyyymmddhh |
| channel_recognize_fields_str | STRING | 是 | 渠道识别字段，例如：project_id,promotion_id。依赖于广告参数配置。 |
| ad_hierarchy_fields_val_str | STRING | 是 | 广告层级数据，例如：UrlEncode(project_id=1&promotion_id=1)。promotion_id可为空值，适用于智擎版等无推广计划ID的场景，如：UrlEncode(project_id=1&promotion_id=) |
| advertise_ad_cost | NUMBER | 是 | 买量成本(单位:分) |
| ad_name | STRING | 是 | 广告名称（创建广告的自定义命名，若不关注可传空值） |
| uid | STRING | 否 | 广告主ID |
| exp_cnt | NUMBER | 否 | 广告曝光数 |
| clk_cnt | NUMBER | 否 | 广告点击数 |
返回参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | uint32 | 错误码 |
| errmsg | string | 错误信息 |
错误码：
| 错误码 | 错误码说明 | 解决方案 |
|---|---|---|
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |