user_demographics.h | Explore in Territory

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

#ifndef COMPONENTS_METRICS_DEMOGRAPHICS_USER_DEMOGRAPHICS_H_
#define COMPONENTS_METRICS_DEMOGRAPHICS_USER_DEMOGRAPHICS_H_

#include "base/time/time.h"
#include "build/build_config.h"
#include "third_party/metrics_proto/user_demographics.pb.h"

class PrefService;
class PrefRegistrySimple;

namespace metrics {

// Default value for user gender when no value has been set.
constexpr int kUserDemographicsGenderDefaultValue = …;

// Default value for user gender enum when no value has been set.
constexpr UserDemographicsProto_Gender kUserDemographicGenderDefaultEnumValue = …;

// Default value for user birth year when no value has been set.
constexpr int kUserDemographicsBirthYearDefaultValue = …;

// Default value for birth year offset when no value has been set. Set to a
// really high value that |kUserDemographicsBirthYearNoiseOffsetRange| will
// never go over.
constexpr int kUserDemographicsBirthYearNoiseOffsetDefaultValue = …;

// Boundary of the +/- range in years within witch to randomly pick an offset to
// add to the user birth year. This adds noise to the birth year to not allow
// someone to accurately know a user's age. Possible offsets range from -2 to 2.
constexpr int kUserDemographicsBirthYearNoiseOffsetRange = …;

// Minimal user age in years to provide demographics for.
constexpr int kUserDemographicsMinAgeInYears = …;

// Max user age to provide demopgrahics for.
constexpr int kUserDemographicsMaxAgeInYears = …;

// Root dictionary pref to store the user's birth year and gender that are
// provided by the sync server. This is a read-only syncable priority pref on
// all platforms except ChromeOS Ash, where it is a syncable OS-level priority
// pref.
#if !BUILDFLAG(IS_CHROMEOS_ASH)
inline constexpr char kSyncDemographicsPrefName[] = …;
#else
inline constexpr char kSyncOsDemographicsPrefName[] = "sync.os_demographics";
// TODO(crbug.com/40240008): Make this non-syncable (on Ash only) after full
// rollout of the syncable os priority pref; then delete it locally from Ash
// devices.
inline constexpr char kSyncDemographicsPrefName[] = "sync.demographics";
#endif

// Stores a "secret" offset that is used to randomize the birth year for metrics
// reporting. This value should not be logged to UMA directly; instead, it
// should be summed with the kSyncDemographicsBirthYear. This value is generated
// locally on the client the first time a user begins to merge birth year data
// into their UMA reports.
inline constexpr char kUserDemographicsBirthYearOffsetPrefName[] = …;
// TODO(crbug.com/40240008): Delete after 2023/09
inline constexpr char kDeprecatedDemographicsBirthYearOffsetPrefName[] = …;

// These are not prefs, they are paths inside of kSyncDemographics.

// This pref value is subordinate to the kSyncDemographics dictionary pref and
// is synced to the client. It stores the self-reported birth year of the
// syncing user. as provided by the sync server. This value should not be logged
// to UMA directly; instead, it should be summed with the
// kSyncDemographicsBirthYearNoiseOffset.
inline constexpr char kSyncDemographicsBirthYearPath[] = …;

// This pref value is subordinate to the kSyncDemographics dictionary pref and
// is synced to the client. It stores the self-reported gender of the syncing
// user, as provided by the sync server. The gender is encoded using the Gender
// enum defined in UserDemographicsProto
// (see third_party/metrics_proto/user_demographics.proto).
inline constexpr char kSyncDemographicsGenderPath[] = …;

// Container of user demographics.
struct UserDemographics { … };

// Represents the status of providing user demographics (noised birth year and
// gender) that are logged to UMA. Entries of the enum should not be renumbered
// and numeric values should never be reused. Please keep in sync with
// "UserDemographicsStatus" in src/tools/metrics/histograms/enums.xml.  There
// should only be one entry representing demographic data that is ineligible to
// be provided. A finer grained division of kIneligibleDemographicsData (e.g.,
// INVALID_BIRTH_YEAR) might help inferring categories of demographics that
// should not be exposed to protect privacy.
enum class UserDemographicsStatus { … };

// Container and handler for data related to the retrieval of user demographics.
// Holds either valid demographics data or an error code.
class UserDemographicsResult { … };

// Registers the local state preferences that are needed to persist demographics
// information exposed via GetUserNoisedBirthYearAndGenderFromPrefs().
void RegisterDemographicsLocalStatePrefs(PrefRegistrySimple* registry);

// Registers the profile preferences that are needed to persist demographics
// information exposed via GetUserNoisedBirthYearAndGenderFromPrefs().
void RegisterDemographicsProfilePrefs(PrefRegistrySimple* registry);

// Clears the profile's demographics-related preferences containing user data.
// This excludes the internal birth year offset.
void ClearDemographicsPrefs(PrefService* profile_prefs);

// Gets the synced user’s birth year and gender from |profile_prefs|, and noise
// from |local_state|. See docs for metrics::DemographicMetricsProvider in
// components/metrics/demographic_metrics_provider.h for more details. Returns
// an error status with an empty value when the user's birth year or gender
// cannot be provided. You need to provide an accurate |now| time that
// represents the current time.
UserDemographicsResult GetUserNoisedBirthYearAndGenderFromPrefs(
    base::Time now,
    PrefService* local_state,
    PrefService* profile_prefs);

}  // namespace metrics

#endif  // COMPONENTS_METRICS_DEMOGRAPHICS_USER_DEMOGRAPHICS_H_
chromium/components/metrics/demographics/user_demographics.h
