You need to enable JavaScript to run this app.
导航
归因报告 WebHook
最近更新时间:2024.09.11 17:39:34首次发布时间: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": []
                        }
                    ]
                }
            ]
        }
    ]