configuration.h 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. // Copyright 2017 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_FEATURE_ENGAGEMENT_PUBLIC_CONFIGURATION_H_
  5. #define COMPONENTS_FEATURE_ENGAGEMENT_PUBLIC_CONFIGURATION_H_
  6. #include <map>
  7. #include <ostream>
  8. #include <set>
  9. #include <string>
  10. #include <vector>
  11. #include "third_party/abseil-cpp/absl/types/optional.h"
  12. namespace base {
  13. struct Feature;
  14. }
  15. namespace feature_engagement {
  16. // A ComparatorType describes the relationship between two numbers.
  17. enum ComparatorType {
  18. ANY = 0, // Will always yield true.
  19. LESS_THAN = 1,
  20. GREATER_THAN = 2,
  21. LESS_THAN_OR_EQUAL = 3,
  22. GREATER_THAN_OR_EQUAL = 4,
  23. EQUAL = 5,
  24. NOT_EQUAL = 6,
  25. };
  26. // A Comparator provides a way of comparing a uint32_t another uint32_t and
  27. // verifying their relationship.
  28. struct Comparator {
  29. public:
  30. Comparator();
  31. Comparator(ComparatorType type, uint32_t value);
  32. ~Comparator();
  33. // Returns true if the |v| meets the this criteria based on the current
  34. // |type| and |value|.
  35. bool MeetsCriteria(uint32_t v) const;
  36. ComparatorType type;
  37. uint32_t value;
  38. };
  39. bool operator==(const Comparator& lhs, const Comparator& rhs);
  40. bool operator<(const Comparator& lhs, const Comparator& rhs);
  41. std::ostream& operator<<(std::ostream& os, const Comparator& comparator);
  42. // A EventConfig contains all the information about how many times
  43. // a particular event should or should not have triggered, for which window
  44. // to search in and for how long to store it.
  45. struct EventConfig {
  46. public:
  47. EventConfig();
  48. EventConfig(const std::string& name,
  49. Comparator comparator,
  50. uint32_t window,
  51. uint32_t storage);
  52. ~EventConfig();
  53. // The identifier of the event.
  54. std::string name;
  55. // The number of events it is required to find within the search window.
  56. Comparator comparator;
  57. // Search for this event within this window.
  58. uint32_t window;
  59. // Store client side data related to events for this minimum this long.
  60. uint32_t storage;
  61. };
  62. bool operator==(const EventConfig& lhs, const EventConfig& rhs);
  63. bool operator!=(const EventConfig& lhs, const EventConfig& rhs);
  64. bool operator<(const EventConfig& lhs, const EventConfig& rhs);
  65. std::ostream& operator<<(std::ostream& os, const EventConfig& event_config);
  66. // A SessionRateImpact describes which features the |session_rate| of a given
  67. // FeatureConfig should affect. It can affect either |ALL| (default), |NONE|,
  68. // or an |EXPLICIT| list of the features. In the latter case, a list of affected
  69. // features is given as their base::Feature name.
  70. struct SessionRateImpact {
  71. public:
  72. enum class Type {
  73. ALL = 0, // Affects all other features.
  74. NONE = 1, // Affects no other features.
  75. EXPLICIT = 2 // Affects only features in |affected_features|.
  76. };
  77. SessionRateImpact();
  78. SessionRateImpact(const SessionRateImpact& other);
  79. ~SessionRateImpact();
  80. // Describes which features are impacted.
  81. Type type;
  82. // In the case of the Type |EXPLICIT|, this is the list of affected
  83. // base::Feature names.
  84. absl::optional<std::vector<std::string>> affected_features;
  85. };
  86. // BlockedBy describes which features the |blocked_by| of a given
  87. // FeatureConfig should affect. It can affect either |ALL| (default), |NONE|,
  88. // or an |EXPLICIT| list of the features. In the latter case, a list of affected
  89. // features is given as their base::Feature name.
  90. struct BlockedBy {
  91. public:
  92. enum class Type {
  93. ALL = 0, // Affects all other features.
  94. NONE = 1, // Affects no other features.
  95. EXPLICIT = 2 // Affects only features in |affected_features|.
  96. };
  97. BlockedBy();
  98. BlockedBy(const BlockedBy& other);
  99. ~BlockedBy();
  100. // Describes which features are impacted.
  101. Type type{Type::ALL};
  102. // In the case of the Type |EXPLICIT|, this is the list of affected
  103. // base::Feature names.
  104. absl::optional<std::vector<std::string>> affected_features;
  105. };
  106. // Blocking describes which features the |blocking| of a given FeatureConfig
  107. // should affect. It can affect either |ALL| (default) or |NONE|.
  108. struct Blocking {
  109. public:
  110. enum class Type {
  111. ALL = 0, // Affects all other features.
  112. NONE = 1, // Affects no other features.
  113. };
  114. Blocking();
  115. Blocking(const Blocking& other);
  116. ~Blocking();
  117. // Describes which features are impacted.
  118. Type type{Type::ALL};
  119. };
  120. // A SnoozeParams describes the parameters for snoozable options of in-product
  121. // help.
  122. struct SnoozeParams {
  123. public:
  124. // The maximum number of times an in-product-help can be snoozed.
  125. uint32_t max_limit{0};
  126. // The minimum time interval between snoozes.
  127. uint32_t snooze_interval{0};
  128. SnoozeParams();
  129. SnoozeParams(const SnoozeParams& other);
  130. ~SnoozeParams();
  131. };
  132. bool operator==(const SessionRateImpact& lhs, const SessionRateImpact& rhs);
  133. std::ostream& operator<<(std::ostream& os, const SessionRateImpact& impact);
  134. // A FeatureConfig contains all the configuration for a given feature.
  135. struct FeatureConfig {
  136. public:
  137. FeatureConfig();
  138. FeatureConfig(const FeatureConfig& other);
  139. ~FeatureConfig();
  140. // Whether the configuration has been successfully parsed.
  141. bool valid;
  142. // The configuration for a particular event that will be searched for when
  143. // counting how many times a particular feature has been used.
  144. EventConfig used;
  145. // The configuration for a particular event that will be searched for when
  146. // counting how many times in-product help has been triggered for a particular
  147. // feature.
  148. EventConfig trigger;
  149. // A set of all event configurations.
  150. std::set<EventConfig> event_configs;
  151. // Number of in-product help triggered within this session must fit this
  152. // comparison.
  153. Comparator session_rate;
  154. // Which features the showing this in-product help impacts.
  155. SessionRateImpact session_rate_impact;
  156. // Which features the current in-product help is blocked by.
  157. BlockedBy blocked_by;
  158. // Which features the current in-product help is blocking.
  159. Blocking blocking;
  160. // Number of days the in-product help has been available must fit this
  161. // comparison.
  162. Comparator availability;
  163. // Whether this configuration will only be used for tracking and comparisons
  164. // between experiment groups. Setting this to true will ensure that
  165. // Tracker::ShouldTriggerHelpUI(...) always returns false, but if all
  166. // other conditions are met, it will still be recorded as having been
  167. // shown in the internal database and through UMA.
  168. bool tracking_only{false};
  169. // Snoozing parameter to decide if in-product help should be shown.
  170. SnoozeParams snooze_params;
  171. };
  172. bool operator==(const FeatureConfig& lhs, const FeatureConfig& rhs);
  173. std::ostream& operator<<(std::ostream& os, const FeatureConfig& feature_config);
  174. // A Configuration contains the current set of runtime configurations.
  175. // It is up to each implementation of Configuration to provide a way to
  176. // register features and their configurations.
  177. class Configuration {
  178. public:
  179. // Convenience alias for typical implementations of Configuration.
  180. using ConfigMap = std::map<std::string, FeatureConfig>;
  181. Configuration(const Configuration&) = delete;
  182. Configuration& operator=(const Configuration&) = delete;
  183. virtual ~Configuration() = default;
  184. // Returns the FeatureConfig for the given |feature|. The |feature| must
  185. // be registered with the Configuration instance.
  186. virtual const FeatureConfig& GetFeatureConfig(
  187. const base::Feature& feature) const = 0;
  188. // Returns the FeatureConfig for the given |feature|. The |feature_name| must
  189. // be registered with the Configuration instance.
  190. virtual const FeatureConfig& GetFeatureConfigByName(
  191. const std::string& feature_name) const = 0;
  192. // Returns the immutable ConfigMap that contains all registered features.
  193. virtual const ConfigMap& GetRegisteredFeatureConfigs() const = 0;
  194. // Returns the list of the names of all registred features.
  195. virtual const std::vector<std::string> GetRegisteredFeatures() const = 0;
  196. protected:
  197. Configuration() = default;
  198. };
  199. } // namespace feature_engagement
  200. #endif // COMPONENTS_FEATURE_ENGAGEMENT_PUBLIC_CONFIGURATION_H_