google-analytics-data-v1alpha 0.4.0 → 0.8.0

data/lib/google/analytics/data/v1alpha.rb

@@ -33,3 +33,6 @@ module Google
     end
   end
 end
+
+helper_path = ::File.join __dir__, "v1alpha", "_helpers.rb"
+require "google/analytics/data/v1alpha/_helpers" if ::File.file? helper_path

data/lib/google/analytics/data/v1alpha/analytics_data/client.rb

@@ -60,7 +60,7 @@ module Google
                 parent_config = while namespace.any?
                                   parent_name = namespace.join "::"
                                   parent_const = const_get parent_name
-                                  break parent_const.configure if parent_const&.respond_to? :configure
+                                  break parent_const.configure if parent_const.respond_to? :configure
                                   namespace.pop
                                 end
                 default_config = Client::Configuration.new parent_config
@@ -68,9 +68,9 @@ module Google
                 default_config.timeout = 60.0
                 default_config.retry_policy = {
                   initial_delay: 1.0,
-                  max_delay:     60.0,
-                  multiplier:    1.3,
-                  retry_codes:   [2]
+                max_delay: 60.0,
+                multiplier: 1.3,
+                retry_codes: [2]
                 }
 
                 default_config.rpcs.run_report.timeout = 60.0
@@ -142,7 +142,13 @@ module Google
 
               # Create credentials
               credentials = @config.credentials
-              credentials ||= Credentials.default scope: @config.scope
+              # Use self-signed JWT if the scope and endpoint are unchanged from default,
+              # but only if the default endpoint does not have a region prefix.
+              enable_self_signed_jwt = @config.scope == Client.configure.scope &&
+                                       @config.endpoint == Client.configure.endpoint &&
+                                       !@config.endpoint.split(".").first.include?("-")
+              credentials ||= Credentials.default scope: @config.scope,
+                                                  enable_self_signed_jwt: enable_self_signed_jwt
               if credentials.is_a?(String) || credentials.is_a?(Hash)
                 credentials = Credentials.new credentials, scope: @config.scope
               end
@@ -199,9 +205,15 @@ module Google
             #     must be unspecified.
             #   @param offset [::Integer]
             #     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).
             #   @param limit [::Integer]
             #     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](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
             #   @param metric_aggregations [::Array<::Google::Analytics::Data::V1alpha::MetricAggregation>]
             #     Aggregation of metrics. Aggregated metric values will be shown in rows
             #     where the dimension_values are set to "RESERVED_(MetricAggregation)".
@@ -502,67 +514,10 @@ module Google
               raise ::Google::Cloud::Error.from_error(e)
             end
 
-            ##
-            # Returns metadata for dimensions and metrics available in reporting methods.
-            # Used to explore the dimensions and metrics. Dimensions and metrics will be
-            # mostly added over time, but renames and deletions may occur.
-            #
-            # This method returns Universal Metadata. Universal Metadata are dimensions
-            # and metrics applicable to any property such as `country` and `totalUsers`.
-            #
-            # @overload get_universal_metadata(request, options = nil)
-            #   Pass arguments to `get_universal_metadata` via a request object, either of type
-            #   {::Google::Analytics::Data::V1alpha::GetUniversalMetadataRequest} or an equivalent Hash.
-            #
-            #   @param request [::Google::Analytics::Data::V1alpha::GetUniversalMetadataRequest, ::Hash]
-            #     A request object representing the call parameters. Required. To specify no
-            #     parameters, or to keep all the default parameter values, pass an empty Hash.
-            #   @param options [::Gapic::CallOptions, ::Hash]
-            #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
-            #
-            # @yield [response, operation] Access the result along with the RPC operation
-            # @yieldparam response [::Google::Analytics::Data::V1alpha::UniversalMetadata]
-            # @yieldparam operation [::GRPC::ActiveCall::Operation]
-            #
-            # @return [::Google::Analytics::Data::V1alpha::UniversalMetadata]
-            #
-            # @raise [::Google::Cloud::Error] if the RPC is aborted.
-            #
-            def get_universal_metadata request, options = nil
-              raise ::ArgumentError, "request must be provided" if request.nil?
-
-              request = ::Gapic::Protobuf.coerce request, to: ::Google::Analytics::Data::V1alpha::GetUniversalMetadataRequest
-
-              # Converts hash and nil to an options object
-              options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
-
-              # Customize the options with defaults
-              metadata = @config.rpcs.get_universal_metadata.metadata.to_h
-
-              # Set x-goog-api-client and x-goog-user-project headers
-              metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
-                lib_name: @config.lib_name, lib_version: @config.lib_version,
-                gapic_version: ::Google::Analytics::Data::V1alpha::VERSION
-              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
-
-              options.apply_defaults timeout:      @config.rpcs.get_universal_metadata.timeout,
-                                     metadata:     metadata,
-                                     retry_policy: @config.rpcs.get_universal_metadata.retry_policy
-              options.apply_defaults metadata:     @config.metadata,
-                                     retry_policy: @config.retry_policy
-
-              @analytics_data_stub.call_rpc :get_universal_metadata, request, options: options do |response, operation|
-                yield response, operation if block_given?
-                return response
-              end
-            rescue ::GRPC::BadStatus => e
-              raise ::Google::Cloud::Error.from_error(e)
-            end
-
             ##
             # Returns metadata for dimensions and metrics available in reporting methods.
             # Used to explore the dimensions and metrics. In this method, a Google
