// 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.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.analytics.data.v1alpha;

import "google/analytics/data/v1alpha/data.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";

option go_package = "google.golang.org/genproto/googleapis/analytics/data/v1alpha;data";
option java_multiple_files = true;
option java_outer_classname = "AnalyticsDataApiProto";
option java_package = "com.google.analytics.data.v1alpha";

// Google Analytics reporting data service.
service AlphaAnalyticsData {
  option (google.api.default_host) = "analyticsdata.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/analytics,"
      "https://www.googleapis.com/auth/analytics.readonly";

  // 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.
  //
  // 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) = {
      post: "/v1alpha/{property=properties/*}:runFunnelReport"
      body: "*"
    };
  }
}

// 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;
  }

  // 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.
  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.
  //
  // Next action only supports `eventName` and most Page / Screen dimensions
  // like `pageTitle` and `pagePath`.
  FunnelNextAction funnel_next_action = 5;

  // 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;

  // 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.
  //
  // 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;

  // 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;

  // 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 = 12;
}

// 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.
  //
  // 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 funnel visualization is a report with the funnel step, segment, date,
  // next action dimension, and active users.
  //
  // 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;

  // This Analytics Property's quota state including this request.
  PropertyQuota property_quota = 3;

  // 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;
}