@google-analytics/data 2.7.0 → 3.0.2

package/build/protos/google/analytics/data/v1alpha/analytics_data_api.proto

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -19,8 +19,6 @@ package google.analytics.data.v1alpha;
 import "google/analytics/data/v1alpha/data.proto";
 import "google/api/annotations.proto";
 import "google/api/client.proto";
-import "google/api/field_behavior.proto";
-import "google/api/resource.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/analytics/data/v1alpha;data";
 option java_multiple_files = true;
@@ -34,444 +32,138 @@ service AlphaAnalyticsData {
       "https://www.googleapis.com/auth/analytics,"
       "https://www.googleapis.com/auth/analytics.readonly";
 
-  // Returns a customized report of your Google Analytics event data. Reports
-  // contain statistics derived from data collected by the Google Analytics
-  // tracking code. The data returned from the API is as a table with columns
-  // for the requested dimensions and metrics. Metrics are individual
-  // measurements of user activity on your property, such as active users or
-  // event count. Dimensions break down metrics across some common criteria,
-  // such as country or event name.
-  rpc RunReport(RunReportRequest) returns (RunReportResponse) {
-    option (google.api.http) = {
-      post: "/v1alpha:runReport"
-      body: "*"
-    };
-  }
-
-  // Returns a customized pivot report of your Google Analytics event data.
-  // Pivot reports are more advanced and expressive formats than regular
-  // reports. In a pivot report, dimensions are only visible if they are
-  // included in a pivot. Multiple pivots can be specified to further dissect
-  // your data.
-  rpc RunPivotReport(RunPivotReportRequest) returns (RunPivotReportResponse) {
-    option (google.api.http) = {
-      post: "/v1alpha:runPivotReport"
-      body: "*"
-    };
-  }
-
-  // Returns multiple reports in a batch. All reports must be for the same
-  // Entity.
-  rpc BatchRunReports(BatchRunReportsRequest) returns (BatchRunReportsResponse) {
-    option (google.api.http) = {
-      post: "/v1alpha:batchRunReports"
-      body: "*"
-    };
-  }
-
-  // Returns multiple pivot reports in a batch. All reports must be for the same
-  // Entity.
-  rpc BatchRunPivotReports(BatchRunPivotReportsRequest) returns (BatchRunPivotReportsResponse) {
-    option (google.api.http) = {
-      post: "/v1alpha:batchRunPivotReports"
-      body: "*"
-    };
-  }
-
-  // Returns metadata for dimensions and metrics available in reporting methods.
-  // Used to explore the dimensions and metrics. In this method, a Google
-  // Analytics GA4 Property Identifier is specified in the request, and
-  // the metadata response includes Custom dimensions and metrics as well as
-  // Universal metadata.
+  // Returns a customized funnel report of your Google Analytics event data. The
+  // data returned from the API is as a table with columns for the requested
+  // dimensions and metrics.
   //
-  // For example if a custom metric with parameter name `levels_unlocked` is
-  // registered to a property, the Metadata response will contain
-  // `customEvent:levels_unlocked`. Universal metadata are dimensions and
-  // metrics applicable to any property such as `country` and `totalUsers`.
-  rpc GetMetadata(GetMetadataRequest) returns (Metadata) {
+  // Funnel exploration lets you visualize the steps your users take to complete
+  // a task and quickly see how well they are succeeding or failing at each
+  // step. For example, how do prospects become shoppers and then become buyers?
+  // How do one time buyers become repeat buyers? With this information, you can
+  // improve inefficient or abandoned customer journeys. To learn more, see [GA4
+  // Funnel Explorations](https://support.google.com/analytics/answer/9327974).
+  rpc RunFunnelReport(RunFunnelReportRequest) returns (RunFunnelReportResponse) {
     option (google.api.http) = {
-      get: "/v1alpha/{name=properties/*/metadata}"
-    };
-    option (google.api.method_signature) = "name";
-  }
-
-  // The Google Analytics Realtime API returns a customized report of realtime
-  // event data for your property. These reports show events and usage from the
-  // last 30 minutes.
-  rpc RunRealtimeReport(RunRealtimeReportRequest) returns (RunRealtimeReportResponse) {
-    option (google.api.http) = {
-      post: "/v1alpha/{property=properties/*}:runRealtimeReport"
+      post: "/v1alpha/{property=properties/*}:runFunnelReport"
       body: "*"
     };
   }
 }
 
-// The dimensions and metrics currently accepted in reporting methods.
-message Metadata {
-  option (google.api.resource) = {
-    type: "analyticsdata.googleapis.com/Metadata"
-    pattern: "properties/{property}/metadata"
-  };
-
-  // Resource name of this metadata.
-  string name = 3;
-
-  // The dimension descriptions.
-  repeated DimensionMetadata dimensions = 1;
-
-  // The metric descriptions.
-  repeated MetricMetadata metrics = 2;
-}
-
-// The request to generate a report.
-message RunReportRequest {
-  // A property whose events are tracked. Within a batch request, this entity
-  // should either be unspecified or consistent with the batch-level entity.
-  Entity entity = 1;
-
-  // The dimensions requested and displayed.
-  repeated Dimension dimensions = 2;
+// The request for a funnel report.
+message RunFunnelReportRequest {
+  // Controls the dimensions present in the funnel visualization sub report
+  // response.
+  enum FunnelVisualizationType {
+    // Unspecified type.
+    FUNNEL_VISUALIZATION_TYPE_UNSPECIFIED = 0;
+
+    // A standard (stepped) funnel. The funnel visualization sub report in the
+    // response will not contain date.
+    STANDARD_FUNNEL = 1;
+
+    // A trended (line chart) funnel. The funnel visualization sub report in the
+    // response will contain the date dimension.
+    TRENDED_FUNNEL = 2;
+  }
 
-  // The metrics requested and displayed.
-  repeated Metric metrics = 3;
+  // 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/devguides/reporting/data/v1/property-id).
+  // Within a batch request, this property should either be unspecified or
+  // consistent with the batch-level property.
+  //
+  // Example: properties/1234
+  string property = 1;
 
   // Date ranges of data to read. If multiple date ranges are requested, each
   // response row will contain a zero based date range index. If two date
   // ranges overlap, the event data for the overlapping days is included in the
-  // response rows for both date ranges. In a cohort request, this `dateRanges`
-  // must be unspecified.
-  repeated DateRange date_ranges = 4;
-
-  // The row count of the start row. The first row is counted as row 0.
-  //
-  // To learn more about this pagination parameter, see
-  // [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.
+  // response rows for both date ranges.
+  repeated DateRange date_ranges = 2;
+
+  // The configuration of this request's funnel. This funnel configuration is
+  // required.
+  Funnel funnel = 3;
+
+  // If specified, this breakdown adds a dimension to the funnel table sub
+  // report response. This breakdown dimension expands each funnel step to the
+  // unique values of the breakdown dimension. For example, a breakdown by the
+  // `deviceCategory` dimension will create rows for `mobile`, `tablet`,
+  // `desktop`, and the total.
+  FunnelBreakdown funnel_breakdown = 4;
+
+  // If specified, next action adds a dimension to the funnel visualization sub
+  // report response. This next action dimension expands each funnel step to the
+  // unique values of the next action. For example a next action of the
+  // `eventName` dimension will create rows for several events (i.e.
+  // `session_start` & `click`) and the total.
   //
-  // To learn more about this pagination parameter, see
-  // [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
-  // where the dimension_values are set to "RESERVED_(MetricAggregation)".
-  repeated MetricAggregation metric_aggregations = 7;
-
-  // The filter clause of dimensions. Dimensions must be requested to be used in
-  // this filter. Metrics cannot be used in this filter.
-  FilterExpression dimension_filter = 8;
-
-  // The filter clause of metrics. Applied at post aggregation phase, similar to
-  // SQL having-clause. Metrics must be requested to be used in this filter.
-  // Dimensions cannot be used in this filter.
-  FilterExpression metric_filter = 9;
-
-  // Specifies how rows are ordered in the response.
-  repeated OrderBy order_bys = 10;
+  // Next action only supports `eventName` and most Page / Screen dimensions
+  // like `pageTitle` and `pagePath`.
+  FunnelNextAction funnel_next_action = 5;
 
-  // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
-  // If the field is empty, the report uses the entity's default currency.
-  string currency_code = 11;
+  // The funnel visualization type controls the dimensions present in the funnel
+  // visualization sub report response. If not specified, `STANDARD_FUNNEL` is
+  // used.
+  FunnelVisualizationType funnel_visualization_type = 6;
 
-  // Cohort group associated with this request. If there is a cohort group
-  // in the request the 'cohort' dimension must be present.
-  CohortSpec cohort_spec = 12;
-
-  // If false or unspecified, each row with all metrics equal to 0 will not be
-  // returned. If true, these rows will be returned if they are not separately
-  // removed by a filter.
-  bool keep_empty_rows = 13;
-
-  // Toggles whether to return the current state of this Analytics Property's
-  // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
-  bool return_property_quota = 14;
-}
-
-// The response report table corresponding to a request.
-message RunReportResponse {
-  // Describes dimension columns. The number of DimensionHeaders and ordering of
-  // DimensionHeaders matches the dimensions present in rows.
-  repeated DimensionHeader dimension_headers = 11;
-
-  // Describes metric columns. The number of MetricHeaders and ordering of
-  // MetricHeaders matches the metrics present in rows.
-  repeated MetricHeader metric_headers = 1;
-
-  // Rows of dimension value combinations and metric values in the report.
-  repeated Row rows = 2;
-
-  // If requested, the totaled values of metrics.
-  repeated Row totals = 8;
-
-  // If requested, the maximum values of metrics.
-  repeated Row maximums = 9;
-
-  // If requested, the minimum values of metrics.
-  repeated Row minimums = 10;
-
-  // The total number of rows in the query result, regardless of the number of
-  // rows returned in the response. For example if a query returns 175 rows and
-  // includes limit = 50 in the API request, the response will contain row_count
-  // = 175 but only 50 rows.
+  // The configurations of segments. Segments are subsets of a property's data.
+  // In a funnel report with segments, the funnel is evaluated in each segment.
   //
-  // To learn more about this pagination parameter, see
-  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
-  int32 row_count = 12;
-
-  // Metadata for the report.
-  ResponseMetaData metadata = 6;
-
-  // This Analytics Property's quota state including this request.
-  PropertyQuota property_quota = 7;
-}
-
-// The request to generate a pivot report.
-message RunPivotReportRequest {
-  // A property whose events are tracked. Within a batch request, this entity
-  // should either be unspecified or consistent with the batch-level entity.
-  Entity entity = 1;
-
-  // The dimensions requested. All defined dimensions must be used by one of the
-  // following: dimension_expression, dimension_filter, pivots, order_bys.
-  repeated Dimension dimensions = 2;
-
-  // The metrics requested, at least one metric needs to be specified. All
-  // defined metrics must be used by one of the following: metric_expression,
-  // metric_filter, order_bys.
-  repeated Metric metrics = 3;
-
-  // The filter clause of dimensions. Dimensions must be requested to be used in
-  // this filter. Metrics cannot be used in this filter.
-  FilterExpression dimension_filter = 4;
-
-  // The filter clause of metrics. Applied at post aggregation phase, similar to
-  // SQL having-clause. Metrics must be requested to be used in this filter.
-  // Dimensions cannot be used in this filter.
-  FilterExpression metric_filter = 5;
-
-  // Describes the visual format of the report's dimensions in columns or rows.
-  // The union of the fieldNames (dimension names) in all pivots must be a
-  // subset of dimension names defined in Dimensions. No two pivots can share a
-  // dimension. A dimension is only visible if it appears in a pivot.
-  repeated Pivot pivots = 6;
-
-  // The date range to retrieve event data for the report. If multiple date
-  // ranges are specified, event data from each date range is used in the
-  // report. A special dimension with field name "dateRange" can be included in
-  // a Pivot's field names; if included, the report compares between date
-  // ranges. In a cohort request, this `dateRanges` must be unspecified.
-  repeated DateRange date_ranges = 7;
-
-  // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
-  // If the field is empty, the report uses the entity's default currency.
-  string currency_code = 8;
+  // Each segment specified in this request
+  // produces a separate row in the response; in the response, each segment
+  // identified by its name.
+  //
+  // The segments parameter is optional. Requests are limited to 4 segments.
+  repeated Segment segments = 7;
 
-  // Cohort group associated with this request. If there is a cohort group
-  // in the request the 'cohort' dimension must be present.
-  CohortSpec cohort_spec = 9;
+  // The number of rows to return. If unspecified, 10,000 rows are returned. The
+  // API returns a maximum of 100,000 rows per request, no matter how many you
+  // ask for. `limit` must be positive.
+  //
+  // The API can also return fewer rows than the requested `limit`, if there
+  // aren't as many dimension values as the `limit`.
+  int64 limit = 9;
 
-  // If false or unspecified, each row with all metrics equal to 0 will not be
-  // returned. If true, these rows will be returned if they are not separately
-  // removed by a filter.
-  bool keep_empty_rows = 10;
+  // Dimension filters allow you to ask for only specific dimension values in
+  // the report. To learn more, see [Creating a Report: Dimension
+  // Filters](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#dimension_filters)
+  // for examples. Metrics cannot be used in this filter.
+  FilterExpression dimension_filter = 10;
 
   // Toggles whether to return the current state of this Analytics Property's
   // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
-  bool return_property_quota = 11;
-}
-
-// The response pivot report table corresponding to a pivot request.
-message RunPivotReportResponse {
-  // Summarizes the columns and rows created by a pivot. Each pivot in the
-  // request produces one header in the response. If we have a request like
-  // this:
-  //
-  //     "pivots": [{
-  //       "fieldNames": ["country",
-  //         "city"]
-  //     },
-  //     {
-  //       "fieldNames": "eventName"
-  //     }]
-  //
-  // We will have the following `pivotHeaders` in the response:
-  //
-  //     "pivotHeaders" : [{
-  //       "dimensionHeaders": [{
-  //         "dimensionValues": [
-  //            { "value": "United Kingdom" },
-  //            { "value": "London" }
-  //          ]
-  //       },
-  //       {
-  //         "dimensionValues": [
-  //         { "value": "Japan" },
-  //         { "value": "Osaka" }
-  //         ]
-  //       }]
-  //     },
-  //     {
-  //       "dimensionHeaders": [{
-  //         "dimensionValues": [{ "value": "session_start" }]
-  //       },
-  //       {
-  //         "dimensionValues": [{ "value": "scroll" }]
-  //       }]
-  //     }]
-  repeated PivotHeader pivot_headers = 1;
-
-  // Describes dimension columns. The number of DimensionHeaders and ordering of
-  // DimensionHeaders matches the dimensions present in rows.
-  repeated DimensionHeader dimension_headers = 7;
-
-  // Describes metric columns. The number of MetricHeaders and ordering of
-  // MetricHeaders matches the metrics present in rows.
-  repeated MetricHeader metric_headers = 2;
-
-  // Rows of dimension value combinations and metric values in the report.
-  repeated Row rows = 3;
-
-  // Aggregation of metric values. Can be totals, minimums, or maximums. The
-  // returned aggregations are controlled by the metric_aggregations in the
-  // pivot. The type of aggregation returned in each row is shown by the
-  // dimension_values which are set to "RESERVED_<MetricAggregation>".
-  repeated Row aggregates = 4;
-
-  // Metadata for the report.
-  ResponseMetaData metadata = 5;
-
-  // This Analytics Property's quota state including this request.
-  PropertyQuota property_quota = 6;
-}
-
-// The batch request containing multiple report requests.
-message BatchRunReportsRequest {
-  // A property whose events are tracked. This entity must be specified for the
-  // batch. The entity within RunReportRequest may either be unspecified or
-  // consistent with this entity.
-  Entity entity = 1;
-
-  // Individual requests. Each request has a separate report response. Each
-  // batch request is allowed up to 5 requests.
-  repeated RunReportRequest requests = 2;
-}
-
-// The batch response containing multiple reports.
-message BatchRunReportsResponse {
-  // Individual responses. Each response has a separate report request.
-  repeated RunReportResponse reports = 1;
-}
-
-// The batch request containing multiple pivot report requests.
-message BatchRunPivotReportsRequest {
-  // A property whose events are tracked. This entity must be specified for the
-  // batch. The entity within RunPivotReportRequest may either be unspecified or
-  // consistent with this entity.
-  Entity entity = 1;
-
-  // Individual requests. Each request has a separate pivot report response.
-  // Each batch request is allowed up to 5 requests.
-  repeated RunPivotReportRequest requests = 2;
-}
-
-// The batch response containing multiple pivot reports.
-message BatchRunPivotReportsResponse {
-  // Individual responses. Each response has a separate pivot report request.
-  repeated RunPivotReportResponse pivot_reports = 1;
+  bool return_property_quota = 12;
 }
 
-// Request for a property's dimension and metric metadata.
-message GetMetadataRequest {
-  // Required. The resource name of the metadata to retrieve. This name field is
-  // 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/devguides/reporting/data/v1/property-id).
+// The funnel report response contains two sub reports. The two sub reports are
+// different combinations of dimensions and metrics.
+message RunFunnelReportResponse {
+  // The funnel table is a report with the funnel step, segment, breakdown
+  // dimension, active users, completion rate, abandonments, and abandonments
+  // rate.
   //
-  // Example: properties/1234/metadata
-  //
-  // Set the Property ID to 0 for dimensions and metrics common to all
-  // properties. In this special mode, this method will not return custom
-  // dimensions and metrics.
-  string name = 1 [
-    (google.api.field_behavior) = REQUIRED,
-    (google.api.resource_reference) = {
-      type: "analyticsdata.googleapis.com/Metadata"
-    }
-  ];
-}
+  // The segment dimension is only present in this response if a segment was
+  // requested. The breakdown dimension is only present in this response if it
+  // was requested.
+  FunnelSubReport funnel_table = 1;
 
-// The request to generate a realtime report.
-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/devguides/reporting/data/v1/property-id).
+  // The funnel visualization is a report with the funnel step, segment, date,
+  // next action dimension, and active users.
   //
-  // Example: properties/1234
-  string property = 1;
-
-  // The dimensions requested and displayed.
-  repeated Dimension dimensions = 2;
-
-  // The metrics requested and displayed.
-  repeated Metric metrics = 3;
+  // The segment dimension is only present in this response if a segment was
+  // requested. The date dimension is only present in this response if it was
+  // requested via the `TRENDED_FUNNEL` funnel type. The next action dimension
+  // is only present in the response if it was requested.
+  FunnelSubReport funnel_visualization = 2;
 
-  // The number of rows to return. If unspecified, 10 rows are returned. If
-  // -1, all rows are returned.
-  int64 limit = 4;
-
-  // The filter clause of dimensions. Dimensions must be requested to be used in
-  // this filter. Metrics cannot be used in this filter.
-  FilterExpression dimension_filter = 5;
-
-  // The filter clause of metrics. Applied at post aggregation phase, similar to
-  // SQL having-clause. Metrics must be requested to be used in this filter.
-  // Dimensions cannot be used in this filter.
-  FilterExpression metric_filter = 6;
-
-  // Aggregation of metrics. Aggregated metric values will be shown in rows
-  // where the dimension_values are set to "RESERVED_(MetricAggregation)".
-  repeated MetricAggregation metric_aggregations = 7;
-
-  // Specifies how rows are ordered in the response.
-  repeated OrderBy order_bys = 8;
-
-  // Toggles whether to return the current state of this Analytics Property's
-  // Realtime quota. Quota is returned in [PropertyQuota](#PropertyQuota).
-  bool return_property_quota = 9;
-}
-
-// The response realtime report table corresponding to a request.
-message RunRealtimeReportResponse {
-  // Describes dimension columns. The number of DimensionHeaders and ordering of
-  // DimensionHeaders matches the dimensions present in rows.
-  repeated DimensionHeader dimension_headers = 1;
-
-  // Describes metric columns. The number of MetricHeaders and ordering of
-  // MetricHeaders matches the metrics present in rows.
-  repeated MetricHeader metric_headers = 2;
-
-  // Rows of dimension value combinations and metric values in the report.
-  repeated Row rows = 3;
-
-  // If requested, the totaled values of metrics.
-  repeated Row totals = 4;
-
-  // If requested, the maximum values of metrics.
-  repeated Row maximums = 5;
-
-  // If requested, the minimum values of metrics.
-  repeated Row minimums = 6;
-
-  // The total number of rows in the query result, regardless of the number of
-  // rows returned in the response. For example if a query returns 175 rows and
-  // includes limit = 50 in the API request, the response will contain row_count
-  // = 175 but only 50 rows.
-  int32 row_count = 7;
+  // This Analytics Property's quota state including this request.
+  PropertyQuota property_quota = 3;
 
-  // This Analytics Property's Realtime quota state including this request.
-  PropertyQuota property_quota = 8;
+  // Identifies what kind of resource this message is. This `kind` is always the
+  // fixed string "analyticsData#runFunnelReport". Useful to distinguish between
+  // response types in JSON.
+  string kind = 4;
 }