-            # Analytics 4 (GA4) Property Identifier is specified in the request, and
+            # Analytics GA4 Property Identifier is specified in the request, and
             # the metadata response includes Custom dimensions and metrics as well as
             # Universal metadata.
             #
@@ -589,10 +544,16 @@ module Google
             #   @param name [::String]
             #     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 4 (GA4) Property identifier.
+            #     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).
             #
             #     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.
+            #
             # @yield [response, operation] Access the result along with the RPC operation
             # @yieldparam response [::Google::Analytics::Data::V1alpha::Metadata]
             # @yieldparam operation [::GRPC::ActiveCall::Operation]
@@ -662,7 +623,7 @@ module Google
             #     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
             #   @param dimensions [::Array<::Google::Analytics::Data::V1alpha::Dimension, ::Hash>]
@@ -825,7 +786,7 @@ module Google
               config_attr :scope,         nil, ::String, ::Array, nil
               config_attr :lib_name,      nil, ::String, nil
               config_attr :lib_version,   nil, ::String, nil
-              config_attr(:channel_args,  { "grpc.service_config_disable_resolution"=>1 }, ::Hash, nil)
+              config_attr(:channel_args,  { "grpc.service_config_disable_resolution" => 1 }, ::Hash, nil)
               config_attr :interceptors,  nil, ::Array, nil
               config_attr :timeout,       nil, ::Numeric, nil
               config_attr :metadata,      nil, ::Hash, nil
@@ -846,7 +807,7 @@ module Google
               def rpcs
                 @rpcs ||= begin
                   parent_rpcs = nil
-                  parent_rpcs = @parent_config.rpcs if defined?(@parent_config) && @parent_config&.respond_to?(:rpcs)
+                  parent_rpcs = @parent_config.rpcs if defined?(@parent_config) && @parent_config.respond_to?(:rpcs)
                   Rpcs.new parent_rpcs
                 end
               end
@@ -858,7 +819,7 @@ module Google
               # Each configuration object is of type `Gapic::Config::Method` and includes
               # the following configuration fields:
               #
-              #  *  `timeout` (*type:* `Numeric`) - The call timeout in milliseconds
+              #  *  `timeout` (*type:* `Numeric`) - The call timeout in seconds
               #  *  `metadata` (*type:* `Hash{Symbol=>String}`) - Additional gRPC headers
               #  *  `retry_policy (*type:* `Hash`) - The retry policy. The policy fields
               #     include the following keys:
@@ -890,11 +851,6 @@ module Google
                 #
                 attr_reader :batch_run_pivot_reports
                 ##
-                # RPC-specific configuration for `get_universal_metadata`
-                # @return [::Gapic::Config::Method]
-                #
-                attr_reader :get_universal_metadata
-                ##
                 # RPC-specific configuration for `get_metadata`
                 # @return [::Gapic::Config::Method]
                 #
@@ -907,19 +863,17 @@ module Google
 
                 # @private
                 def initialize parent_rpcs = nil
-                  run_report_config = parent_rpcs&.run_report if parent_rpcs&.respond_to? :run_report
+                  run_report_config = parent_rpcs.run_report if parent_rpcs.respond_to? :run_report
                   @run_report = ::Gapic::Config::Method.new run_report_config
-                  run_pivot_report_config = parent_rpcs&.run_pivot_report if parent_rpcs&.respond_to? :run_pivot_report
+                  run_pivot_report_config = parent_rpcs.run_pivot_report if parent_rpcs.respond_to? :run_pivot_report
                   @run_pivot_report = ::Gapic::Config::Method.new run_pivot_report_config
