diff --git a/google/analytics/data/v1alpha/analytics_data_api.proto b/google/analytics/data/v1alpha/analytics_data_api.proto index cabd1736..7f5f9f9b 100644 --- a/google/analytics/data/v1alpha/analytics_data_api.proto +++ b/google/analytics/data/v1alpha/analytics_data_api.proto @@ -145,14 +145,14 @@ message RunReportRequest { // The row count of the start row. The first row is counted as row 0. // // To learn more about this pagination parameter, see - // [Pagination](basics#pagination). + // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination). int64 offset = 5; // The number of rows to return. If unspecified, 10 rows are returned. If // -1, all rows are returned. // // To learn more about this pagination parameter, see - // [Pagination](basics#pagination). + // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination). int64 limit = 6; // Aggregation of metrics. Aggregated metric values will be shown in rows @@ -217,7 +217,7 @@ message RunReportResponse { // = 175 but only 50 rows. // // To learn more about this pagination parameter, see - // [Pagination](basics#pagination). + // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination). int32 row_count = 12; // Metadata for the report. @@ -388,7 +388,7 @@ message GetMetadataRequest { // specified in the URL path and not URL parameters. Property is a numeric // Google Analytics GA4 Property identifier. To learn more, see [where to find // your Property - // ID](https://developers.google.com/analytics/trusted-testing/analytics-data/property-id). + // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id). // // Example: properties/1234/metadata // @@ -408,7 +408,7 @@ message RunRealtimeReportRequest { // A Google Analytics GA4 property identifier whose events are tracked. // Specified in the URL path and not the body. To learn more, see [where to // find your Property - // ID](https://developers.google.com/analytics/trusted-testing/analytics-data/property-id). + // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id). // // Example: properties/1234 string property = 1; diff --git a/google/analytics/data/v1alpha/data.proto b/google/analytics/data/v1alpha/data.proto index a1df5efe..aafd1768 100644 --- a/google/analytics/data/v1alpha/data.proto +++ b/google/analytics/data/v1alpha/data.proto @@ -47,7 +47,7 @@ message DateRange { message Entity { // A Google Analytics GA4 property id. To learn more, see [where to find your // Property - // ID](https://developers.google.com/analytics/trusted-testing/analytics-data/property-id). + // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id). string property_id = 1; } @@ -57,7 +57,7 @@ message Entity { // Requests are allowed up to 8 dimensions. message Dimension { // The name of the dimension. See the [API - // Dimensions](https://developers.google.com/analytics/trusted-testing/analytics-data/api-schema#dimensions) + // Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions) // for the list of dimension names. // // If `dimensionExpression` is specified, `name` can be any string that you @@ -120,7 +120,7 @@ message DimensionExpression { // metrics. message Metric { // The name of the metric. See the [API - // Metrics](https://developers.google.com/analytics/trusted-testing/analytics-data/api-schema#metrics) + // Metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics) // for the list of metric names. // // If `expression` is specified, `name` can be any string that you would like. @@ -399,20 +399,35 @@ message Pivot { repeated MetricAggregation metric_aggregations = 5; } -// Specification for a cohort report. +// Specification of cohorts for a cohort report. +// Cohort reports can be used for example to 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 the `cohort` object. Following that +// cohort for the next six weeks is specified in the `cohortsRange` object. +// +// 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 metric +// `cohortActiveUsers/cohortTotalUsers` and will be separate rows in the report. message CohortSpec { - // The definition for the cohorts. + // 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. repeated Cohort cohorts = 1; - // The data ranges of cohorts. + // Cohort reports follow cohorts over an extended reporting date range. This + // range specifies an offset duration to follow the cohorts over. CohortsRange cohorts_range = 2; - // Settings of a cohort report. + // Optional settings for a cohort report. CohortReportSettings cohort_report_settings = 3; } -// Defines a cohort. A cohort is a group of users who share a common -// characteristic. For example, all users with the same acquisition date +// Defines a cohort selection criteria. A cohort is a group of users who share +// a common characteristic. For example, users with the same `firstTouchDate` // belong to the same cohort. message Cohort { // Assigns a name to this cohort. The dimension `cohort` is valued to this @@ -421,61 +436,92 @@ message Cohort { // `cohort_0`, `cohort_1`, etc. string name = 1; - // The dimension used by cohort. Only supports `firstTouchDate` for retention - // report. + // Dimension used by the cohort. Required and only supports `firstTouchDate`. string dimension = 2; - // The cohort selects users whose first visit date is between start date - // and end date defined in the `dateRange`. In a cohort request, this - // `dateRange` is required and the `dateRanges` in the `RunReportRequest` or - // `RunPivotReportRequest` must be unspecified. + // The cohort selects users whose first touch date is between start date and + // end date defined in the `dateRange`. This `dateRange` does not specify the + // full date range of event data that is present in a cohort report. In a + // cohort report, this `dateRange` is extended by the granularity and offset + // present in the `cohortsRange`; event data for the extended reporting date + // range is present in a cohort report. // - // The date range should be aligned with the cohort's granularity. If - // CohortsRange uses daily granularity, the date range can be aligned to any - // day. If CohortsRange uses weekly granularity, the date range should be - // aligned to the week boundary, starting at Sunday and ending Saturday. If - // CohortsRange uses monthly granularity, the date range should be aligned to - // the month, starting at the first and ending on the last day of the month. + // In a cohort request, this `dateRange` is required and the `dateRanges` in + // the `RunReportRequest` or `RunPivotReportRequest` must be unspecified. + // + // This `dateRange` should generally be aligned with the cohort's granularity. + // If `CohortsRange` uses daily granularity, this `dateRange` can be a single + // day. If `CohortsRange` uses weekly granularity, this `dateRange` can be + // aligned to a week boundary, starting at Sunday and ending Saturday. If + // `CohortsRange` uses monthly granularity, this `dateRange` can be aligned to + // a month, starting at the first and ending on the last day of the month. DateRange date_range = 3; } -// Settings of a cohort report. -message CohortReportSettings { - // If true, accumulates the result from first visit day to the end day. Not - // supported in `RunReportRequest`. - bool accumulate = 1; -} - -// Describes date range for a cohort report. +// Configures the extended reporting date range for a cohort report. Specifies +// an offset duration to follow the cohorts over. message CohortsRange { - // Reporting granularity for the cohorts. + // The granularity used to interpret the `startOffset` and `endOffset` for the + // extended reporting date range for a cohort report. enum Granularity { - // Unspecified. + // Should never be specified. GRANULARITY_UNSPECIFIED = 0; - // Daily + // Daily granularity. Commonly used if the cohort's `dateRange` is a single + // day and the request contains `cohortNthDay`. DAILY = 1; - // Weekly + // Weekly granularity. Commonly used if the cohort's `dateRange` is a week + // in duration (starting on Sunday and ending on Saturday) and the request + // contains `cohortNthWeek`. WEEKLY = 2; - // Monthly + // Monthly granularity. Commonly used if the cohort's `dateRange` is a month + // in duration and the request contains `cohortNthMonth`. MONTHLY = 3; } - // Reporting date range for each cohort is calculated based on these three - // fields. + // The granularity used to interpret the `startOffset` and `endOffset` for the + // extended reporting date range for a cohort report. Granularity granularity = 1; - // For daily cohorts, this will be the start day offset. - // For weekly cohorts, this will be the week offset. + // `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. + // + // If `granularity` is `DAILY`, the `startDate` of the extended reporting date + // range is `startDate` of the cohort plus `startOffset` days. + // + // If `granularity` is `WEEKLY`, the `startDate` of the extended reporting + // date range is `startDate` of the cohort plus `startOffset * 7` days. + // + // If `granularity` is `MONTHLY`, the `startDate` of the extended reporting + // date range is `startDate` of the cohort plus `startOffset * 30` days. int32 start_offset = 2; - // For daily cohorts, this will be the end day offset. - // For weekly cohorts, this will be the week offset. + // `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. + // + // If `granularity` is `DAILY`, the `endDate` of the extended reporting date + // range is `endDate` of the cohort plus `endOffset` days. + // + // If `granularity` is `WEEKLY`, the `endDate` of the extended reporting date + // range is `endDate` of the cohort plus `endOffset * 7` days. + // + // If `granularity` is `MONTHLY`, the `endDate` of the extended reporting date + // range is `endDate` of the cohort plus `endOffset * 30` days. int32 end_offset = 3; } +// Optional settings of a cohort report. +message CohortReportSettings { + // If true, accumulates the result from first touch day to the end day. Not + // supported in `RunReportRequest`. + bool accumulate = 1; +} + // Response's metadata carrying additional information about the report content. message ResponseMetaData { // If true, indicates some buckets of dimension combinations are rolled into @@ -650,6 +696,9 @@ message DimensionMetadata { // for a period of time. After the deprecation period, the dimension will be // available only by `apiName`. repeated string deprecated_api_names = 4; + + // True if the dimension is a custom dimension for this property. + bool custom_definition = 5; } // Explains a metric. @@ -678,6 +727,9 @@ message MetricMetadata { // [Metric](#Metric)'s `expression` field for equivalent reports. Most metrics // are not expressions, and for non-expressions, this field is empty. string expression = 6; + + // True if the metric is a custom metric for this property. + bool custom_definition = 7; } // Represents aggregation of metrics.