# 外部应用分析 API 接口

## 一、获取渠道参数配置

**接口名称**：GetExternalChannelAdParasConf

**功能描述**：获取渠道参数配置

**注意事项**：调用凭据请使用 [获取稳定版接口调用凭据](/minigame/dev/api-backend/access-token/api_getstableaccesstoken.md) 接口获取。

**调用地址**：请使用GET HTTP请求：

```
https://api.weixin.qq.com/publisher/stat?action=get_external_channel_ad_paras_conf&access_token=
```

**返回数据示例**：

```json
{
    "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 | 渠道配置列表 |

### ConfItem

单个渠道的参数配置。

| **字段** | **类型** | **说明** |
| --- | --- | --- |
| channel_recognize_fields | array | 渠道识别字段 |
| appid | string | appid |
| ad_hierarchy_fields | array | 广告层级字段（按序第0位为计划识别字段，第1位为广告识别字段） |
| external_channel_name | string | 渠道名称 |



**错误码示例**

| 错误码 | 错误码说明 | 解决方案 |
| --- | --- | --- |
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 1700 | 参数错误 | 查看返回的错误信息，检查输入参数是否正确 |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |



## 二、获取外渠广告列表

**接口名称**：GetExtChanValidAdList

**功能描述**：获取外渠广告列表

**注意事项**：调用凭据请使用 [获取稳定版接口调用凭据](/minigame/dev/api-backend/access-token/api_getstableaccesstoken.md) 接口获取。

**调用地址**：请使用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=
```

**返回数据示例**：

```json
{
    "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 | 广告层级字段（按序第0位为计划识别字段，第1位为广告识别字段） |
| ad_hierarchy_fields_jsons | array | 识别出的广告ID（按广告层级字段拼接给出） |

**错误码示例**：

| 错误码 | 错误码说明 | 解决方案 |
| --- | --- | --- |
| 0 | ok | ok |
| -202 | 内部错误 | 可在一段时间后重试 |
| 2 | 无效参数 | 检验输入参数是否符合文档说明 |
| 4 | 服务器错误 | 根据错误信息判断 |
| 6 | 校验access_token失败 | 重新生成access_token |
| 1700 | 参数错误 | 查看返回的错误信息，检查输入参数是否正确 |
| 45009 | 访问过快 | 过一分钟或一小时后调用 |
| 45010 | 输入action错误 | 检验输入参数是否符合文档说明 |

## 三、获取外渠实时ROI数据

**接口名称**：GetExtChanRealTimeRoiTrace

**功能描述**：获取外渠广告列表实时ROI数据，以小时维度聚合回传

**注意事项**：调用凭据请使用 [获取稳定版接口调用凭据](/minigame/dev/api-backend/access-token/api_getstableaccesstoken.md) 接口获取。

**调用地址**：请使用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=
```

**返回数据示例**：

```json
{
    "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 | 实时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长效数据

**注意事项**：调用凭据请使用 [获取稳定版接口调用凭据](/minigame/dev/api-backend/access-token/api_getstableaccesstoken.md) 接口获取。

**调用地址**：请使用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=
```

**返回数据示例**：

```json
{
    "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 | 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看板」查看完整数据。

**注意事项**：调用凭据请使用 [获取稳定版接口调用凭据](/minigame/dev/api-backend/access-token/api_getstableaccesstoken.md) 接口获取。

**调用方式**：POST 

```
https://api.weixin.qq.com/publisherupload/publisher_upload?action=data_upload&access_token=
```

**请求数据示例**：

```bash
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=
```



**返回数据示例**

```json
{
    "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错误 | 检验输入参数是否符合文档说明 |