-                  batch_run_reports_config = parent_rpcs&.batch_run_reports if parent_rpcs&.respond_to? :batch_run_reports
+                  batch_run_reports_config = parent_rpcs.batch_run_reports if parent_rpcs.respond_to? :batch_run_reports
                   @batch_run_reports = ::Gapic::Config::Method.new batch_run_reports_config
-                  batch_run_pivot_reports_config = parent_rpcs&.batch_run_pivot_reports if parent_rpcs&.respond_to? :batch_run_pivot_reports
+                  batch_run_pivot_reports_config = parent_rpcs.batch_run_pivot_reports if parent_rpcs.respond_to? :batch_run_pivot_reports
                   @batch_run_pivot_reports = ::Gapic::Config::Method.new batch_run_pivot_reports_config
-                  get_universal_metadata_config = parent_rpcs&.get_universal_metadata if parent_rpcs&.respond_to? :get_universal_metadata
-                  @get_universal_metadata = ::Gapic::Config::Method.new get_universal_metadata_config
-                  get_metadata_config = parent_rpcs&.get_metadata if parent_rpcs&.respond_to? :get_metadata
+                  get_metadata_config = parent_rpcs.get_metadata if parent_rpcs.respond_to? :get_metadata
                   @get_metadata = ::Gapic::Config::Method.new get_metadata_config
-                  run_realtime_report_config = parent_rpcs&.run_realtime_report if parent_rpcs&.respond_to? :run_realtime_report
+                  run_realtime_report_config = parent_rpcs.run_realtime_report if parent_rpcs.respond_to? :run_realtime_report
                   @run_realtime_report = ::Gapic::Config::Method.new run_realtime_report_config
 
                   yield self if block_given?

data/lib/google/analytics/data/v1alpha/analytics_data_api_pb.rb

@@ -78,12 +78,6 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
     add_message "google.analytics.data.v1alpha.BatchRunPivotReportsResponse" do
       repeated :pivot_reports, :message, 1, "google.analytics.data.v1alpha.RunPivotReportResponse"
     end
-    add_message "google.analytics.data.v1alpha.GetUniversalMetadataRequest" do
-    end
-    add_message "google.analytics.data.v1alpha.UniversalMetadata" do
-      repeated :dimensions, :message, 1, "google.analytics.data.v1alpha.DimensionMetadata"
-      repeated :metrics, :message, 2, "google.analytics.data.v1alpha.MetricMetadata"
-    end
     add_message "google.analytics.data.v1alpha.GetMetadataRequest" do
       optional :name, :string, 1
     end
@@ -124,8 +118,6 @@ module Google
         BatchRunReportsResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.BatchRunReportsResponse").msgclass
         BatchRunPivotReportsRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.BatchRunPivotReportsRequest").msgclass
         BatchRunPivotReportsResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.BatchRunPivotReportsResponse").msgclass
-        GetUniversalMetadataRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.GetUniversalMetadataRequest").msgclass
-        UniversalMetadata = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.UniversalMetadata").msgclass
         GetMetadataRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.GetMetadataRequest").msgclass
         RunRealtimeReportRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.RunRealtimeReportRequest").msgclass
         RunRealtimeReportResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.RunRealtimeReportResponse").msgclass

data/lib/google/analytics/data/v1alpha/analytics_data_api_services_pb.rb

@@ -54,15 +54,8 @@ module Google
             # Entity.
             rpc :BatchRunPivotReports, ::Google::Analytics::Data::V1alpha::BatchRunPivotReportsRequest, ::Google::Analytics::Data::V1alpha::BatchRunPivotReportsResponse
             # Returns metadata for dimensions and metrics available in reporting methods.
-            # Used to explore the dimensions and metrics. Dimensions and metrics will be
-            # mostly added over time, but renames and deletions may occur.
-            #
-            # This method returns Universal Metadata. Universal Metadata are dimensions
-            # and metrics applicable to any property such as `country` and `totalUsers`.
-            rpc :GetUniversalMetadata, ::Google::Analytics::Data::V1alpha::GetUniversalMetadataRequest, ::Google::Analytics::Data::V1alpha::UniversalMetadata
-            # Returns metadata for dimensions and metrics available in reporting methods.
             # Used to explore the dimensions and metrics. In this method, a Google
-            # Analytics 4 (GA4) Property Identifier is specified in the request, and
+            # Analytics GA4 Property Identifier is specified in the request, and
             # the metadata response includes Custom dimensions and metrics as well as
             # Universal metadata.
             #

