一、留存分析查询
接口URL
/api/open_api/v1/analysis/retention?token=xxx
请求方式
POST
Content-Type
application/json
请求Query参数
|
参数名
|
参数类型
|
是否必填
|
参数描述
|
|
token
|
String
|
是
|
查询token
|
请求Body参数
留存分析的请求参数由初始事件参数（firstEvent）、回访事件参数（returnEvent）、全局筛选参数（eventsFilter）、分组项参数（eventsGroup）、时间粒度参数（eventsView）、时区参数（timeZoneOffset）和分析主体参数（entity），特殊地，在留存分析中如果使用"同时展示"功能，则会额外传入同时展示参数（alsoShow），如图所示
初始事件与回访事件参数
初始事件与回访事件参数用于描述在留存分析中使用到的事件，同时可以对其每个事件单独做筛选，参数说明如下：
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
firstEvent
|
Object
|
是
|
初始 参数 |
|
eventName
|
String
|
是
|
事件名 特殊情况：当您想要计算“任意事件”时，该值填入“_any_” |
|
eventID
|
Number｜String
|
否
|
事件唯一id，均为Number 特殊地，当您想要计算“任意事件”时，值为"_any_" |
|
eventDisplayName
|
String
|
否
|
初始事件自定义显示名，默认可以设置为事件显示名 |
|
relation
|
String
|
否
|
当想要对该事件进行筛选时，需要传入这三个字段，具体说明可见通用的API查询参数说明中“如何表示一个筛选” |
|
filterType
|
String
|
否
|
|
|
filters
|
List[Object]
|
否
|
|
|
returnEvent
|
Object
|
是
|
回访事件参数，内容同初始事件参数 |
同时展示参数
当您在留存分析中想要使用“同时展示”的功能时，还需要额外传入同时展示参数，从页面操作来看，同时展示是一个分析指标，故他的参数表示与事件分析模型API的分析指标是一致的。留存分析指标的"同时展示"有两类：一类等同于事件分析中的默认事件类型（即xxx事件的xxx值），一类是高级编辑（由多个指标进行四则运算，类似于事件分析中的自定义公式类型）
1️⃣ 使用默认事件类型作为同时展示参数
在开启同时展示时，使用默认事件类型作为计算值，如下图所示，此时同时展示参数与事件分析的默认事件类型参数基本一致，如下：
如上图所示的同时展示计算方式，可用如下的示例表示
{
"alsoShow": {
"format": "TWO DECIMALS",
"eventDisplayName": "默认类型的同时展示示例",
"eventA": {
"analysis": ["#acid", "A109"],
"eventName": "#ad_show",
"eventID": 4671,
"filterType": "SIMPLE",
"relation": "and",
"filters": [],
"boundProp": [{
"id": 1345756,
"app_id": "dt_xxxx",
"table_type": 0,
"name": "#acid",
"column_type": "varchar",
"describe": "应用内账号系统的ID",
"display_name": "账号ID",
"type": 1,
"data_type": "string"
}]
}
}
}参数说明
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
alsoShow
|
Object
|
否
|
当需要使用同时展示时，需要传入该参数
|
| format | String | 是 |
同时展示最终计算结果的精度，与事件分析自定义公式取值一致，包括： 两位小数：'TWO DECIMALS' 三位小数：'THREE DECIMALS' 四位小数：'FOUR DECIMALS' 五位小数：'FIVE DECIMALS' 六位小数：'SIX DECIMALS' 百分比：'PERCENTAGE' 取整：'ROUND' |
|
eventDisplayName
|
String
|
否
|
自定义同时展示指标的显示名 |
|
eventA
|
Object
|
是
|
同时展示所使用的事件，使用上图所示的默认类型的分析指标时，eventA的结构与与事件分析模型API中的默认事件类型一致，详见事件分析模型API |
2️⃣ 开启高级编辑的同时展示
在留存分析中的同时展示用，我们可以使用更加复杂的计算指标，通过高级编辑的形式，如下图：
在高级编辑的场景下，我们会有“回访用户指标”和“初始日期指标”，同时还可以决定两指标之间使用怎样的四则运算。两个指标与事件分析的分析指标完全一致，上图的高级编辑我们可以用如下示例表示，相较于第一种类型，我们会额外有eventB、onLeft、operator三个参数
{
"alsoShow": {
"format": "TWO DECIMALS",
"operator": "/",
"onLeft": "eventA",
"eventDisplayName": "高级编辑的同时展示示例",
"eventA": {
"analysis": ["#acid","A109"],
"eventName": "#ad_show",
"eventID": 4671,
"eventType": "default",
"filterType": "SIMPLE",
"relation": "and",
"filters": [],
"boundProp": [
{
"id": 1345756,
"app_id": "dt_xxxx",
"table_type": 0,
"name": "#acid",
"column_type": "varchar",
"describe": "应用内账号系统的ID",
"display_name": "账号ID",
"type": 1,
"data_type": "string"
}
]
},
"eventB": {
"eventType": "customized",
"customEvents": "#ad_conversion.A101 / #ad_paid.A100",
"customFilters": [],
"filterType": "SIMPLE",
"relation": "and",
"filters": [],
"boundProp": [null,null]
},
"isAdvancedEdit": true
}
}参数说明：
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
alsoShow
|
Object
|
否
|
当需要使用同时展示时，需要传入该参数
|
| format | String | 是 |
同时展示最终计算结果的精度，与事件分析自定义公式取值一致，包括： 两位小数：'TWO DECIMALS' 三位小数：'THREE DECIMALS' 四位小数：'FOUR DECIMALS' 五位小数：'FIVE DECIMALS' 六位小数：'SIX DECIMALS' 百分比：'PERCENTAGE' 取整：'ROUND' |
|
eventDisplayName
|
String
|
否
|
自定义同时展示指标的显示名 |
|
eventA
|
Object
|
是
|
高级编辑下，“回访用户指标（eventA）”和“初始日期指标（eventB）”都可以使用默认类型以及自定义公式类型的指标，其参数与事件分析对应类型一致，可参照示例以及事件分析中的说明 |
| eventB |
Object
|
是
|
|
| operator | String | 是 | 表明四则运算符，支持"+"、"-"、"*"、"/" |
| onLeft | String | 是 | 表示运算符左侧是什么指标，如果回访用户指标在运算符左侧，则填入"eventA"，如果初始日期指标在运算符左侧，则填入"eventB" |
全局筛选、分组项与计算时间、分析主体参数
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
eventsFilter
|
Object
|
否
|
通用参数，见"如何表示一个筛选项" |
|
eventsGroup
|
Object
|
否
|
通用参数，其中globalization为计算所使用的分组项构成的列表，每一项为一个分组，每一个分组项见"如何表示一个分组项"
|
| globalization |
List[Object]
|
否
|
|
|
eventsView
|
Object
|
是
|
通用参数，见"如何表示计算时间范围以及计算粒度"，留存分析在通用参数的基础上，额外需要补充两个字段，来表明留存天数，例如计算7天的留存，2月的留存 retentionUnitNum：表示留存单位，数值 retentionTimeUnit：表示留存的日期粒度，支持天(day)、周（week）、月(month) |
|
retentionUnitNum
|
Number
|
是
|
|
|
retentionTimeUnit
|
String
|
是
|
|
|
timeZoneOffset
|
Number
|
否
|
计算时区，如8，-8 若未填，表示0时区 |
|
entity
|
Object
|
是
|
分析主体，留存分析支持计算不同的分析主体，例如用户、国家等，一般我们以$uid作为分析主体计算，分析主体的表示见"如何表示分析主体" |
请求响应结果
示例
我们以下图所示的分析场景，进行API查询，那么最终返回结果如下示例
返回结果示例：
{
"indicators_name": ["初始事件自定义显示名","回访事件自定义显示名","同时展示自定义显示名"],
"union_groups_name": ["应用版本号(event)"],
"union_groups": [["0.0~+∞"]],
"axis_x": ["2024-12-25","2024-12-26"],
"axis_y": [
{
"firstevent_num": 5738,
"day_0": 1350,
"day_1": 0,
"day_2": 0,
"day_0_lost": 5208,
"day_1_lost": 0,
"day_2_lost": 0,
"eventb_num": 0,
"day_0_alsoshows": 1350,
"day_1_alsoshows": "-",
"day_2_alsoshows": "-",
"day_0_p": "25.92%",
"day_1_p": "0.00%",
"day_2_p": "0.00%",
"day_0_lost_p": "100.00%",
"day_1_lost_p": "0.00%",
"day_2_lost_p": "0.00%",
"date": "total_amount",
"inadequacy_date": "-",
"groups": [
{
"应用版本号(event)": "0.0~+∞",
"firstevent_num": 5738,
"day_0": 1350,
"day_1": 0,
"day_2": 0,
"day_0_lost": 5208,
"day_1_lost": 0,
"day_2_lost": 0,
"eventb_num": 0,
"day_0_alsoshows": 1350,
"day_1_alsoshows": "-",
"day_2_alsoshows": "-",
"day_0_p": "23.53%",
"day_1_p": "0.00%",
"day_2_p": "0.00%",
"day_0_lost_p": "90.76%",
"day_1_lost_p": "0.00%",
"day_2_lost_p": "0.00%",
"date": "total_amount",
"inadequacy_date": "-"
}
]
},
{
"firstevent_num": 5208,
"day_0": 1350,
"day_1": 32,
"day_2": "-",
"day_0_lost": 5208,
"day_1_lost": 5176,
"day_2_lost": "-",
"eventb_num": 0,
"day_0_alsoshows": 1350,
"day_1_alsoshows": 5,
"day_2_alsoshows": "-",
"day_0_p": "25.92%",
"day_1_p": "0.61%",
"day_2_p": "-",
"day_0_lost_p": "100.00%",
"day_1_lost_p": "99.39%",
"day_2_lost_p": "-",
"date": "2024-12-25",
"inadequacy_date": "day_1",
"groups": [
{
"应用版本号(event)": "0.0~+∞",
"firstevent_num": 5208,
"day_0": 1350,
"day_1": 32,
"day_2": "-",
"day_0_lost": 5208,
"day_1_lost": 5176,
"day_2_lost": "-",
"eventb_num": 0,
"day_0_alsoshows": 1350,
"day_1_alsoshows": 5,
"day_2_alsoshows": "-",
"day_0_p": "25.92%",
"day_1_p": "0.61%",
"day_2_p": "-",
"day_0_lost_p": "100.00%",
"day_1_lost_p": "99.39%",
"day_2_lost_p": "-",
"date": "2024-12-25",
"inadequacy_date": "day_1"
}
]
},
{
"firstevent_num": 530,
"day_0": 96,
"day_1": "-",
"day_2": "-",
"day_0_lost": 530,
"day_1_lost": "-",
"day_2_lost": "-",
"eventb_num": 0,
"day_0_alsoshows": 96,
"day_1_alsoshows": "-",
"day_2_alsoshows": "-",
"day_0_p": "18.11%",
"day_1_p": "-",
"day_2_p": "-",
"day_0_lost_p": "100.00%",
"day_1_lost_p": "-",
"day_2_lost_p": "-",
"date": "2024-12-26",
"inadequacy_date": "day_0",
"groups": [
{
"应用版本号(event)": "0.0~+∞",
"firstevent_num": 530,
"day_0": 96,
"day_1": "-",
"day_2": "-",
"day_0_lost": 530,
"day_1_lost": "-",
"day_2_lost": "-",
"eventb_num": 0,
"day_0_alsoshows": 96,
"day_1_alsoshows": "-",
"day_2_alsoshows": "-",
"day_0_p": "18.11%",
"day_1_p": "-",
"day_2_p": "-",
"day_0_lost_p": "100.00%",
"day_1_lost_p": "-",
"day_2_lost_p": "-",
"date": "2024-12-26",
"inadequacy_date": "day_0"
}
]
}
],
"axis_z": ["#app_install","#ad_to_show","#app_install"],
}响应结果说明
| 字段名 | 字段类型 | 字段说明 |
|
axis_x
|
List[String] |
由计算时间构成的字符串列表， 如果留存按天计算，列表长度则计算范围内的天数，按周计算则长度等于计算范围内的周数 |
|
indicators_name
|
List[String] |
由初始事件、回访事件、同时展示的自定义显示名后成的显示名列表 |
|
union_groups_name
|
List[String] |
本次计算使用的分组项属性构成的数组，长度等于计算时用的分组项个数 |
|
union_groups
|
List[List[String]] |
分组值构成的二维列表，即使用请求参数中的分组，最终可以将结果分成哪些组，外层长度 = 分组结果的个数，内层列表的长度 = 计算时所用的分组项个数，在使用多个分组时，分组值的顺序与union_groups_name的顺序是一致的 |
|
axis_z
|
List[String] |
由初始事件、回访事件、同时展示所使用的事件构成的事件名列表 其中，当同时展示evenA/eventB使用自定义公式时，返回"custom_event_a"/"custom_event_b" |
|
axis_y
|
List[Object] |
每天/周的具体留存人数结果构成的列表，如果计算时，选用天的留存，那么列表的长度 = 计算范围的天数 + 1（+1的原因是额外会计算一个阶段值） |
| date | String |
日期 特殊地，阶段值的该字段值为"total_amount" |
| firstevent_num | Number | 对应日期发生初始事件的用户数 |
|
eventb_num
|
Number|String | 对应日期的初始日期指标值，当使用同时展示，且有回访日期指标时才会有值 |
|
day_(n)
|
Number｜String |
-day_(n)：第n天的留存人数 -day_(n)_p：第n天的留存率 -day_(n)_lost：第n天的流失人数 -day_(n)_lost_p：第n天的流失率 其中n从0开始，一直到计算时所用的留存天数，当未发生时，结果为"-"（例如今天算7天留存，第1-7天还未发生，结果应该为"-"） |
|
day_(n)_p
|
String | |
|
day_(n)_lost
|
Number｜String | |
|
day_(n)_lost_p
|
String | |
|
groups
|
List[Object] |
当使用分组时，会展示对应日期，各个分组的n天的留存人数、留存率、流失人数和流失率。列表长度 = 分组数 对象结构相较于外层day_(n)、day_(n)_p、day_(n)_lost、day_(n)_lost_p外，多了分组的键值对，多的个数取决于使用了几个分组，键名为分组名，值为具体分组值，可见上述示例 |
二、留存分析用户列表查询
在留存分析中，我们可以看到具体某天的后续的留存/流失人数，当我们想查看这些人数具体的用户列表时，可以使用留存分析的用户列表查询API
接口URL
/api/open_api/v1/analysis/retention_user_list?token=xxx
请求方式
POST
Content-Type
application/json
请求Query参数
|
参数名
|
参数类型
|
是否必填
|
参数描述
|
|
token
|
String
|
是
|
查询token
|
请求Body参数
请求的body参数在对应完整使用的留存分析的参数外，额外增加一项details和properties字段，来指明是需要查看查看什么时间什么分组的第x天留存/流失人数
|
参数名
|
参数类型
|
是否必填
|
参数描述
|
| details | Object | 是 | 查询详情 |
| eventModel | String | 是 | 留存分析固定为"retention" |
| sliceDate | String | 是 |
查询具体那一天的数据，对应页面表格的日期列 |
| sliceGroup | List[Object] | 否 |
当计算用了分组时，需要指明最终查询的是哪个分组的列表详情，长度 = 分组项的个数 |
| groupName | String | 是 |
分组属性名 |
| groupValue | String | 是 |
具体分组值 |
| tableType | String | 是 |
分组属性类型 |
| sliceType | String | 是 | 固定传"user" |
| isLost | Number | 是 | 查看留存/流失人数，0为留存，1为流失 |
| retentionStep | Number | 是 | 查看第几天的留存/流失人数，0表示当天 |
| properties | List[Obejct] | 否 |
要查询的事件/用户属性列表，即最终计算结果需要返回的属性 若未传，默认会查询"$uid"、"#dt_id"和"#acid" |
示例
下述示例，即表示在留存分析完成计算后，想要查看12月18号这天，分组是"中国"、"ios"的当天留存人数
{
"firstEvent": {...},
"returnEvent": {...},
"alsoShow": {...},
"eventsFilter":{...},
"eventsGroup":{...},
"eventsView": {...},
"entity":{...},
"timeZoneOffset": 8,
"details": {
"eventModel:"retention",
"sliceType": "user",
"sliceDate": "2024-12-18",
"sliceGroup": [
{
"groupName": "国家",
"groupValue": "中国",
"tableType": "event",
},
{
"groupName": "操作系统",
"groupValue": "ios",
"tableType": "event",
}
],
"retentionStep":0,
"isLost":0
},
"properties": [
{"column_name": "#acid"},
{"column_name": "#app_id"},
{"column_name": "#app_version"},
{"column_name": "#bundle_id"},
{"column_name": "#carrier"},
{"column_name": "#city"},
{"column_name": "#dt_id"},
{"column_name": "$uid"},
{"column_name": "#country"}]
}请求响应结果
| 字段名 | 字段类型 | 字段说明 |
|
columnMeta
|
Object |
所查询的properties的属性映射，键值对的个数 = 请求参数中properties的长度， 键名为属性名，值为属性显示名 |
|
data_list
|
List[Object] | 事件/用户列表详情，长度 = 计算的结果数，对象中为属性名：属性值的键值对 |
|
total
|
Number | 总数，最多返回1000条 |
示例
{
"columnMeta": {
"#acid": "账号 ID",
"#app_id": "应用唯一标识",
"#app_version": "应用版本",
"#bundle_id": "应用包名",
"#carrier": "运营商",
"#city": "城市",
"#country": "国家",
"#dt_id": "访客ID",
"$uid": "DT 用户 ID"
},
"total": 1,
"data_list": [
{
"#acid": "0@5IZJI4YUWZcard_games",
"#app_id": "dt_xxxx",
"#app_version": "app2.0.1",
"#bundle_id": null,
"#carrier": "移动",
"#city": "纽约",
"#country": "中国",
"#dt_id": "dddddd",
"$uid": "123232455"
},
],
}