<!--
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.
-->

<!--
This file is used to generate a comprehensive list of ReadAloud histograms
along with a detailed description for each histogram.

For best practices on writing histogram descriptions, see
https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md

Please follow the instructions in the OWNERS file in this directory to find a
reviewer. If no OWNERS file exists, please consider signing up at
go/reviewing-metrics (Googlers only), as all subdirectories are expected to
have an OWNERS file. As a last resort you can send the CL to
chromium-metrics-reviews@google.com.
-->

<histogram-configuration>

<histograms>

<variants name="Phase">
  <variant name="Playback"/>
  <variant name="PlaybackRequest"/>
  <variant name="ReadabilityCheck"/>
</variants>

<histogram name="ReadAloud.AudioOverviews.PlaybackPositionOnManualClose"
    enum="PlaybackLocation" expires_after="2027-02-14">
  <owner>shlomib@google.com</owner>
  <summary>
    Android only. Records the playback location at the time when the user
    manually closes the readaloud player (using the X button). Recorded only in
    Audio Overviews playback.
  </summary>
</histogram>

<histogram name="ReadAloud.AudioOverviews.TimeToMidLoadingManualClose"
    units="ms" expires_after="2027-02-14">
  <owner>shlomib@google.com</owner>
  <summary>
    Android only. Recorded when the user closes the player while the playback is
    still loading. Records how long it takes for users to hit X while the
    playback is still loading. Recorded only for audio overview playback.
  </summary>
</histogram>

<histogram name="ReadAloud.DurationListened" units="ms"
    expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Record user's cumulative duration spent listening to a single playback.
    Emitted when playback is reset. Max value is 1 hour. Any listening durations
    longer than 1 hour will be recorded as 1 hour.
  </summary>
</histogram>

<histogram name="ReadAloud.DurationListened.LockedScreen" units="ms"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Record user's cumulative duration spent listening to a single playback with
    the screen locked. Emitted when playback is reset. Max value is 1 hour. Any
    listening durations longer than 1 hour will be recorded as 1 hour.
  </summary>
</histogram>

<histogram name="ReadAloud.DurationScrubbingBackwardsSeekbar" units="ms"
    expires_after="2027-08-09">
  <owner>sanaakbani@google.com</owner>
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Records when a user scrubs backwards on the expanded player seekbar.
    Measures the duration (in milliseconds) between the user starting and
    stopping a touch on the seekbar. Max value is 1 hour. Any interval longer
    than 1 hour will be logged as 1 hour.
  </summary>
</histogram>

<histogram name="ReadAloud.DurationScrubbingForwardsSeekbar" units="ms"
    expires_after="2027-08-09">
  <owner>sanaakbani@google.com</owner>
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Records when a user scrubs forwards on the expanded player seekbar. Measures
    the duration (in milliseconds) between the user starting and stopping a
    touch on the seekbar. Max value is 1 hour. Any interval longer than 1 hour
    will be logged as 1 hour.
  </summary>
</histogram>

<histogram name="ReadAloud.Eligibility.IneligiblityReason"
    enum="ReadAloudIneligibilityReason" expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Histogram for recording why a user is not eligible for the
    ReadAloud feature. Emitted when the user profile is available and the user
    is ineligible. Conditions are checked in ReadAloudFeatures. Don't use data
    from before M123.
  </summary>
</histogram>

<histogram name="ReadAloud.Eligibility.IsUserEligible" enum="BooleanEligible"
    expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Histogram for recording if a user is eligible for ReadAloud.
    Emitted when the user profile is available. Don't use data from before M123.
  </summary>
</histogram>

<histogram name="ReadAloud.EmptyURLPlayback" enum="ReadAloudEntrypoint"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Records entrypoint from which a request to play an empty URL
    was executed. Recorded for each empty URL that had a playback requested.
  </summary>
</histogram>

<histogram name="ReadAloud.HasDateModified" enum="BooleanSuccess"
    expires_after="2026-10-11">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Histogram for recording if we were able to retrieve dateModified for the
    requested tab. False value could mean that the page either doesn't specify
    dateModified or there was an error during retrieval.
  </summary>
</histogram>

<histogram name="ReadAloud.HasTapToSeekFoundMatch" enum="BooleanSuccess"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Record if Read Aloud finds a substring match between the user's requested
    word to seek to and the distilled Read Aloud text.
  </summary>
</histogram>

<histogram name="ReadAloud.HighlightingEnabled" enum="BooleanEnabled"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Histogram for recording if highlighting is enabled or disabled. Emitted when
    the user toggles the &quot;Highlighting enabled&quot; setting.
  </summary>
</histogram>

<histogram name="ReadAloud.HighlightingEnabled.OnStartup" enum="BooleanEnabled"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Histogram for recording if highlighting is enabled or disabled on session
    startup.
  </summary>
</histogram>

<histogram name="ReadAloud.HighlightingSupported" enum="BooleanSupported"
    expires_after="2026-12-06">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Histogram for recording if highlighting is supported. Emitted when a
    playback is successfully created. Warning: This histogram was expired from
    2024-12 to 2025-04; data may be missing.
  </summary>
</histogram>

<histogram name="ReadAloud.IsPageReadabilitySuccessful" enum="BooleanSuccess"
    expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Histogram for recording if a page readability check is successful or fails.
    The readability check is run on each page load for Android clients who are
    eligible for ReadAloud.
  </summary>
</histogram>

