基础能力

视频能力

线索组件

接口调用凭证

Web 化接入

隐私协议

流量主

小程序码与小程序链接

用户信息

抖音号绑定

小程序推广计划

内容安全

任务能力

反馈

客服

小程序券

触达与营销

支付

运营

生活服务

垂直行业

其它

广告收入5分钟聚合数据Webhook
收藏
我的收藏

功能描述

将实时广告数据按5分钟进行聚合，随后推送至平台所配置的URL地址，以消除轮询查询接口所产生的固定延迟和无效性能消耗。

接入流程

1.开发者服务端实现

1.配置webhook回调

参考小程序webhook

2.实现接收事件逻辑

一条或多条数据聚合数据会被打包进请求 body 中，作为一次事件推送。

•

body 数据

名称	类型	是否必填	描述	示例值
event	string	是	对应于平台上订阅的某个事件英文名称，实时广告数据对应的事件名称为 "ma_ecpm_notify"	ma_ecpm_notify
client_key	string	是	小程序ID	tt5daf2b12c285xxxx
from_user_id	string	否	ma_ecpm_notify事件下固定为空	''
content	string	否	包含一条或多条广告数据记录的JSON字符串，最外层是个列表	{"data_list":[{"id":"10000000509","mp_id":"tt5daf2b12c2857910","cost":"3412","open_id":"9eMmlmrIzcr-i96V","event_time":"1780646400","ipu":"2","ad_type":"激励视频广告"},{"id":"10000000505","mp_id":"tt5daf2b12c2857910","cost":"1501","open_id":"duEo3n21Gd-e9nc","event_time":"1780646400","ipu":"1","ad_type":"激励视频广告"}]}
log_id	string	是	内部链路事件推送的日志ID，用于提供给平台 debug	021715174212333fdbddc0300ff0501923618698dde1fe7bd105a

•

content详情

名称	类型	是否必填	描述
id	string	是	记录唯一标识，随 event_time 趋势递增
mp_id	string	是	小程序ID
cost	string	是	广告消耗，单位为：十万分之一元
open_id	string	是	用户OpenID（如果 OpenID 返回为空且需要重试，可以将 http 响应码返回为400）
event_time	string	是	5分钟聚合数据粒度的起始时间戳，单位秒
ad_type	string	是	小程序广告类型
ipu	string	是	5分钟内的请求次数加总

请求头示例：

{
        "log_id": "021715689753164fdbddc0300150239894918b04000001244bba2",
        "event": "ma_ecpm_notify",
        "client_key": "tt5daf2b12c2857910",
        "from_user_id": "",
        "content": "{\"data_list\": [{\"id\": \"10000000505\",\"mp_id\": \"tt5daf2b12c2857910\",\"cost\": \"1501\",\"open_id\": \"9eMmlmrIzcr-i96V\",\"event_time\": \"1715689706\",\"ipu\": \"1\",\"ad_type\": \"激励视频广告\"}]}"
}

Content 字段示例：

{
    "data_list": [
        {
            "id": "10000000509",
            "mp_id": "tt5daf2b12c2857910",
            "cost": "3412",
            "open_id": "9eMmlmrIzcr-i96V",
            "event_time": "1780646400",
            "ipu": "2",
            "ad_type": "激励视频广告"
        },
        {
            "id": "10000000505",
            "mp_id": "tt5daf2b12c2857910",
            "cost": "1501",
            "open_id": "duEo3n21Gd-e9nc",
            "event_time": "1780646400",
            "ipu": "1",
            "ad_type": "激励视频广告"
        }
    ]
}

HTTP响应码约定

如果开发者服务端确定接收到某次事件的广告数据，返回[200,300)范围内的响应状态码；

如果返回其他响应状态码，系统认为开发者服务端异常及事件推送失败。

由于 OpenID 字段实现为弱依赖且存在下游稳定性问题，如果 OpenID 返回为空且需要重新推送获取非空 OpenID 时，可以将响应状态码返回为 400。如果超出 10 次重试推送仍为空（几乎不可能出现），可以延迟一段时间通过查询接口查询相应记录。