data/lib/google/analytics/data/v1alpha/data_pb.rb

@@ -137,9 +137,6 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
       optional :dimension, :string, 2
       optional :date_range, :message, 3, "google.analytics.data.v1alpha.DateRange"
     end
-    add_message "google.analytics.data.v1alpha.CohortReportSettings" do
-      optional :accumulate, :bool, 1
-    end
     add_message "google.analytics.data.v1alpha.CohortsRange" do
       optional :granularity, :enum, 1, "google.analytics.data.v1alpha.CohortsRange.Granularity"
       optional :start_offset, :int32, 2
@@ -151,6 +148,9 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
       value :WEEKLY, 2
       value :MONTHLY, 3
     end
+    add_message "google.analytics.data.v1alpha.CohortReportSettings" do
+      optional :accumulate, :bool, 1
+    end
     add_message "google.analytics.data.v1alpha.ResponseMetaData" do
       optional :data_loss_from_other_row, :bool, 3
     end
@@ -203,6 +203,7 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
       optional :ui_name, :string, 2
       optional :description, :string, 3
       repeated :deprecated_api_names, :string, 4
+      optional :custom_definition, :bool, 5
     end
     add_message "google.analytics.data.v1alpha.MetricMetadata" do
       optional :api_name, :string, 1
@@ -211,6 +212,7 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
       repeated :deprecated_api_names, :string, 4
       optional :type, :enum, 5, "google.analytics.data.v1alpha.MetricType"
       optional :expression, :string, 6
+      optional :custom_definition, :bool, 7
     end
     add_enum "google.analytics.data.v1alpha.MetricAggregation" do
       value :METRIC_AGGREGATION_UNSPECIFIED, 0
@@ -266,9 +268,9 @@ module Google
         Pivot = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.Pivot").msgclass
         CohortSpec = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.CohortSpec").msgclass
         Cohort = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.Cohort").msgclass
-        CohortReportSettings = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.CohortReportSettings").msgclass
         CohortsRange = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.CohortsRange").msgclass
         CohortsRange::Granularity = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.CohortsRange.Granularity").enummodule
+        CohortReportSettings = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.CohortReportSettings").msgclass
         ResponseMetaData = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.ResponseMetaData").msgclass
         DimensionHeader = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.DimensionHeader").msgclass
         MetricHeader = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.analytics.data.v1alpha.MetricHeader").msgclass

data/lib/google/analytics/data/v1alpha/version.rb

@@ -21,7 +21,7 @@ module Google
   module Analytics
     module Data
       module V1alpha
-        VERSION = "0.4.0"
+        VERSION = "0.8.0"
       end
     end
   end

data/proto_docs/google/analytics/data/v1alpha/analytics_data_api.rb

@@ -57,10 +57,16 @@ module Google
         # @!attribute [rw] offset
         #   @return [::Integer]
         #     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).
         # @!attribute [rw] limit
         #   @return [::Integer]
         #     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](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
         # @!attribute [rw] metric_aggregations
         #   @return [::Array<::Google::Analytics::Data::V1alpha::MetricAggregation>]
         #     Aggregation of metrics. Aggregated metric values will be shown in rows
@@ -126,6 +132,9 @@ module Google
         #     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.
+        #
+        #     To learn more about this pagination parameter, see
+        #     [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
         # @!attribute [rw] metadata
         #   @return [::Google::Analytics::Data::V1alpha::ResponseMetaData]
         #     Metadata for the report.
@@ -310,32 +319,20 @@ module Google
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
-        # Request for the universal dimension and metric metadata.
-        class GetUniversalMetadataRequest
-          include ::Google::Protobuf::MessageExts
-          extend ::Google::Protobuf::MessageExts::ClassMethods
-        end
-
-        # The dimensions and metrics currently accepted in reporting methods.
-        # @!attribute [rw] dimensions
-        #   @return [::Array<::Google::Analytics::Data::V1alpha::DimensionMetadata>]
-        #     The dimensions descriptions.
-        # @!attribute [rw] metrics
-        #   @return [::Array<::Google::Analytics::Data::V1alpha::MetricMetadata>]
-        #     The metric descriptions.
-        class UniversalMetadata
-          include ::Google::Protobuf::MessageExts
-          extend ::Google::Protobuf::MessageExts::ClassMethods
-        end
-
         # Request for a property's dimension and metric metadata.
         # @!attribute [rw] name
         #   @return [::String]
         #     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 4 (GA4) Property identifier.
