147 lines
6.0 KiB
C++
147 lines
6.0 KiB
C++
// 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 = -1;
|
||
|
||
// Default value for user gender enum when no value has been set.
|
||
constexpr UserDemographicsProto_Gender kUserDemographicGenderDefaultEnumValue =
|
||
UserDemographicsProto_Gender_Gender_MIN;
|
||
|
||
// Default value for user birth year when no value has been set.
|
||
constexpr int kUserDemographicsBirthYearDefaultValue = -1;
|
||
|
||
// 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 = 100;
|
||
|
||
// 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 = 2;
|
||
|
||
// Minimal user age in years to provide demographics for.
|
||
constexpr int kUserDemographicsMinAgeInYears = 20;
|
||
|
||
// Max user age to provide demopgrahics for.
|
||
constexpr int kUserDemographicsMaxAgeInYears = 85;
|
||
|
||
// Preference names, exposed publicly for testing.
|
||
#if BUILDFLAG(IS_CHROMEOS_ASH)
|
||
extern const char kSyncOsDemographicsPrefName[];
|
||
#endif
|
||
extern const char kSyncDemographicsPrefName[];
|
||
extern const char kUserDemographicsBirthYearOffsetPrefName[];
|
||
// Deprecated (2022/09)
|
||
extern const char kDeprecatedDemographicsBirthYearOffsetPrefName[];
|
||
|
||
// These are not prefs, they are paths inside of kSyncDemographics.
|
||
extern const char kSyncDemographicsBirthYearPath[];
|
||
extern const char kSyncDemographicsGenderPath[];
|
||
|
||
// Container of user demographics.
|
||
struct UserDemographics {
|
||
int birth_year = 0;
|
||
UserDemographicsProto_Gender gender = UserDemographicsProto::Gender_MIN;
|
||
};
|
||
|
||
// 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 {
|
||
// Could get the user's noised birth year and gender.
|
||
kSuccess = 0,
|
||
// Sync is not enabled.
|
||
kSyncNotEnabled = 1,
|
||
// User's birth year and gender are ineligible to be provided either because
|
||
// some of them don't exist (missing data) or some of them are not eligible to
|
||
// be provided.
|
||
kIneligibleDemographicsData = 2,
|
||
// Could not get the time needed to compute the user's age.
|
||
kCannotGetTime = 3,
|
||
// There is more than one Profile for the Chrome browser. This entry is used
|
||
// by the DemographicMetricsProvider client.
|
||
kMoreThanOneProfile = 4,
|
||
// There is no sync service available for the loaded Profile. This entry is
|
||
// used by the DemographicMetricsProvider client.
|
||
kNoSyncService = 5,
|
||
// Upper boundary of the enum that is needed for the histogram.
|
||
kMaxValue = kNoSyncService
|
||
};
|
||
|
||
// Container and handler for data related to the retrieval of user demographics.
|
||
// Holds either valid demographics data or an error code.
|
||
class UserDemographicsResult {
|
||
public:
|
||
// Builds a UserDemographicsResult that contains user demographics and has a
|
||
// UserDemographicsStatus::kSuccess status.
|
||
static UserDemographicsResult ForValue(UserDemographics value);
|
||
|
||
// Builds a UserDemographicsResult that does not have user demographics (only
|
||
// default values) and has a status other than
|
||
// UserDemographicsStatus::kSuccess.
|
||
static UserDemographicsResult ForStatus(UserDemographicsStatus status);
|
||
|
||
// Determines whether demographics could be successfully retrieved.
|
||
bool IsSuccess() const;
|
||
|
||
// Gets the status of the result.
|
||
UserDemographicsStatus status() const;
|
||
|
||
// Gets the value of the result which will contain data when status() is
|
||
// UserDemographicsStatus::kSuccess.
|
||
const UserDemographics& value() const;
|
||
|
||
private:
|
||
UserDemographicsResult(UserDemographics value, UserDemographicsStatus status);
|
||
|
||
UserDemographics value_;
|
||
UserDemographicsStatus status_ = UserDemographicsStatus::kMaxValue;
|
||
};
|
||
|
||
// 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_
|