CohortSpec

  • Cohort reports analyze user retention over time by grouping users with a shared characteristic.

  • Thecohort object defines the criteria for selecting a cohort, such as users acquired within a specific date range.

  • ThecohortsRange object specifies the extended date range over which the cohort is tracked, using a defined granularity and offsets.

  • The granularity can be daily, weekly, or monthly, determining how thestartOffset andendOffset are interpreted.

The specification of cohorts for a cohort report.

Cohort reports create a time series of user retention for the cohort. For example, you could select the cohort of users that were acquired in the first week of September and follow that cohort for the next six weeks. Selecting the users acquired in the first week of September cohort is specified in thecohort object. Following that cohort for the next six weeks is specified in thecohortsRange object.

For examples, seeCohort Report Examples.

The report response could show a weekly time series where say your app has retained 60% of this cohort after three weeks and 25% of this cohort after six weeks. These two percentages can be calculated by the metriccohortActiveUsers/cohortTotalUsers and will be separate rows in the report.

JSON representation
{"cohorts":[{object (Cohort)}],"cohortsRange":{object (CohortsRange)},"cohortReportSettings":{object (CohortReportSettings)}}
Fields
cohorts[]

object (Cohort)

Defines the selection criteria to group users into cohorts.

Most cohort reports define only a single cohort. If multiple cohorts are specified, each cohort can be recognized in the report by their name.

cohortsRange

object (CohortsRange)

Cohort reports follow cohorts over an extended reporting date range. This range specifies an offset duration to follow the cohorts over.

cohortReportSettings

object (CohortReportSettings)

Optional settings for a cohort report.

Cohort

Defines a cohort selection criteria. A cohort is a group of users who share a common characteristic. For example, users with the samefirstSessionDate belong to the same cohort.

JSON representation
{"name":string,"dimension":string,"dateRange":{object (DateRange)}}
Fields
name

string

Assigns a name to this cohort. The dimensioncohort is valued to this name in a report response. If set, cannot begin withcohort_ orRESERVED_. If not set, cohorts are named by their zero based indexcohort_0,cohort_1, etc.

dimension

string

Dimension used by the cohort. Required and only supportsfirstSessionDate.

dateRange

object (DateRange)

The cohort selects users whose first touch date is between start date and end date defined in thedateRange. ThisdateRange does not specify the full date range of event data that is present in a cohort report. In a cohort report, thisdateRange is extended by the granularity and offset present in thecohortsRange; event data for the extended reporting date range is present in a cohort report.

In a cohort request, thisdateRange is required and thedateRanges in theRunReportRequest orRunPivotReportRequest must be unspecified.

ThisdateRange should generally be aligned with the cohort's granularity. IfCohortsRange uses daily granularity, thisdateRange can be a single day. IfCohortsRange uses weekly granularity, thisdateRange can be aligned to a week boundary, starting at Sunday and ending Saturday. IfCohortsRange uses monthly granularity, thisdateRange can be aligned to a month, starting at the first and ending on the last day of the month.

CohortsRange

Configures the extended reporting date range for a cohort report. Specifies an offset duration to follow the cohorts over.

JSON representation
{"granularity":enum (Granularity),"startOffset":integer,"endOffset":integer}
Fields
granularity

enum (Granularity)

Required. The granularity used to interpret thestartOffset andendOffset for the extended reporting date range for a cohort report.

startOffset

integer

startOffset specifies the start date of the extended reporting date range for a cohort report.startOffset is commonly set to 0 so that reports contain data from the acquisition of the cohort forward.

Ifgranularity isDAILY, thestartDate of the extended reporting date range isstartDate of the cohort plusstartOffset days.

Ifgranularity isWEEKLY, thestartDate of the extended reporting date range isstartDate of the cohort plusstartOffset * 7 days.

Ifgranularity isMONTHLY, thestartDate of the extended reporting date range isstartDate of the cohort plusstartOffset * 30 days.

endOffset

integer

Required.endOffset specifies the end date of the extended reporting date range for a cohort report.endOffset can be any positive integer but is commonly set to 5 to 10 so that reports contain data on the cohort for the next several granularity time periods.

Ifgranularity isDAILY, theendDate of the extended reporting date range isendDate of the cohort plusendOffset days.

Ifgranularity isWEEKLY, theendDate of the extended reporting date range isendDate of the cohort plusendOffset * 7 days.

Ifgranularity isMONTHLY, theendDate of the extended reporting date range isendDate of the cohort plusendOffset * 30 days.

Granularity

The granularity used to interpret thestartOffset andendOffset for the extended reporting date range for a cohort report.

Enums
GRANULARITY_UNSPECIFIEDShould never be specified.
DAILYDaily granularity. Commonly used if the cohort'sdateRange is a single day and the request containscohortNthDay.
WEEKLYWeekly granularity. Commonly used if the cohort'sdateRange is a week in duration (starting on Sunday and ending on Saturday) and the request containscohortNthWeek.
MONTHLYMonthly granularity. Commonly used if the cohort'sdateRange is a month in duration and the request containscohortNthMonth.

CohortReportSettings

Optional settings of a cohort report.

JSON representation
{"accumulate":boolean}
Fields
accumulate

boolean

If true, accumulates the result from first touch day to the end day. Not supported inRunReportRequest.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-11-19 UTC.