导航
归因报告 WebHook
最近更新时间：2024.06.27 14:31:19首次发布时间：2024.02.22 14:46:09
1. 概述
归因报告 WebHook 是归因决策中的一个重要功能，主要用于向已经注册 WebHook 的用户推送归因报告相关数据。通过归因报告 WebHook，用户可以及时获取异动分析、维度归因和指标归因三种报告类型的数据，实现实时监控、数据同步、告警通知和数据分析等应用场景。由于该接口的用法目前都是主动推给用户，并不会被调用，因此本文仅对出参进行说明。（归因决策为增值模块，需单独付费方可使用，自V2.62.0及以上版本支持。如您需要使用，请联系贵公司的商务人员或客户成功经理咨询购买事宜）。
2. WebHook
2.1 注册WebHook
第一步：在"项目中心"界面，点击左下角的"WebHook配置"，点击右上角的"新建配置"。
第二步：请您完成以下内容的配置
- 名称：填写一个可读的名字即可
- URL：用于接收 WebHook 数据推送的服务地址
- Secret：填写所需机制即可
- 订阅事件：勾选"归因报告"即可
2.2 订阅WebHook
第一步：进入报告的配置页面，点击"更多" -> "新建订阅"。
第二步：推送方式选择"WebHook"，在下拉列表中选择对应的 WebHook，然后点击"确定"即可。
3. 出参结构及各字段含义
3.1 所有报告类型都通用的公共部分
{ "secret": "xxx", // 密钥，从API获得 "event": { "channel": "insight", // channel和title合在一起可确认此次消息来自归因报告 "timestamp": 1610941345327, // 此消息时间戳 "title": "insight_report", "payload": { "calculationDay": "2022-05-13", "reportType": "DIM_CONTRIBUTE", // 表示归因分析 "reportLink": "https://...", "sceneId":"555371_scene_gkkxl_1648533079", "sceneGroupId":"555371_sceneGroup_gpytp_1648533079", "bigEvents": [ // 如果没有大事件，这里是空值[] { // 这里表明有2个节日覆盖了2022-05-16这一天 "date": "2022-05-16", "events": [ { "name": "测试-刘志毅-2", "range": "2022-05-01 ~ 2022-05-30", "type": "ChineseStatutoryHoliday" }, { "name": "可以的", "range": "2022-05-01 ~ 2022-05-31", "type": "ChineseStatutoryHoliday" } ], "label": "cmp" // cmp是对比日，base是基准日 }, { "date": "2022-05-15", "events": [ { "name": "测试-刘志毅-2", "range": "2022-05-01 ~ 2022-05-30", "type": "ChineseStatutoryHoliday" }, { "name": "可以的", "range": "2022-05-01 ~ 2022-05-31", "type": "ChineseStatutoryHoliday" } ], "label": "base" } ], // 新增wholeReportUrl和token "reportUrl": "http://dp-insight-service-staging.byted.org/api/v4/report/{sceneId}/{calculationDay}", "token": "1989a24fc4ce416aa28a263e45bf2160", "detail": [ { // 这里各类型的报告会不一样，下面展开讲 } ] } } }
3.2 获取完整报告
使用 GET 方法请求"payload"中的"reportUrl"，将"token"作为 GET 请求的一个参数，token 的有效时长为8小时，最终请求的URL例子如下：
http://dp-insight-service-staging.byted.org/api/v4/report/555371_scene_gkkxl_1648533079/2022-05-13?token=1989a24fc4ce416aa28a263e45bf2160
GET 接口返回示例：
- 成功：
{ "success": true, "code": 0, "errMsg": "", "data": {} // data和payload结构完全一致，这里不列出了 }
- 失败：
{ "success": false, // 用success来判断请求成功或者失败即可 "code": 4, "errMsg": "Cannot find report file on 2022-05-15 for 555371_scene_krdgm_1652784047", "data": {} }
- 注意：这种方法返回的仅有"payload"这一层级的数据，不包括最外层的"secret"和"event"中的其他部分。
3.3 WebHook 返回的约定格式
当前归因报告仅支持通过 POST 请求推送数据，当接收方正常收到数据时，结果要包含：
{"code": 0, "data": ""}
这是为了方便出错后重试推送WebHook，如果出错的话 Code 返回-1即可。当前重试的逻辑是每10秒尝试一次，最多尝试5次。
3.4 异动分析(即 reportType==ANOMALY)
3.4.1 报告结构概览
- 观察日期：2022-05-16
- 归因配置名称：异动分析附带维度下钻和指标拆解
- 核心指标名称：session_in_hour
- 核心指标的异动结论：显著偏低
- 核心指标在观察日期的值、差值、日环比or周同比
- 核心指标mini图中用到的日期和数据：detail部分
- 大事件（如果有）
- 指标拆解的异动结论（如果有）
- 维度拆解的异动结论（如果有）
- 归因报告链接（如果用户配置了自定义链接则选取自定义链接）
3.4.2 现有推送样例
3.4.3 Detail 部分
"detail": [ { "name": "2022-05-16 nlg首页 deno", // 计算日期 + 归因配置名 + 核心指标名 "method": "hw", // 表示Holt-winters, 还可能是prophet "group": { // 分组维度信息，如果column为空表示ALL "column": "", "value": "" }, "date": "2022-05-16", "primary": { "id": "anomaly_555371_555371_scene_krdgm_1652784047_2022-05-17_0", "measure": "session_in_hour", "isAnomaly": true, "anomalyDirection": "lower", "summary": "显著偏低", "period": 30, "stats": { "today": 1428453.0, "diffLastDay": -99409.0, "comparisonLastDay": -0.06506412228329522, // 对比上个计算粒度的差值 "comparisonLastWeek": null, // 只有当报告粒度为天且想对比上周同一天才需要这个值，即周同比 "diffLastWeek": null, "deviationDegree": 0.01680348145439999 // 异常程度 }, "graph": { "upper": [ 1738253.5589200377, 1705806.4809082185, 1818177.6084551401, 1810731.0620174522, 1699870.8104530869, 1777902.799121916, 1700911.2968303005, 1733185.8019011735, 1689146.904172288, 1788360.6605829196, 1758954.8414980113, 1647064.215157513, 1757255.0041363733, 1702868.0345540121, 1721177.7118999576, 1662972.0420704607, 1783613.6765082409, 1757603.924242037, 1652246.221146727, 1705576.8827840516, 1600171.6398726602, 1600068.6438080508, 1581970.814286254, 1657729.6403775096, 1672605.688495312, 1575270.1998828433, 1653097.682167733, 1547843.9046878188, 1574212.634276808, 1587994.307854472 ], "lower": [ 1603125.4614881256, 1570678.3834763065, 1683049.511023228, 1675602.9645855401, 1564742.7130211748, 1642774.701690004, 1565783.1993983884, 1598057.7044692615, 1554018.806740376, 1653232.5631510075, 1623826.7440660992, 1511936.117725601, 1622126.9067044612, 1567739.9371221, 1586049.6144680455, 1527843.9446385487, 1648485.5790763288, 1622475.826810125, 1517118.123714815, 1570448.7853521395, 1465043.542440748, 1464940.5463761387, 1446842.716854342, 1522601.5429455976, 1537477.5910633998, 1440142.1024509312, 1517969.584735821, 1412715.8072559068, 1439084.536844896, 1452866.2104225599 ], "forecast": [ 1670689.5102040817, 1638242.4321922625, 1750613.559739184, 1743167.0133014962, 1632306.7617371308, 1710338.75040596, 1633347.2481143444, 1665621.7531852175, 1621582.855456332, 1720796.6118669636, 1691390.7927820552, 1579500.166441557, 1689690.9554204172, 1635303.985838056, 1653613.6631840016, 1595407.9933545047, 1716049.6277922848, 1690039.875526081, 1584682.172430771, 1638012.8340680955, 1532607.5911567041, 1532504.5950920947, 1514406.765570298, 1590165.5916615536, 1605041.6397793558, 1507706.1511668873, 1585533.633451777, 1480279.8559718628, 1506648.585560852, 1520430.259138516 ], "self": [ 1674168.0, 1643952.0, 1757754.0, 1751225.0, 1640953.0, 1719362.0, 1642612.0, 1635209.0, 1589599.0, 1666062.0, 1696172.0, 1677568.0, 1761579.0, 1633391.0, 1584790.0, 1639099.0, 1629120.0, 1647740.0, 1542514.0, 1619300.0, 1526203.0, 1496796.0, 1524381.0, 1586034.0, 1585034.0, 1517444.0, 1558635.0, 1568211.0, 1527862.0, 1428453.0 ], "time": [ "2022-04-17", "2022-04-18", "2022-04-19", "2022-04-20", "2022-04-21", "2022-04-22", "2022-04-23", "2022-04-24", "2022-04-25", "2022-04-26", "2022-04-27", "2022-04-28", "2022-04-29", "2022-04-30", "2022-05-01", "2022-05-02", "2022-05-03", "2022-05-04", "2022-05-05", "2022-05-06", "2022-05-07", "2022-05-08", "2022-05-09", "2022-05-10", "2022-05-11", "2022-05-12", "2022-05-13", "2022-05-14", "2022-05-15", "2022-05-16" ] } }, "disassembly": [ // 指标拆解的部分在这里 { "id": "anomaly_555371_555371_scene_krdgm_1652784047_2022-05-17_1", "formula": "[session_in_hour] = [sum(常数项)] * [deno]", "formulaValues": [ { "measure": "deno", "today": 22.335981111128486, // 今天的值，即对比值 "diff": -1.1587444001739904, // 和基准日的差值 "comparisonLastDay": -0.04931934189299465, "comparisonLastWeek": null, "diffLastWeek": null, "isAnomaly": true, "anomalyDirection": "lower", "summary": "显著偏低", "deviationDegree": 0.018997340807629024, "subPathValues": [] }, { "measure": "sum(常数项)", "today": 63953.0, "diff": -1077.0, "comparisonLastDay": -0.016561586959864677, "comparisonLastWeek": null, "diffLastWeek": null, "isAnomaly": false, "anomalyDirection": "normal", "summary": "没有显著变化", "deviationDegree": null, "subPathValues": [] } ] } ], "drillDown": [ // 这里只包含有异动的维度 { "id": "anomaly_555371_555371_scene_krdgm_1652784047_2022-05-17_16558", "path": [ "app_id", "user_unique_id" ], "pathValues": [ // 下钻会有嵌套的pathValues { "id": "anomaly_555371_555371_scene_krdgm_1652784047_2022-05-17_3", "pathValue": "214043", "today": 1299049.0, "diff": -110578.0, "comparisonLastDay": -0.07844486520192931, "comparisonLastWeek": null, "diffLastWeek": null, "percentage": 0.9094096900633063, "isAnomaly": true, "anomalyDirection": "lower", "summary": "显著偏低", "deviationDegree": 0.021050503181031792, "pathValues": [ // 为了简洁仅保留了部分下钻数据 { "id": "anomaly_555371_555371_scene_krdgm_1652784047_2022-05-17_4957", "pathValue": "2664866863384238", "today": 71.0, "diff": 50.0, "comparisonLastDay": 2.380952380952381, "comparisonLastWeek": null, "diffLastWeek": null, "percentage": 5.4655367118561345e-05, "isAnomaly": true, "anomalyDirection": "higher", "summary": "显著偏高", "deviationDegree": 436.26511727854773, "pathValues": [], "subPathAnomalyNum": 0 } ], "subPathAnomalyNum": 1878 } ] } ] } ]
3.5 维度归因(即 reportType==DIM_CONTRIBUTE)
3.5.1 报告结构概览
- 观察日期：2022-05-15
- 基准日期：2022-05-14
- 归因配置名称：测试detect
- 核心指标名称：deno
- 核心指标的观察日期值、基准日期值、差值、差异百分比
- 算法名称：定基法
- NLG摘要
- 核心指标异动结论（如果有）
- 核心指标mini图中用到的日期和数据（如果有）
- 大事件（如果有）
- 根因维度定位NLG（如果有）
- 维度下钻路径下的数据：
- 维度下钻路径名称
- 维度项
- 观察日期值、基准日期值、差值、差异百分比、贡献率
- 归因报告链接（如果用户配置了自定义链接则选取自定义链接）
3.5.2 现有推送样例
3.5.3 Detail 部分
"detail": [ { // 表示'定基法'，还可能有'drop'表示剔除法，和'proportion'表示占比加权法 "method": "adtributor", "data": [ { "group": { // 分组维度信息，如果column为空表示ALL "column": "", "value": "" }, "trend": { // 推送截图上的趋势图来自这里 "measure": "deno", "compareDate": "2022-05-15", "baseDate": "2022-05-14", "stats": { "compareValue": 59.67160830020151, "diff": -2.3955546727878385, "pop": -0.03859616837699423 }, "graph": { "date": [ "2022-05-09", "2022-05-10", "2022-05-11", "2022-05-12", "2022-05-13", "2022-05-14", "2022-05-15" ], "self": [ 54.64136433924111, 55.68505132860585, 53.009107351225204, 56.69255614406207, 62.20009328358209, 62.06716297298935, 59.67160830020151 ] } }, "table": [ // 详细的归因数据都在这里，为了简洁只保留了部分数据 { "path": [ // 下钻路径的名字，如果层级下钻这里会有多个 "app_id_2" ], "pathValue": [ // 下钻路径各个维度的维度值都在这 "151129test" ], "baseVal": 67.6795645031715, // 基准日指标值 "cmpVal": 65.10193034956757, // 对比日指标值 "score": 1.0727633728229282, // 贡献率，最重要的几个值之一 "growth": -2.3955546727878385, // 指标增长的值 "diff": -2.577634153603938, "contribution": -2.5698633105616078, // 贡献值 "parentToday": 59.67160830020151, // 对比日指标值 "parentYesterday": 62.06716297298935, // 基准日指标值 "parentDiff": -2.3955546727878385, // 指标的差值 "gcol": "", // 分组的列名，比如对城市分组，gcol就是'城市' "parentPath": [], // 父层级的路径值，多层下钻的话会有 "today": "2022-05-15", // 对比日的日期值 "yesterday": "2022-05-14", // 基准日的日期值 "factor": "positive", // 正向还是负向贡献 "pop": -0.03808585608560097, // (cmpVal - baseVal) / baseVal "gval": "", // 分组的维度值，接上文对城市分组的话，这里可能是北京，上海等 "drillPath": [ // 下钻路径 "app_id_2" ], "drill": [] }, { "path": [ // 截图上的摘要就来自'date'这个维度的数据 "date" ], "pathValue": [ "20220514" ], "baseVal": 62.06716297298935, "cmpVal": 0, "score": 0.9817680045843858, "growth": -2.3955546727878385, "diff": -62.06716297298935, "contribution": -2.3518789309757175, "parentToday": 59.67160830020151, "parentYesterday": 62.06716297298935, "parentDiff": -2.3955546727878385, "gcol": "", "parentPath": [], "today": "2022-05-15", "yesterday": "2022-05-14", "factor": "positive", "pop": -1.0, "gval": "", "drillPath": [ "date" ], "drill": [], } ], "summary": [ // 截图上的摘要部分来自这里 { "main": { "l1factor": "20220514", // 这条摘要的维度值 "diff": -62.06716297298935, "from": 62.06716297298935, "to": 0, "direction": "positive", // 表示正向，负向negative "contribution": 0.9817680045843858 }, "explanation": { // 只有除法才有numerator和denominator "nume": -12289050.0, // 分子值 "deno": -197996.0 // 分母值 }, "granularity": "比前日", "drillPath": [ "date" // 这条摘要的维度 ] }, { "main": { "l1factor": "20220515", "diff": 59.67160830020151, "from": 0, "to": 59.67160830020151, "direction": "positive", "contribution": 0.018231995415614165 }, "explanation": { "nume": 10956304.0, "deno": 183610.0 }, "granularity": "比前日", "drillPath": [ "date" ] } ] } ] } ]
3.6 指标归因(即reportType==MEASURE_CONTRIBUTE)
3.6.1 报告结构概览
- 观察日期：2022-05-16
- 基准日期：2022-05-15
- 归因配置名称：8
- 核心指标名称：sum(session_in_hour)
- 核心指标的观察日期值、基准日期值、差值、差异百分比
- 算法名称：Lmdi算法
- NLG摘要
- 大事件（如果有）
- 各子指标的数据：
- 指标名称
- 观察日期值、基准日期值、差值、差异百分比、贡献率
- 归因报告链接（（如果用户配置了自定义链接则选取自定义链接）
3.6.2 现有推送样例
3.6.3 Detail 部分
"detail": [ { "method": "lmdi", // 指标归因的算法，目前只有这一种 "data": [ { "group": { "column": "", "value": "" }, "trend": { // 推送截图上的趋势图就来自这里 "measure": "sum(seesion_in_hour)", "compareDate": "2022-05-16", "baseDate": "2022-05-15", "stats": { "compareValue": 5036509752.0, "diff": -618115610.0, "pop": -0.10931150525971839 }, "graph": { "date": [ "2022-05-10", "2022-05-11", "2022-05-12", "2022-05-13", "2022-05-14", "2022-05-15", "2022-05-16" ], "self": [ 5267687990.0, 5228128407.0, 5275302689.0, 5336674485.0, 5661999198.0, 5654625362.0, 5036509752.0 ] } }, "table": [ // 详细的贡献率等数据来自这里 { "path": [ "factor" ], "pathValue": [ "sum(常数项)" ], "factorName": "sum(常数项)", "baseVal": 83215024.0, "cmpVal": 75566226.0, "diff": -7648798.0, "score": 0.8329132103557245, "contribution": -514836657.096087, "parentToday": 5036509752.0, "parentYesterday": 5654625362.0, "parentDiff": -618115610.0, "gcol": "", "parentPath": [], "today": "2022-05-16", "yesterday": "2022-05-15", "factor": "positive", "pop": -0.091916070348066, "gval": "" }, { "path": [ "factor" ], "pathValue": [ "deno" ], "factorName": "deno", "baseVal": 67.95197658057516, "cmpVal": 66.65027511099998, "diff": -1.3017014695751783, "score": 0.16708678964427556, "contribution": -103278952.90391307, "parentToday": 5036509752.0, "parentYesterday": 5654625362.0, "parentDiff": -618115610.0, "gcol": "", "parentPath": [], "today": "2022-05-16", "yesterday": "2022-05-15", "factor": "positive", "pop": -0.01915619728929687, "gval": "" } ], "summary": [ // 推送截图上的摘要部分来自这里 { "main": { "l1factor": "sum(常数项)", "diff": -7648798.0, "from": 83215024.0, "to": 75566226.0, "direction": "positive", "contribution": 0.8329132103557245 }, "granularity": "比前日", "drillPath": [] }, { "main": { "l1factor": "deno", "diff": -1.3017014695751783, "from": 67.95197658057516, "to": 66.65027511099998, "direction": "positive", "contribution": 0.16708678964427556 }, "granularity": "比前日", "drillPath": [] } ] } ] } ]