+        #     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).
         #
         #     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.
         class GetMetadataRequest
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -347,7 +344,7 @@ module Google
         #     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
         # @!attribute [rw] dimensions

data/proto_docs/google/analytics/data/v1alpha/data.rb

@@ -22,8 +22,7 @@ module Google
     module Data
       module V1alpha
         # A contiguous set of days: startDate, startDate + 1, ..., endDate. Requests
-        # are allowed up to 4 date ranges, and the union of the ranges can cover up to
-        # 1 year.
+        # are allowed up to 4 date ranges.
         # @!attribute [rw] start_date
         #   @return [::String]
         #     The inclusive start date for the query in the format `YYYY-MM-DD`. Cannot
@@ -52,7 +51,7 @@ module Google
         #   @return [::String]
         #     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).
         class Entity
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -65,7 +64,7 @@ module Google
         # @!attribute [rw] name
         #   @return [::String]
         #     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
@@ -137,7 +136,7 @@ module Google
         # @!attribute [rw] name
         #   @return [::String]
         #     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.
@@ -448,23 +447,38 @@ module Google
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
-        # 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.
         # @!attribute [rw] cohorts
         #   @return [::Array<::Google::Analytics::Data::V1alpha::Cohort>]
-        #     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.
         # @!attribute [rw] cohorts_range
         #   @return [::Google::Analytics::Data::V1alpha::CohortsRange]
-        #     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.
         # @!attribute [rw] cohort_report_settings
         #   @return [::Google::Analytics::Data::V1alpha::CohortReportSettings]
-        #     Settings of a cohort report.
+        #     Optional settings for a cohort report.
         class CohortSpec
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
-        # 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.
         # @!attribute [rw] name
         #   @return [::String]
@@ -474,69 +488,100 @@ module Google
         #     `cohort_0`, `cohort_1`, etc.
         # @!attribute [rw] dimension
         #   @return [::String]
-        #     The dimension used by cohort. Only supports `firstTouchDate` for retention
-        #     report.
+        #     Dimension used by the cohort. Required and only supports `firstTouchDate`.
         # @!attribute [rw] date_range
         #   @return [::Google::Analytics::Data::V1alpha::DateRange]
-        #     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.
         class Cohort
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
-        # Settings of a cohort report.
-        # @!attribute [rw] accumulate
-        #   @return [::Boolean]
-        #     If true, accumulates the result from first visit day to the end day. Not
-        #     supported in `RunReportRequest`.
-        class CohortReportSettings
-          include ::Google::Protobuf::MessageExts
-          extend ::Google::Protobuf::MessageExts::ClassMethods
-        end
-
-        # 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.
         # @!attribute [rw] granularity
         #   @return [::Google::Analytics::Data::V1alpha::CohortsRange::Granularity]
-        #     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.
         # @!attribute [rw] start_offset
         #   @return [::Integer]
-        #     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.
         # @!attribute [rw] end_offset
         #   @return [::Integer]
-        #     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.
         class CohortsRange
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
 
-          # Reporting granularity for the cohorts.
+          # The granularity used to interpret the `startOffset` and `endOffset` for the
+          # extended reporting date range for a cohort report.
           module 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
           end
         end
 
+        # Optional settings of a cohort report.
+        # @!attribute [rw] accumulate
+        #   @return [::Boolean]
+        #     If true, accumulates the result from first touch day to the end day. Not
+        #     supported in `RunReportRequest`.
+        class CohortReportSettings
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
         # Response's metadata carrying additional information about the report content.
         # @!attribute [rw] data_loss_from_other_row
         #   @return [::Boolean]
@@ -735,6 +780,9 @@ module Google
         #     dimension is available by either `apiName` or one of `deprecatedApiNames`
         #     for a period of time. After the deprecation period, the dimension will be
         #     available only by `apiName`.
+        # @!attribute [rw] custom_definition
+        #   @return [::Boolean]
+        #     True if the dimension is a custom dimension for this property.
         class DimensionMetadata
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -766,6 +814,9 @@ module Google
         #     The mathematical expression for this derived metric. Can be used in
         #     [Metric](#Metric)'s `expression` field for equivalent reports. Most metrics
         #     are not expressions, and for non-expressions, this field is empty.
+        # @!attribute [rw] custom_definition
+        #   @return [::Boolean]
+        #     True if the metric is a custom metric for this property.
         class MetricMetadata
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods