Skip to content

Commit

Permalink
feat: custom_definition field added to DimensionMetadata object, indi…
Browse files Browse the repository at this point in the history 
…cating whether a dimension is a custom dimension for a property

feat: custom_definition field added to MetricMetadata object, indicating whether a metric is a custom metric for a property
docs: documentation urls updated
docs: documentation for Cohort reporting feature is updated

PiperOrigin-RevId: 345553480
  • Loading branch information
@copybara-github
Google APIs authored and copybara-github committed Dec 3, 2020
1 parent a6cbc5f commit e67686c
Show file tree
Hide file tree
Showing 2 changed files with 97 additions and 45 deletions.
10 changes: 5 additions & 5 deletions google/analytics/data/v1alpha/analytics_data_api.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
//
Expand All @@ -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;
Expand Down
132 changes: 92 additions & 40 deletions google/analytics/data/v1alpha/data.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
//
// In a cohort request, this `dateRange` is required and the `dateRanges` in
// the `RunReportRequest` or `RunPivotReportRequest` must be unspecified.
//
// 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.
// 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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit e67686c

Please sign in to comment.