chrome/browser/companion/core/companion_metrics_logger.h

// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CHROME_BROWSER_COMPANION_CORE_COMPANION_METRICS_LOGGER_H_
#define CHROME_BROWSER_COMPANION_CORE_COMPANION_METRICS_LOGGER_H_

#include "base/memory/raw_ptr.h"
#include "chrome/browser/companion/core/mojom/companion.mojom.h"
#include "services/metrics/public/cpp/ukm_source_id.h"
#include "url/gurl.h"

using side_panel::mojom::PhFeedback;
using side_panel::mojom::PromoAction;
using side_panel::mojom::PromoType;
using side_panel::mojom::UiSurface;

namespace companion {

// Invalid values.
const int32_t kInvalidPosition = -1;
const int32_t kInvalidNumChildren = -1;

// Types of events on the UI surfaces. Keep in sync with Companion.UiEvent in
// enums.xml.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum class UiEvent {
  // The UI surface was not shown.
  kNotAvailable = 1,

  // The UI surface was shown.
  kShown = 2,

  // User clicked on the UI surface.
  kClicked = 3,
};

// Various UI locations from which the companion page can be launched. Keep in
// sync with Companion.OpenTrigger in enums.xml. These values are persisted to
// logs. Entries should not be renumbered and numeric values should never be
// reused.
enum class OpenTrigger {
  // Launch location is unknown.
  kUnknown = 0,

  // The companion page was opened via a context menu image search.
  kContextMenuImageSearch = 1,

  // The companion page was opened via a context menu text search.
  kContextMenuTextSearch = 2,

  // Other types of launches. Includes the toolbar button entry point.
  kOther = 3,
};

// Tracks events happening on a single UI surface.
struct UiSurfaceMetrics {
  UiSurfaceMetrics() = default;
  UiSurfaceMetrics(const UiSurfaceMetrics& other) = default;
  UiSurfaceMetrics& operator=(const UiSurfaceMetrics& other) = default;
  ~UiSurfaceMetrics() = default;

  // Events on the surface. The last event wins and gets recorded.
  UiEvent last_event = UiEvent::kNotAvailable;

  // The position of the UI surface relative to the companion page.
  size_t ui_surface_position = kInvalidPosition;

  // The number of child elements that were considered to be shown within the
  // surface, e.g. number of candidate queries inside related queries component.
  size_t child_element_available_count = kInvalidNumChildren;

  // The number of child elements shown within the surface, e.g. number of
  // related queries inside related queries component.
  size_t child_element_shown_count = kInvalidNumChildren;

  // The number of times user clicked on the surface.
  size_t click_count = 0;

  // The position of the clicked UI element within its parent list. Applicable
  // to surfaces that show a list.
  int32_t click_position = kInvalidPosition;
};

// Various types of events happening on the promo surfaces on the companion
// page. Keep in sync with Companion.PromoEvent in enums.xml. These values are
// persisted to logs. Entries should not be renumbered and numeric values should
// never be reused.
enum class PromoEvent {
  kUnknown = 0,
  kSignInShown = 1,
  kSignInAccepted = 2,
  kSignInRejected = 3,
  kMsbbShown = 4,
  kMsbbAccepted = 5,
  kMsbbRejected = 6,
  kExpsShown = 7,
  kExpsAccepted = 8,
  kExpsRejected = 9,
  kMaxValue = kExpsRejected,
};

// Utility to log UKM and UMA metrics for events happening on the companion
// page. Should be associated with a single navigation. Flushes metrics on
// destruction.
class CompanionMetricsLogger {
 public:
  explicit CompanionMetricsLogger(ukm::SourceId ukm_source_id);
  CompanionMetricsLogger(const CompanionMetricsLogger&) = delete;
  CompanionMetricsLogger& operator=(const CompanionMetricsLogger&) = delete;
  ~CompanionMetricsLogger();

  void RecordOpenTrigger(OpenTrigger open_trigger);

  // For the following methods, please refer CompanionPageHandler in
  // companion.mojom for detailed documentation.

  // Logging method corresponding to `RecordUiSurfaceShown` in companion.mojom.
  void RecordUiSurfaceShown(UiSurface ui_surface,
                            uint32_t ui_surface_position,
                            uint32_t child_element_available_count,
                            uint32_t child_element_shown_count);

  // Logging method corresponding to `RecordUiSurfaceClicked` in
  // companion.mojom.
  void RecordUiSurfaceClicked(UiSurface ui_surface, int32_t click_position);

  // Logging method corresponding to `OnPromoAction` in companion.mojom.
  void OnPromoAction(PromoType promo_type, PromoAction promo_action);

  // Logging method corresponding to `OnPhFeedback` in companion.mojom.
  void OnPhFeedback(PhFeedback ph_feedback);

 private:
  // Meant to be called at destruction. Flushes the UKM metrics.
  void FlushStats();

  // The UKM source ID for the page being shown.
  ukm::SourceId ukm_source_id_;

  // In-memory accumulator of UI surface metrics.
  std::map<UiSurface, UiSurfaceMetrics> ui_surface_metrics_;

  // Last event on the promo surfaces.
  absl::optional<PromoEvent> last_promo_event_;

  // Last event on the promo surfaces.
  absl::optional<PhFeedback> last_ph_feedback_;

  // Indicates how the companion page was opened. Non-empty for the first
  // navigation.
  absl::optional<OpenTrigger> open_trigger_;
};

}  // namespace companion

#endif  // CHROME_BROWSER_COMPANION_CORE_COMPANION_METRICS_LOGGER_H_