<histogram name="ReadAloud.IsPageReadable" enum="BooleanEligible"
    expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Histogram for recording if a page is readable or not. Will be
    recorded only if ReadAloud is enabled and initialization of all
    ReadAloud-required objects was successful. Emitted when readability check is
    requested (on page load, on redirect, on selecting a tab), and cached
    readability results may be retured. This histogram contain both server side
    readability responses as well as client side optimizations (client will fail
    fast readability check for some URL types). For server side only readability
    ratio, check ReadAloud.ServerReadabilityResult. Do not use data from before
    M123.
  </summary>
</histogram>

<histogram name="ReadAloud.IsTabPlaybackCreationSuccessful"
    enum="BooleanSuccess" expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Records if a tab playback creation succeeds or fails. Emitted in the tab
    playback creation callback. Does not mean playback has started.
  </summary>
</histogram>

<histogram name="ReadAloud.PlaybackModeChange" enum="PlaybackMode"
    expires_after="2027-02-14">
  <owner>shlomib@google.com</owner>
  <owner>juanmejia@google.com</owner>
  <summary>
    Histogram for recording what playback mode setting a user selects for the
    ReadAloud playback. Emitted when the ReadAloud playback mode is changed.
  </summary>
</histogram>

<histogram name="ReadAloud.ReadAloudError.{Phase}" enum="ReadAloudErrorCode"
    expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Records cause of a ReadAloud-speficic exception. In case more details are
    known, ReadAloud.ReadAloudUnsuportedError.{Phase} or
    ReadAloud.ReadAloudNetError.{Phase} will also be emitted. Recorded during
    {Phase}.
  </summary>
  <token key="Phase" variants="Phase"/>
</histogram>

<histogram name="ReadAloud.ReadAloudNetError.{Phase}" enum="NetErrorCodes"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Network status codes recorded for each ReadAloudRequest that fails and has
    this information present. Recorded value is the absolute value of the
    received net::Error value.

    Recorded during {Phase}.
  </summary>
  <token key="Phase" variants="Phase"/>
</histogram>

<histogram name="ReadAloud.ReadAloudPlaybackWithoutReadabilityCheckError"
    enum="ReadAloudEntrypoint" expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Records entrypoint from which a request to play a tab was
    executed without checking for page readability readability first. Recorded
    for each playback request without prior readability check.
  </summary>
</histogram>

<histogram name="ReadAloud.ReadAloudUnsuportedError.{Phase}"
    enum="RejectionReason" expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Records a rejection reason for not being able to trigger or continue read
    aloud. Recorded during {Phase}.
  </summary>
  <token key="Phase" variants="Phase"/>
</histogram>

<histogram name="ReadAloud.ServerReadabilityResult" enum="BooleanEligible"
    expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Histogram for recording server side responses if a page is
    readable or not. Will be recorded only if ReadAloud is enabled,
    initialization of all ReadAloud-required objects was successful and no
    previously cached readability results are available for the requested URL.
    Emitted from a server response callback when requesting readability
    information.
  </summary>
</histogram>

<histogram name="ReadAloud.SpeedChange" enum="ReadAloudSpeed"
    expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Histogram for recording what speed setting a user selects for the ReadAloud
    playback. Emitted when the ReadAloud speed pref is changed.
  </summary>
</histogram>

<histogram name="ReadAloud.StandardPlayback.PlaybackPositionOnManualClose"
    enum="PlaybackLocation" expires_after="2027-02-14">
  <owner>shlomib@google.com</owner>
  <summary>
    Android only. Records the playback location at the time when the user
    manually closes the readaloud player (using the X button). Recorded only in
    standard playback.
  </summary>
</histogram>

<histogram name="ReadAloud.StandardPlayback.TimeToMidLoadingManualClose"
    units="ms" expires_after="2027-02-14">
  <owner>shlomib@google.com</owner>
  <summary>
    Android only. Recorded when the user closes the player while the playback is
    still loading. Records how long it takes for users to hit X while the
    playback is still loading. Recorded only for standard playbacks.
  </summary>
</histogram>

<histogram name="ReadAloud.TabPlaybackCreationFailure"
    enum="ReadAloudEntrypoint" expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Records when a a request to create playback from given
    entrypoint fails. Emitted in the tab playback creation callback. Does not
    mean playback has started.
  </summary>
</histogram>

<histogram name="ReadAloud.TabPlaybackCreationSuccess"
    enum="ReadAloudEntrypoint" expires_after="2027-02-14">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Records when a a request to create playback from given
    entrypoint succeeds. Emitted in the tab playback creation callback. Does not
    mean playback has started.
  </summary>
</histogram>

<histogram name="ReadAloud.TabPlaybackStoppedReason"
    enum="PlaybackStoppedReason" expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Records reason for stopping a tab playback. Note that this
    doesn't include stopping the voice preview playbacks. Warning: This
    histogram was expired from 2024-12 to 2025-04; data may be missing.
  </summary>
</histogram>

<histogram name="ReadAloud.TapToSeekTime" units="ms" expires_after="2027-08-09">
  <owner>andresmolina@google.com</owner>
  <owner>chrome-readaloud-team@google.com</owner>
  <summary>
    Android only. Records processing time for a tap to seek feature. Finds a
    matching substring in the ReadAloud distilled text to seek playback to the
    word. Records the time taken for both successful and failed attempts to
    match the substring.
  </summary>
</histogram>

</histograms>

</histogram-configuration>
