user_demographics.h 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
  1. // Copyright 2019 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef COMPONENTS_METRICS_DEMOGRAPHICS_USER_DEMOGRAPHICS_H_
  5. #define COMPONENTS_METRICS_DEMOGRAPHICS_USER_DEMOGRAPHICS_H_
  6. #include "base/time/time.h"
  7. #include "third_party/metrics_proto/user_demographics.pb.h"
  8. class PrefService;
  9. namespace user_prefs {
  10. class PrefRegistrySyncable;
  11. } // namespace user_prefs
  12. namespace metrics {
  13. // Default value for user gender when no value has been set.
  14. constexpr int kUserDemographicsGenderDefaultValue = -1;
  15. // Default value for user gender enum when no value has been set.
  16. constexpr UserDemographicsProto_Gender kUserDemographicGenderDefaultEnumValue =
  17. UserDemographicsProto_Gender_Gender_MIN;
  18. // Default value for user birth year when no value has been set.
  19. constexpr int kUserDemographicsBirthYearDefaultValue = -1;
  20. // Default value for birth year offset when no value has been set. Set to a
  21. // really high value that |kUserDemographicsBirthYearNoiseOffsetRange| will
  22. // never go over.
  23. constexpr int kUserDemographicsBirthYearNoiseOffsetDefaultValue = 100;
  24. // Boundary of the +/- range in years within witch to randomly pick an offset to
  25. // add to the user birth year. This adds noise to the birth year to not allow
  26. // someone to accurately know a user's age. Possible offsets range from -2 to 2.
  27. constexpr int kUserDemographicsBirthYearNoiseOffsetRange = 2;
  28. // Minimal user age in years to provide demographics for.
  29. constexpr int kUserDemographicsMinAgeInYears = 20;
  30. // Max user age to provide demopgrahics for.
  31. constexpr int kUserDemographicsMaxAgeInYears = 85;
  32. // Syncable preference names, exposed publicly for testing.
  33. extern const char kSyncDemographicsPrefName[];
  34. extern const char kSyncDemographicsBirthYearOffsetPrefName[];
  35. // These are not prefs, they are paths inside of kSyncDemographics.
  36. extern const char kSyncDemographicsBirthYearPath[];
  37. extern const char kSyncDemographicsGenderPath[];
  38. // Container of user demographics.
  39. struct UserDemographics {
  40. int birth_year = 0;
  41. UserDemographicsProto_Gender gender = UserDemographicsProto::Gender_MIN;
  42. };
  43. // Represents the status of providing user demographics (noised birth year and
  44. // gender) that are logged to UMA. Entries of the enum should not be renumbered
  45. // and numeric values should never be reused. Please keep in sync with
  46. // "UserDemographicsStatus" in src/tools/metrics/histograms/enums.xml. There
  47. // should only be one entry representing demographic data that is ineligible to
  48. // be provided. A finer grained division of kIneligibleDemographicsData (e.g.,
  49. // INVALID_BIRTH_YEAR) might help inferring categories of demographics that
  50. // should not be exposed to protect privacy.
  51. enum class UserDemographicsStatus {
  52. // Could get the user's noised birth year and gender.
  53. kSuccess = 0,
  54. // Sync is not enabled.
  55. kSyncNotEnabled = 1,
  56. // User's birth year and gender are ineligible to be provided either because
  57. // some of them don't exist (missing data) or some of them are not eligible to
  58. // be provided.
  59. kIneligibleDemographicsData = 2,
  60. // Could not get the time needed to compute the user's age.
  61. kCannotGetTime = 3,
  62. // There is more than one Profile for the Chrome browser. This entry is used
  63. // by the DemographicMetricsProvider client.
  64. kMoreThanOneProfile = 4,
  65. // There is no sync service available for the loaded Profile. This entry is
  66. // used by the DemographicMetricsProvider client.
  67. kNoSyncService = 5,
  68. // Upper boundary of the enum that is needed for the histogram.
  69. kMaxValue = kNoSyncService
  70. };
  71. // Container and handler for data related to the retrieval of user demographics.
  72. // Holds either valid demographics data or an error code.
  73. class UserDemographicsResult {
  74. public:
  75. // Builds a UserDemographicsResult that contains user demographics and has a
  76. // UserDemographicsStatus::kSuccess status.
  77. static UserDemographicsResult ForValue(UserDemographics value);
  78. // Builds a UserDemographicsResult that does not have user demographics (only
  79. // default values) and has a status other than
  80. // UserDemographicsStatus::kSuccess.
  81. static UserDemographicsResult ForStatus(UserDemographicsStatus status);
  82. // Determines whether demographics could be successfully retrieved.
  83. bool IsSuccess() const;
  84. // Gets the status of the result.
  85. UserDemographicsStatus status() const;
  86. // Gets the value of the result which will contain data when status() is
  87. // UserDemographicsStatus::kSuccess.
  88. const UserDemographics& value() const;
  89. private:
  90. UserDemographicsResult(UserDemographics value, UserDemographicsStatus status);
  91. UserDemographics value_;
  92. UserDemographicsStatus status_ = UserDemographicsStatus::kMaxValue;
  93. };
  94. // Registers the profile preferences that are needed to persist demographics
  95. // information exposed via GetUserNoisedBirthYearAndGenderFromPrefs().
  96. void RegisterDemographicsProfilePrefs(
  97. user_prefs::PrefRegistrySyncable* registry);
  98. // Clears the profile's demographics-related preferences containing user data.
  99. // This excludes the internal bith year offset.
  100. void ClearDemographicsPrefs(PrefService* pref_service);
  101. // Gets the synced user’s noised birth year and gender from preferences, see doc
  102. // of metrics::DemographicMetricsProvider in
  103. // components/metrics/demographic_metrics_provider.h for more details. Returns
  104. // an error status with an empty value when the user's birth year or gender
  105. // cannot be provided. You need to provide an accurate |now| time that
  106. // represents the current time.
  107. UserDemographicsResult GetUserNoisedBirthYearAndGenderFromPrefs(
  108. base::Time now,
  109. PrefService* pref_service);
  110. } // namespace metrics
  111. #endif // COMPONENTS_METRICS_DEMOGRAPHICS_USER_DEMOGRAPHICS_H_