// Copyright 2023 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";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/timestamp.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";
option (google.api.resource_definition) = {
  type: "analyticsadmin.googleapis.com/Property"
  pattern: "properties/{property}"
};

// 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,"
      "https://www.googleapis.com/auth/drive,"
      "https://www.googleapis.com/auth/drive.file,"
      "https://www.googleapis.com/auth/spreadsheets";

  // 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).
  //
  // This method is introduced at alpha stability with the intention of
  // gathering feedback on syntax and capabilities before entering beta. To give
  // your feedback on this API, complete the [Google Analytics Data API Funnel
  // Reporting
  // Feedback](https://docs.google.com/forms/d/e/1FAIpQLSdwOlQDJAUoBiIgUZZ3S_Lwi8gr7Bb0k1jhvc-DEg7Rol3UjA/viewform).
  rpc RunFunnelReport(RunFunnelReportRequest)
      returns (RunFunnelReportResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{property=properties/*}:runFunnelReport"
      body: "*"
    };
  }

  // Creates an audience list for later retrieval. This method quickly returns
  // the audience list's resource name and initiates a long running asynchronous
  // request to form an audience list. To list the users in an audience list,
  // first create the audience list through this method and then send the
  // audience resource name to the `QueryAudienceList` method.
  //
  // See [Creating an Audience
  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
  // for an introduction to Audience Lists with examples.
  //
  // An audience list is a snapshot of the users currently in the audience at
  // the time of audience list creation. Creating audience lists for one
  // audience on different days will return different results as users enter and
  // exit the audience.
  //
  // Audiences in Google Analytics 4 allow you to segment your users in the ways
  // that are important to your business. To learn more, see
  // https://support.google.com/analytics/answer/9267572. Audience lists contain
  // the users in each audience.
  //
  // This method is introduced at alpha stability with the intention of
  // gathering feedback on syntax and capabilities before entering beta. To give
  // your feedback on this API, complete the
  // [Google Analytics Audience Export API
  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
  rpc CreateAudienceList(CreateAudienceListRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=properties/*}/audienceLists"
      body: "audience_list"
    };
    option (google.api.method_signature) = "parent,audience_list";
    option (google.longrunning.operation_info) = {
      response_type: "AudienceList"
      metadata_type: "AudienceListMetadata"
    };
  }

  // Retrieves an audience list of users. After creating an audience, the users
  // are not immediately available for listing. First, a request to
  // `CreateAudienceList` is necessary to create an audience list of users, and
  // then second, this method is used to retrieve the users in the audience
  // list.
  //
  // See [Creating an Audience
  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
  // for an introduction to Audience Lists with examples.
  //
  // Audiences in Google Analytics 4 allow you to segment your users in the ways
  // that are important to your business. To learn more, see
  // https://support.google.com/analytics/answer/9267572.
  //
  // This method is introduced at alpha stability with the intention of
  // gathering feedback on syntax and capabilities before entering beta. To give
  // your feedback on this API, complete the
  // [Google Analytics Audience Export API
  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
  rpc QueryAudienceList(QueryAudienceListRequest)
      returns (QueryAudienceListResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=properties/*/audienceLists/*}:query"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }

  // Exports an audience list of users to a Google Sheet. After creating an
  // audience, the users are not immediately available for listing. First, a
  // request to `CreateAudienceList` is necessary to create an audience list of
  // users, and then second, this method is used to export those users in the
  // audience list to a Google Sheet.
  //
  // See [Creating an Audience
  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
  // for an introduction to Audience Lists with examples.
  //
  // Audiences in Google Analytics 4 allow you to segment your users in the ways
  // that are important to your business. To learn more, see
  // https://support.google.com/analytics/answer/9267572.
  //
  // This method is introduced at alpha stability with the intention of
  // gathering feedback on syntax and capabilities before entering beta. To give
  // your feedback on this API, complete the
  // [Google Analytics Audience Export API
  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
  rpc SheetExportAudienceList(SheetExportAudienceListRequest)
      returns (SheetExportAudienceListResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=properties/*/audienceLists/*}:exportSheet"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }

  // Gets configuration metadata about a specific audience list. This method
  // can be used to understand an audience list after it has been created.
  //
  // See [Creating an Audience
  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
  // for an introduction to Audience Lists with examples.
  //
  // This method is introduced at alpha stability with the intention of
  // gathering feedback on syntax and capabilities before entering beta. To give
  // your feedback on this API, complete the
  // [Google Analytics Audience Export API
  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
  rpc GetAudienceList(GetAudienceListRequest) returns (AudienceList) {
    option (google.api.http) = {
      get: "/v1alpha/{name=properties/*/audienceLists/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists all audience lists for a property. This method can be used for you to
  // find and reuse existing audience lists rather than creating unnecessary new
  // audience lists. The same audience can have multiple audience lists that
  // represent the list of users that were in an audience on different days.
  //
  // See [Creating an Audience
  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
  // for an introduction to Audience Lists with examples.
  //
  // This method is introduced at alpha stability with the intention of
  // gathering feedback on syntax and capabilities before entering beta. To give
  // your feedback on this API, complete the
  // [Google Analytics Audience Export API
  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
  rpc ListAudienceLists(ListAudienceListsRequest)
      returns (ListAudienceListsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/{parent=properties/*}/audienceLists"
    };
    option (google.api.method_signature) = "parent";
  }
}

// A request to retrieve configuration metadata about a specific audience list.
message GetAudienceListRequest {
  // Required. The audience list resource name.
  // Format: `properties/{property}/audienceLists/{audience_list}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "analyticsdata.googleapis.com/AudienceList"
    }
  ];
}

// A request to list all audience lists for a property.
message ListAudienceListsRequest {
  // Required. All audience lists for this property will be listed in the
  // response. Format: `properties/{property}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "analyticsdata.googleapis.com/AudienceList"
    }
  ];

  // Optional. The maximum number of audience lists to return. The service may
  // return fewer than this value. If unspecified, at most 200 audience lists
  // will be returned. The maximum value is 1000 (higher values will be coerced
  // to the maximum).
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListAudienceLists` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListAudienceLists` must
  // match the call that provided the page token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// A list of all audience lists for a property.
message ListAudienceListsResponse {
  // Each audience list for a property.
  repeated AudienceList audience_lists = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  optional string next_page_token = 2;
}

// A request to create a new audience list.
message CreateAudienceListRequest {
  // Required. The parent resource where this audience list will be created.
  // Format: `properties/{property}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "analyticsdata.googleapis.com/AudienceList"
    }
  ];

  // Required. The audience list to create.
  AudienceList audience_list = 2 [(google.api.field_behavior) = REQUIRED];
}

// An audience list is a list of users in an audience at the time of the list's
// creation. One audience may have multiple audience lists created for different
// days.
message AudienceList {
  option (google.api.resource) = {
    type: "analyticsdata.googleapis.com/AudienceList"
    pattern: "properties/{property}/audienceLists/{audience_list}"
    plural: "audienceLists"
    singular: "audienceList"
  };

  // The AudienceList currently exists in this state.
  enum State {
    // Unspecified state will never be used.
    STATE_UNSPECIFIED = 0;

    // The AudienceList is currently creating and will be available in the
    // future. Creating occurs immediately after the CreateAudienceList call.
    CREATING = 1;

    // The AudienceList is fully created and ready for querying. An AudienceList
    // is updated to active asynchronously from a request; this occurs some
    // time (for example 15 minutes) after the initial create call.
    ACTIVE = 2;

    // The AudienceList failed to be created. It is possible that re-requesting
    // this audience list will succeed.
    FAILED = 3;
  }

  // Output only. Identifier. The audience list resource name assigned during
  // creation. This resource name identifies this `AudienceList`.
  //
  // Format: `properties/{property}/audienceLists/{audience_list}`
  string name = 1 [
    (google.api.field_behavior) = IDENTIFIER,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Required. The audience resource name. This resource name identifies the
  // audience being listed and is shared between the Analytics Data & Admin
  // APIs.
  //
  // Format: `properties/{property}/audiences/{audience}`
  string audience = 2 [(google.api.field_behavior) = REQUIRED];

  // Output only. The descriptive display name for this audience. For example,
  // "Purchasers".
  string audience_display_name = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The dimensions requested and displayed in the report response.
  repeated AudienceDimension dimensions = 4
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The current state for this AudienceList.
  optional State state = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when CreateAudienceList was called and the
  // AudienceList began the `CREATING` state.
  optional google.protobuf.Timestamp begin_creating_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The total quota tokens charged during creation of the
  // AudienceList. Because this token count is based on activity from the
  // `CREATING` state, this tokens charged will be fixed once an AudienceList
  // enters the `ACTIVE` or `FAILED` states.
  int32 creation_quota_tokens_charged = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The total number of rows in the AudienceList result.
  optional int32 row_count = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Error message is populated when an audience list fails during
  // creation. A common reason for such a failure is quota exhaustion.
  optional string error_message = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// This metadata is currently blank.
message AudienceListMetadata {}

// A request to list users in an audience list.
message QueryAudienceListRequest {
  // Required. The name of the audience list to retrieve users from.
  // Format: `properties/{property}/audienceLists/{audience_list}`
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The row count of the start row. The first row is counted as row
  // 0.
  //
  // When paging, the first request does not specify offset; or equivalently,
  // sets offset to 0; the first request returns the first `limit` of rows. The
  // second request sets offset to the `limit` of the first request; the second
  // request returns the second `limit` of rows.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 offset = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The number of rows to return. If unspecified, 10,000 rows are
  // returned. The API returns a maximum of 250,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`.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 limit = 3 [(google.api.field_behavior) = OPTIONAL];
}

// A list of users in an audience list.
message QueryAudienceListResponse {
  // Configuration data about AudienceList being queried. Returned to help
  // interpret the audience rows in this response. For example, the dimensions
  // in this AudienceList correspond to the columns in the AudienceRows.
  optional AudienceList audience_list = 1;

  // Rows for each user in an audience list. The number of rows in this
  // response will be less than or equal to request's page size.
  repeated AudienceRow audience_rows = 2;

  // The total number of rows in the AudienceList result. `rowCount` is
  // independent of the number of rows returned in the response, the `limit`
  // request parameter, and the `offset` request parameter. For example if a
  // query returns 175 rows and includes `limit` of 50 in the API request, the
  // response will contain `rowCount` of 175 but only 50 rows.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  optional int32 row_count = 3;
}

// A request to export users in an audience list to a Google Sheet.
message SheetExportAudienceListRequest {
  // Required. The name of the audience list to retrieve users from.
  // Format: `properties/{property}/audienceLists/{audience_list}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "analyticsdata.googleapis.com/AudienceList"
    }
  ];

  // Optional. The row count of the start row. The first row is counted as row
  // 0.
  //
  // When paging, the first request does not specify offset; or equivalently,
  // sets offset to 0; the first request returns the first `limit` of rows. The
  // second request sets offset to the `limit` of the first request; the second
  // request returns the second `limit` of rows.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 offset = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The number of rows to return. If unspecified, 10,000 rows are
  // returned. The API returns a maximum of 250,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`.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 limit = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The created Google Sheet with the list of users in an audience list.
message SheetExportAudienceListResponse {
  // A uri for you to visit in your browser to view the Google Sheet.
  optional string spreadsheet_uri = 1;

  // An ID that identifies the created Google Sheet resource.
  optional string spreadsheet_id = 2;

  // The total number of rows in the AudienceList result. `rowCount` is
  // independent of the number of rows returned in the response, the `limit`
  // request parameter, and the `offset` request parameter. For example if a
  // query returns 175 rows and includes `limit` of 50 in the API request, the
  // response will contain `rowCount` of 175 but only 50 rows.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  optional int32 row_count = 3;

  // Configuration data about AudienceList being exported. Returned to help
  // interpret the AudienceList in the Google Sheet of this response.
  //
  // For example, the AudienceList may have more rows than are present in the
  // Google Sheet, and in that case, you may want to send an additional sheet
  // export request with a different `offset` value to retrieve the next page of
  // rows in an additional Google Sheet.
  optional AudienceList audience_list = 4;
}

// Dimension value attributes for the audience user row.
message AudienceRow {
  // Each dimension value attribute for an audience user. One dimension value
  // will be added for each dimension column requested.
  repeated AudienceDimensionValue dimension_values = 1;
}

// An audience dimension is a user attribute. Specific user attributed are
// requested and then later returned in the `QueryAudienceListResponse`.
message AudienceDimension {
  // Optional. The API name of the dimension. See the [API
  // Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-api-schema#dimensions)
  // for the list of dimension names.
  string dimension_name = 1 [(google.api.field_behavior) = OPTIONAL];
}

// The value of a dimension.
message AudienceDimensionValue {
  // One kind of dimension value.
  oneof one_value {
    // Value as a string if the dimension type is a string.
    string value = 1;
  }
}

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

  // Optional. 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 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The configuration of this request's funnel. This funnel
  // configuration is required.
  Funnel funnel = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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
  // (for example `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
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The number of rows to return. If unspecified, 10,000 rows are
  // returned. The API returns a maximum of 250,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 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Toggles whether to return the current state of this Analytics
  // Property's quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  bool return_property_quota = 12 [(google.api.field_behavior) = OPTIONAL];
}

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