# Retention Analysis Model API
As for the call method, please refer to the call method description in Open API
You can read the retention analysis in the user manual to understand the usage scenario.
# Retention Analysis Query
Interface URL
/open/retention-analyze?token=xxx
Request method
POST
Content-Type
application/json
Request Query Parameter
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| token | xxx | String | Yes | token |
# Request Body Parameter
{
"eventView":{
"endTime":"2021-10-30 23:59:59",
"filts":[
{
"columnDesc":"app version",
"columnName":"app_version",
"comparator":"equal",
"filterType":"SIMPLE",
"ftv":[
"V1.0"],
"specifiedClusterDate":"2022-01-24",
"tableType":"event",
"timeUnit":""
}],
"firstDayOfWeek":1,
"groupBy":[
{
"columnDesc": "browser",
"columnName":"browser",
"propertyRange":"",
"specifiedClusterDate":"2022-01-24",
"tableType":"event"
}],
"recentDay":"",
"relation":"and",
"startTime":"2021-10-01 00:00:00",
"statType":"retention",
"taIdMeasureVo":{
"columnDesc":"user only ID",
"columnName":"#user_id",
"tableType":"event"
},
"timeParticleSize":"week",
"unitNum":1
},
"events":[
{
"eventName":"login",
"eventNameDisplay":"",
"filts":[
{
"columnDesc":"app_version",
"columnName":"app_version",
"comparator":"equal",
"filterType":"SIMPLE",
"ftv":["V1.0"],
"specifiedClusterDate":"2022-01-26",
"tableType":"event",
"timeUnit":""
}],
"relation":"and",
"relationUser":"and",
"type":"first"
},
{
"eventName":"logout",
"eventNameDisplay":"",
"filts":[
],
"relation":"and",
"relationUser":"and",
"type":"second"
},
{
"analysis":"TOTAL_TIMES",
"analysisDesc":"total number",
"eventName":"activity_attend",
"eventNameDisplay":"",
"filts":[
],
"quota":"",
"relation":"and",
"relationUser":"and",
"type":"simultaneous_display"
}],
"projectId": 377,
"limit": 2,
"timeoutSeconds": 10,
"useCache": true
}
# Request Parameter Description
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| eventView | - | Object | Yes | Metrics common attribute part |
| ∟ endTime | 2021-10-30 23:59:59 | String | No | End time (format: yyyy-MM-dd HH: mm: ss), valid when the relative time is empty |
| ∟ filts | - | List | No | Global filter |
| ∟ columnDesc | App version | String | No | Field display name |
| ∟ columnName | app_version | String | Yes | Field name |
| ∟ comparator | equal | String | Yes | Reference: filtering expression of model query API |
| ∟ filterType | SIMPLE | String | No | Filter mode, SIMPLE: simple, COMPOUND: composite |
| ∟ ftv | ["V1.0"] | List | No | Property comparative with bound literial |
| ∟ specifiedClusterDate | 2022-01-24 | String | No | Historical tag version of specified date |
| ∟ tableType | event | String | Yes | Table type enumeration |
| ∟ timeUnit | String | No | Property filter unit, only valid to relativeEvent*：day，hour，minute | |
| ∟ firstDayOfWeek | 1 | Integer | No | When timeParticleSize is week, specify the first day of the week, 1: Monday, 2: Tuesday,.., 7: Sunday, minimum 1, maximum 7 |
| ∟ groupBy | - | List | No | Group attributes, can have zero or more |
| ∟ columnDesc | Browser | String | No | Field display name |
| ∟ columnName | browser | String | Yes | Field name |
| ∟ propertyRange | String | No | Self-defined property interval | |
| ∟ specifiedClusterDate | 2022-01-24 | String | No | Historical tag version of specified date |
| ∟ tableType | event | String | Yes | Table type enumeration |
| ∟ recentDay | String | No | Relative time (this item cannot be empty both with the start time and the end time) | |
| ∟ relation | and | String | No | Logical relationship, and: logical and, or: logical or |
| ∟ startTime | 2021-10-01 00:00:00 | String | No | Start time (format: yyyy-MM-dd HH: mm: ss), valid when the relative time is empty |
| ∟ statType | retention | String | Yes | Statistics type, retention: retention, loss: lost |
| ∟ taIdMeasureVo | - | Object | No | Query ID system configuration |
| ∟ columnDesc | User unique ID | String | No | Field display name |
| ∟ columnName | #user_id | String | Yes | Field name |
| ∟ tableType | event | String | Yes | Table type enumeration |
| ∟ timeParticleSize | week | String | Yes | Unit of the time period taken for analysis day: based on days week: based on weeks month: based on months |
| ∟ unitNum | 1 | Integer | Yes | Retention period |
| events | - | List | Yes | Event metric list |
| ∟ eventName | login | String | Yes | The eventName the metric based on, "anyEvent" can be used to represent any event |
| ∟ eventNameDisplay | String | No | Self-defined metric display name | |
| ∟ analysis | TRIG_USER_NUM | String | 否 | Analysis aspect for simutaneous display, aggregation for Aggregate type enumeration for simultaneous analysis |
| ∟ analysisDesc | TOTAL_TIMES | String | 否 | Analysis aspect description for simutaneous display |
| ∟ filts | - | List | No | Condition list |
| ∟ columnDesc | app_version | String | No | Field display name |
| ∟ columnName | app_version | String | Yes | Field name |
| ∟ comparator | equal | String | Yes | Reference: filtering expression of model query API |
| ∟ filterType | SIMPLE | String | No | Filtering mode, SIMPLE：simple, COMPOUND：compound, default as SIMPLE |
| ∟ ftv | ["V1.0"] | List | No | Property comparison value |
| ∟ specifiedClusterDate | 2022-01-26 | String | No | Cluster specified date |
| ∟ tableType | event | String | Yes | Table type enumeration |
| ∟ timeUnit | String | No | Unit of the time taken for filtering | |
| ∟ relation | and | String | No | Logical relation，and：logic and，or：logic or |
| ∟ relationUser | and | String | No | User filtering logical relationships, and: logical and, or: logical or |
| ∟ type | first | String | Yes | Retention event type, First: Initial event Second: Return visit event simultaneous_display: Simultaneous display init_date_stat: Initial date indicator |
| projectId | 377 | Integer | Yes | Project numeric I dentity. |
| limit | 2 | Integer | No | Maximum number of groups per analysis object, optional parameters, default is 1000, maximum is 10000 |
| timeoutSeconds | 10 | Integer | No | Request timed out parameter, timeout cancels query task |
| useCache | true | Boolean | No | Use cache, optional parameter, default is true |
# Successful Response Example
{
"data": {
"result_generate_time": "2022-01-01 00:00:00",
"state_avg": {
"0": [
{
"groupCols": [
"total"
],
"initNum": 0,
"isTotal": 1,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"0.998"
]
},
{
"groupCols": [
"Chrome"
],
"initNum": 0,
"isTotal": 0,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"0.9981"
]
}
],
"1": [
{
"groupCols": [
"total"
],
"initNum": 0,
"isTotal": 1,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"1"
]
},
{
"groupCols": [
"Chrome"
],
"initNum": 0,
"isTotal": 0,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"1"
]
}
],
"2": [
{
"groupCols": [
"total"
],
"initNum": 0,
"isTotal": 1,
"lastValidDateVerticalIndexs": [],
"values": [
"-",
"132405.4"
]
},
{
"groupCols": [
"Chrome"
],
"initNum": 0,
"isTotal": 0,
"lastValidDateVerticalIndexs": [],
"values": [
"-",
"66343.2"
]
}
]
},
"x": [
"2021-09-27",
"2021-10-04",
"2021-10-11",
"2021-10-18",
"2021-10-25"
],
"y": {
"0": {
"2021-09-27": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7388,
"isTotal": 1,
"values": [
"7388",
"7374"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3647,
"isTotal": 0,
"values": [
"3647",
"3642"
]
}
],
"2021-10-04": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7861,
"isTotal": 1,
"values": [
"7861",
"7844"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3939,
"isTotal": 0,
"values": [
"3939",
"3930"
]
}
],
"2021-10-11": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8013,
"isTotal": 1,
"values": [
"8013",
"7994"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4062,
"isTotal": 0,
"values": [
"4062",
"4054"
]
}
],
"2021-10-18": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8553,
"isTotal": 1,
"values": [
"8553",
"8543"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4225,
"isTotal": 0,
"values": [
"4225",
"4218"
]
}
],
"2021-10-25": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7414,
"isTotal": 1,
"values": [
"7414",
"7397"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3741,
"isTotal": 0,
"values": [
"3741",
"3733"
]
}
]
},
"1": {
"2021-09-27": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7388,
"isTotal": 1,
"values": [
"7388",
"7388"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3647,
"isTotal": 0,
"values": [
"3647",
"3647"
]
}
],
"2021-10-04": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7861,
"isTotal": 1,
"values": [
"7861",
"7861"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3939,
"isTotal": 0,
"values": [
"3939",
"3939"
]
}
],
"2021-10-11": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8013,
"isTotal": 1,
"values": [
"8013",
"8013"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4062,
"isTotal": 0,
"values": [
"4062",
"4062"
]
}
],
"2021-10-18": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8553,
"isTotal": 1,
"values": [
"8553",
"8553"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4225,
"isTotal": 0,
"values": [
"4225",
"4225"
]
}
],
"2021-10-25": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7414,
"isTotal": 1,
"values": [
"7414",
"7414"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3741,
"isTotal": 0,
"values": [
"3741",
"3741"
]
}
]
},
"2": {
"2021-09-27": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7388,
"isTotal": 1,
"values": [
"0",
"125324"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3647,
"isTotal": 0,
"values": [
"0",
"62105"
]
}
],
"2021-10-04": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7861,
"isTotal": 1,
"values": [
"0",
"132130"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3939,
"isTotal": 0,
"values": [
"0",
"65971"
]
}
],
"2021-10-11": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8013,
"isTotal": 1,
"values": [
"0",
"134691"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4062,
"isTotal": 0,
"values": [
"0",
"68566"
]
}
],
"2021-10-18": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8553,
"isTotal": 1,
"values": [
"0",
"144030"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4225,
"isTotal": 0,
"values": [
"0",
"71345"
]
}
],
"2021-10-25": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7414,
"isTotal": 1,
"values": [
"0",
"125852"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3741,
"isTotal": 0,
"values": [
"0",
"63729"
]
}
]
}
},
"z": [
"login",
"logout",
"activity_attend"
]
},
"return_code": 0,
"return_message": "success"
}
# Response Parameter Description
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | 0 | Integer | Return code |
| return_message | success | String | Return message |
| data | - | Object | Return result s |
| ∟ result_generate_time | 2022-01-01 00:00:00 | String | Query result generation time |
| ∟ state_avg | - | Object | Result map with key as type and value as retention grouping |
| ∟ {type} | - | List | Type value, 0: retention, 1: loss, 2: statistics |
| ∟ groupCols | ["Overall"] | List | Grouping columns |
| ∟ initNum | 0 | Integer | Initial value |
| ∟ isTotal | 1 | Integer | Is it summary, 1: yes, 0: no |
| ∟ lastValidDateVerticalIndexs | ["-", "4"] | List | Last complete Data Date Index |
| ∟ values | ["-", "0.998"] | List | Value list, "-" or number |
| ∟ x | ["2021-09-27"] | List | Date List |
| ∟ y | - | Object | Y-axis data |
| ∟ {type} | - | Object | Type value, 0: retention, 1: loss, 2: statistics |
| ∟ {date} | - | List | Key is date |
| ∟ groupCols | ["Overall"] | List | Grouping columns |
| ∟ includeToday | false | Boolean | Does it include today |
| ∟ initNum | 7388 | Integer | Initial value |
| ∟ isTotal | 1 | Integer | Is it summary, 1: yes, 0: no |
| ∟ values | ["7388"] | List | Value list |
| ∟ z | ["login"] | List | List of event names |
Error Response Example
{
"return_code": -1008,
"return_message": "The parameter (token) is empty"
}
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | -1008 | Integer | Return code |
| return_message | The parameter (token) is empty | String | Return message |
# Retention Analysis Full Data Download
Interface URL
/open/streaming-download/retention-analyze?token=xxx
Request method
POST
Content-Type
application/json
Request Query Parameter
| Parameter name | Sample value | Parameter type | Mandatory or not | Parameter description |
|---|---|---|---|---|
| token | xxx | String | Yes | Query key |
# Request Body parameter
{
"eventView": {
"collectFirstDay": 1,
"endTime": "2022-03-08 16:55:10",
"filts": [],
"groupBy": [{
"columnDesc": "Channel",
"columnName": "channel",
"propertyRange": "",
"specifiedClusterDate": "2022-03-09",
"tableType": "event"
}],
"recentDay": "1-7",
"relation": "and",
"startTime": "2022-03-02 16:55:10",
"statType": "retention",
"taIdMeasureVo": {
"columnDesc": "User unique identification",
"columnName": "#user_id",
"tableType": "event"
},
"timeParticleSize": "day",
"unitNum": 7
},
"events": [{
"eventName": "Recharge",
"eventNameDisplay": "",
"filts": [],
"relation": "and",
"relationUser": "and",
"type": "first"
}],
"projectId": 390
}
# Request Parameter Description
| Parameter name | Sample value | Parameter type | Mandatory or not | Parameter description |
|---|---|---|---|---|
| eventView | - | Object | Yes | Same parameters as Retention Analysis Query interface |
| events | - | List | Yes | Same parameters as Retention Analysis Query interface |
| projectId | 377 | Integer | Yes | Project numeric identity |
# Response
Same with the full data download of the retention analysis of the TE system
# Retention Analysis User List
Interface URL
/open/retention-user-list?token=xxx
Request method
POST
Content-Type
application/json
Request Query Parameter
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| token | xxx | String | Yes | token |
# Request Body Parameter
{
"projectId": 0,
"eventView": {
"startTime": "2019-11-24 00:00:00",
"endTime": "2019-11-26 00:00:00",
"recentDay": "1-3",
"statType": "retention",
"timeParticleSize": "day",
"unitNum": 7,
"groupBy": [
{
"columnName": "#province",
"tableType": "event"
}
]
},
"events": [
{
"type": "first",
"relation": "and",
"eventName": "player_register",
"filts": [
{
"columnName": "#province",
"comparator": "equal",
"ftv": [
"Jiangsu",
"Shanghai"
],
"tableType": "event"
},
{
"columnName": "user_level",
"comparator": "greater",
"ftv": [
"2"
],
"tableType": "user"
}
]
},
{
"type": "second",
"relation": "and",
"eventName": "obtain_diamond",
"filts": [
{
"columnName": "#os",
"comparator": "equal",
"ftv": [
"android"
],
"tableType": "event"
},
{
"$ref": "$.events[0].filts[1]"
}
]
}
],
"sliceDate": "2019-11-26",
"sliceInterval": 3,
"timeoutSeconds": 10
}
# Request Parameter Description
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| projectId | 0 | String | Yes | Project numeric identity |
| eventView | - | Object | Yes | Same parameters as Retention Analysis Query interface |
| events | List | Yes | Same parameters as Retention Analysis Query interface | |
| sliceDate | "2019-11-26" | String | No | Go into detail by which date |
| sliceGroupVal | ["Beijing"] | List | Yes | Go into detail by which group |
| sliceInterval | 3 | List | Yes | Go into detail by which retention interval 0: Initial event number of users 1: The current {date unit} 2: After 1 {date unit} 3: After 2 {date unit} |
| timeoutSeconds | 10 | Integer | No | Request timed out parameter, timeout cancels query task |
# Successful Response Example
{
"data": {
"datalist": [
{
"#account_id": "v47739399",
"#distinct_id": "v88658799",
"user_level": 11,
"register_time": "2019-11-26 19:13:20",
"diamond_num": 1182,
"latest_login_time": "2019-11-26 20:16:19",
"channel": "Huawei App store",
"#user_id": 20459799
},
{
"#account_id": "i7819568",
"#distinct_id": "i14522048",
"user_level": 4,
"register_time": "2019-11-26 23:56:17",
"diamond_num": 1006,
"latest_login_time": "2019-11-26 23:59:59",
"channel": "360 Mobile Assistant",
"#user_id": 3351248
},
{
"#account_id": "g7812426",
"#distinct_id": "g14508786",
"user_level": 14,
"register_time": "2019-11-26 17:54:13",
"diamond_num": 245,
"first_recharge_time": "2019-11-26 18:08:58",
"latest_login_time": "2019-11-26 20:16:19",
"channel": "Xiaomi App stor",
"#user_id": 3348186
},
{
"#account_id": "a7812000",
"#distinct_id": "a14508000",
"user_level": 3,
"register_time": "2019-11-26 17:27:28",
"diamond_num": 1153,
"latest_login_time": "2019-11-26 18:45:58",
"channel": "app store",
"#user_id": 3348000
}
],
"columMeta": {
"#account_id": "account ID",
"#distinct_id": "visitor ID",
"user_level": "user level",
"register_time": "register time",
"diamond_num": "diamond number",
"first_recharge_time": "first recharge time",
"latest_login_time": "lastest login time",
"channel": "channel"
}
},
"return_code": 0,
"return_message": "success"
}
# Response Parameter Description
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | 0 | Integer | Return code |
| return_message | success | String | Return message |
| data | - | Object | Return result |
| data.datalist | - | List | User Information |
| data.columMeta | - | Map | Field meaning mapping |
Error Response Example
{
"return_code": -1008,
"return_message": "The parameter (token) is empty"
}
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | -1008 | Integer | Return code |
| return_message | The parameter (token) is empty | String | Return information |
# Download of Retention Analysis User List
Interface URL
/open/streaming-download/retention-user-list?token=xxx
Request method
POST
Content-Type
application/json
Request Query parameters
| Parameter name | Sample value | Parameter type | Mandatory or not | Parameter description |
|---|---|---|---|---|
| token | xxx | String | Yes | Query key |
# Request Body Parameters
{
"eventView": {
"collectFirstDay": 1,
"endTime": "2022-03-07 17:09:58",
"filts": [],
"groupBy": [],
"recentDay": "1-7",
"relation": "and",
"startTime": "2022-03-01 17:09:58",
"statType": "retention",
"taIdMeasureVo": {
"columnDesc": "User ID",
"columnName": "#user_id",
"tableType": "event"
},
"timeParticleSize": "day",
"unitNum": 7
},
"events": [{
"eventName": "Login",
"eventNameDisplay": "",
"filts": [],
"relation": "and",
"relationUser": "and",
"type": "first"
}, {
"eventName": "Recharge",
"eventNameDisplay": "",
"filts": [],
"relation": "and",
"relationUser": "and",
"type": "second"
}],
"projectId": 319,
"isLost": false,
"sliceDate": "2022-03-01",
"sliceInterval": 0,
"selectedColumns": ["#account_id", "#distinct_id"]
}
# Request Parameter Description
| Parameter name | Sample value | Parameter type | Mandatory or not | Parameter description |
|---|---|---|---|---|
| eventView | - | Object | 是 | Same parameters as Retention Analysis Query interface |
| events | - | List | 是 | Same parameters as Retention Analysis Query interface |
| projectId | 377 | Integer | 是 | The columns to be downloaded |
| isLost | false | Boolean | 是 | Whether Download lost data |
| sliceDate | "2019-11-26" | String | 否 | Go into detail by which date |
| sliceGroupVal | ["Beijing"] | List | 否 | Go into detail by which group |
| sliceInterval | 0 | Integer | Yes | Go into detail by which retention interval 0: Initial event number of users 1: The current {date unit} 2: After 1 {date unit} 3: After 2 {date unit} |
| selectedColumns | ["#account_id"] | List | Yes | The columns to be downloaded |
TIP
The main structure of request parameters could be exported from the retention analysis screen of the TE system, while such parameters as isLost, sliceDate, sliceGroupVal, sliceInterval, selectedColumns could be added to indicate how to go to the detail.
# Response
Same with the download of the retention analysis user list of the TE system.
# Generic enumeration for simultaneous analysis
# Aggregate type enumeration for simultaneous analysis
| Value | Description | Whether properties are required |
|---|---|---|
| TOTAL_TIMES | Total number | No |
| TRIG_USER_NUM | Number of users triggered | No |
| PER_CAPITA_TIMES | Number of times per capita | No |
| SUM | Sum of values | Yes |
| FOR _ CAPITA _ NUM | Per capita | Yes |
| STAGE_ACC | Accumulated sum of stages | Yes |
| STAGE_ACC_PCV | Stage cumulative average | Yes |
| TRUE | True number | Yes |
| FALSE | False number | Yes |
| IS_NOT_EMPTY | Not an empty number | Yes |
| IS_EMPTY | Null number | Yes |