HTTP响应体

系统不处理响应体。

超时控制

对于某次事件推送如果开发者服务端超过2.5秒未响应，系统认为事件推送失败。

事件推送失败重试策略

当某次推送被认为是失败时（超时或非[200,300)响应码），系统会累积这些推送失败的广告数据记录，并每隔1分钟定期重新打包和推送（可能与新到来的记录打包到一个请求 body 中投递）。如果被重新打包推送超过10次，那么这条广告记录会被系统丢弃。

2.开启订阅事件

以下两种方式均可：

1.开发者平台订阅

2.openapi 开启事件订阅

更新webhook事件状态

语义说明

1.实时性

绝大部分情况是从广告服务端发送广告开始1分钟内能将数据推送至开发者服务端，最大延迟不会超过10分钟。若大量数据超过10分钟为系统异常，会有监控报警并被及时处理。

2.数据延迟

可能存在部分数据延迟情况，即数据在5分钟的时间窗口之后到达，届时会追加推送一条数据，由开发者服务端依据(event_time, open_id, ad_type)唯一键保证幂等性。

3.重试策略

•

当某次推送被认为是失败时（超时或非[200,300)响应状态码），系统会累积这些推送失败的广告数据记录，并每隔1分钟定期重新打包和推送（可能与新到来的记录打包到一个请求中投递）。如果被重新打包推送超过10次，那么这条广告记录会被系统丢弃。

•

为了避免资源浪费，系统会统计5分钟内的开发者服务端超时或非正常响应状态码次数，若次数超出阈值，则在这5分钟内不再发起请求，等到下一个5分钟窗口重置次数并继续请求。

4.超时控制

对于某次事件推送如果开发者服务端超过2.5秒未响应，系统认为事件推送失败并触发重试策略。

5.顺序性

系统无法保证先被发送广告的数据记录被先推送。

6.完整性

系统会将产生的每一条广告数据记录都至少一次推送至开发者服务端中，但开发者服务端存在失败的可能，记录可能会因为重试次数超限而被丢弃，因此开发者需要做好监控来识别丢失的情况，并通过调用查询接口来补偿丢失数据。

衡量webhook推送的数据是否丢失是以数据库为准的，目的是为了保证跟查询接口相比不丢失记录。如果认为webhook推送少了数据，但通过查询接口也查询不到想要的数据，说明存在其他数据缺失或无数据的原因，这些可能的情况列举在查询接口文档中，如果无法解决请oncall进来。

Q&A

1.推送数据量少于预期

广告未投放，参考巨量广告投放流程-投放流程指引-资产管理与创编IAA*抖音小程序-投放全流程指引

某个用户最近一个月无 clickid 激活记录（只看最新一次激活时间是否超过一个月，不管历史激活多少次），参考巨量广告回传激活-投放流程指引-巨量回传IAA*抖音小程序-投放全流程指引

用户通过客户端向广告服务端请求广告，但获取不到广告，此时客户端会展示兜底广告，兜底广告无收益也无数据。广告服务端是否返回广告是由广告策略决定。

用户获取和看到的广告为预览广告，即由预览广告计划产生的广告；这种情况通常是测试点击预览广告进入小程序的用户会获取到预览广告。

风控场景：非正常渠道的广告，用户近期内多次刷广告，其它识别到的作弊场景

参数查询错误，openId、appId、日期等是否传对

查询超时：增加重试，请求密度控制在1-5分钟内一次，视网络、数据量定

2.与离线数据 gap 说明

跟原查询接口一样，webhook和新查询接口都是依赖相同的实时数据源，实时数据源与离线数据源存在 gap 仍未解决。gap 成因很多，例如实时数据源没有经过去重和风控机制。最终结算以离线数据为准。

广告收入5分钟聚合数据Webhook收藏我的收藏