menu
Is this helpful?

# 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
eventView.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
eventView.filts - List No Global filter
eventView.filts.columnDesc App version String No Field display name
eventView.filts.columnName app_version String Yes Field name
eventView.filts.comparator equal String Yes Reference: filtering expression of model query API
eventView.filts.filterType SIMPLE String No Filter mode, SIMPLE: simple, COMPOUND: composite
eventView.filts.ftv ["V1.0"] List No Property comparative with bound literial
eventView.filts.specifiedClusterDate 2022-01-24 String No Historical tag version of specified date
eventView.filts.tableType event String Yes Table type enumeration
eventView.filts.timeUnit String No Property filter unit, only valid to relativeEvent*:day,hour,minute
eventView.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
eventView.groupBy - List No Group attributes, can have zero or more
eventView.groupBy.columnDesc Browser String No Field display name
eventView.groupBy.columnName browser String Yes Field name
eventView.groupBy.propertyRange String No Self-defined property interval
eventView.groupBy.specifiedClusterDate 2022-01-24 String No Historical tag version of specified date
eventView.groupBy.tableType event String Yes Table type enumeration
eventView.recentDay String No Relative time (this item cannot be empty both with the start time and the end time)
eventView.relation and String No Logical relationship, and: logical and, or: logical or
eventView.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
eventView.statType retention String Yes Statistics type, retention: retention, loss: lost
eventView.taIdMeasureVo - Object No Query ID system configuration
eventView.taIdMeasureVo.columnDesc User unique ID String No Field display name
eventView.taIdMeasureVo.columnName #user_id String Yes Field name
eventView.taIdMeasureVo.tableType event String Yes Table type enumeration
eventView.timeParticleSize week String Yes Unit of the time period taken for analysis
  • day: based on days

  • week: based on weeks

  • month: based on months

eventView.unitNum 1 Integer Yes Retention period
events - List Yes Event metric list
events.eventName login String Yes The eventName the metric based on, "anyEvent" can be used to represent any event
events.eventNameDisplay String No Self-defined metric display name
events.analysis TRIG_USER_NUM String Analysis aspect for simutaneous display, aggregation for Aggregate type enumeration for simultaneous analysis
events.analysisDesc TOTAL_TIMES String Analysis aspect description for simutaneous display
events.filts - List No Condition list
events.filts.columnDesc app_version String No Field display name
events.filts.columnName app_version String Yes Field name
events.filts.comparator equal String Yes Reference: filtering expression of model query API
events.filts.filterType SIMPLE String No Filtering mode, SIMPLE:simple, COMPOUND:compound, default as SIMPLE
events.filts.ftv ["V1.0"] List No Property comparison value
events.filts.specifiedClusterDate 2022-01-26 String No Cluster specified date
events.filts.tableType event String Yes Table type enumeration
events.filts.timeUnit String No Unit of the time taken for filtering
events.relation and String No Logical relation,and:logic and,or:logic or
events.relationUser and String No User filtering logical relationships, and: logical and, or: logical or
events.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 Identity.
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 results
data.result_generate_time 2022-01-01 00:00:00 String Query result generation time
data.state_avg - Object Result map with key as type and value as retention grouping
data.state_avg.{type} - List Type value, 0: retention, 1: loss, 2: statistics
data.state_avg.{type}.groupCols ["Overall"] List Grouping columns
data.state_avg.{type}.initNum 0 Integer Initial value
data.state_avg.{type}.isTotal 1 Integer Is it summary, 1: yes, 0: no
data.state_avg.{type}.lastValidDateVerticalIndexs ["-", "4"] List Last complete Data Date Index
data.state_avg.{type}.values ["-", "0.998"] List Value list, "-" or number
data.x ["2021-09-27"] List Date List
data.y - Object Y-axis data
data.y.{type} - Object Type value, 0: retention, 1: loss, 2: statistics
data.y.{type}.{date} - List Key is date
data.y.{type}.{date}.groupCols ["Overall"] List Grouping columns
data.y.{type}.{date}.includeToday false Boolean Does it include today
data.y.{type}.{date}.initNum 7388 Integer Initial value
data.y.{type}.{date}.isTotal 1 Integer Is it summary, 1: yes, 0: no
data.y.{type}.{date}.values ["7388"] List Value list
data.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