variations_associated_data.h 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  1. // Copyright 2013 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_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_
  5. #define COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_
  6. #include <map>
  7. #include <memory>
  8. #include <string>
  9. #include "base/metrics/field_trial.h"
  10. #include "components/variations/active_field_trials.h"
  11. // This file provides various helpers that extend the functionality around
  12. // base::FieldTrial.
  13. //
  14. // This includes several simple APIs to handle getting and setting additional
  15. // data related to Chrome variations, such as parameters and Google variation
  16. // IDs. These APIs are meant to extend the base::FieldTrial APIs to offer extra
  17. // functionality that is not offered by the simpler base::FieldTrial APIs.
  18. //
  19. // The AssociateGoogleVariationID and AssociateVariationParams functions are
  20. // generally meant to be called by the VariationsService based on server-side
  21. // variation configs, but may also be used for client-only field trials by
  22. // invoking them directly after appending all the groups to a FieldTrial.
  23. //
  24. // Experiment code can then use the getter APIs to retrieve variation parameters
  25. // or IDs:
  26. //
  27. // std::map<std::string, std::string> params;
  28. // if (GetVariationParams("trial", &params)) {
  29. // // use |params|
  30. // }
  31. //
  32. // std::string value = GetVariationParamValue("trial", "param_x");
  33. // // use |value|, which will be "" if it does not exist
  34. //
  35. // VariationID id = GetGoogleVariationID(
  36. // GOOGLE_WEB_PROPERTIES_ANY_CONTEXT, "trial", "group1");
  37. // if (id != variations::EMPTY_ID) {
  38. // // use |id|
  39. // }
  40. namespace variations {
  41. typedef int VariationID;
  42. const VariationID EMPTY_ID = 0;
  43. // A key into the Associate/Get methods for VariationIDs. This is used to create
  44. // separate ID associations for separate parties interested in VariationIDs.
  45. enum IDCollectionKey {
  46. // The IDs in this collection are used by Google web properties and are
  47. // transmitted via the X-Client-Data header. These IDs are transmitted in
  48. // first- and third-party contexts.
  49. GOOGLE_WEB_PROPERTIES_ANY_CONTEXT,
  50. // The IDs in this collection are used by Google web properties and are
  51. // transmitted via the X-Client-Data header. When kRestrictGoogleWebVisibility
  52. // is enabled, these IDs are transmitted in only first-party contexts;
  53. // otherwise, these IDs are transmitted in first- and third-party contexts.
  54. GOOGLE_WEB_PROPERTIES_FIRST_PARTY,
  55. // This collection is used by Google web properties for signed in users only,
  56. // transmitted through the X-Client-Data header.
  57. GOOGLE_WEB_PROPERTIES_SIGNED_IN,
  58. // The IDs in this collection are used by Google web properties to trigger
  59. // server-side experimental behavior and are transmitted via the X-Client-Data
  60. // header. These IDs are transmitted in first- and third-party contexts.
  61. GOOGLE_WEB_PROPERTIES_TRIGGER_ANY_CONTEXT,
  62. // The IDs in this collection are used by Google web properties to trigger
  63. // server-side experimental behavior and are transmitted via the X-Client-Data
  64. // header. When kRestrictGoogleWebVisibility is enabled, these IDs are
  65. // transmitted in only first-party contexts; otherwise, these IDs are
  66. // transmitted in first- and third-party contexts.
  67. GOOGLE_WEB_PROPERTIES_TRIGGER_FIRST_PARTY,
  68. // This collection is used by the Google App and is passed at the time
  69. // the cross-app communication is triggered.
  70. GOOGLE_APP,
  71. // The total count of collections.
  72. ID_COLLECTION_COUNT,
  73. };
  74. // Associate a variations::VariationID value with a FieldTrial group for
  75. // collection |key|. If an id was previously set for |trial_name| and
  76. // |group_name|, this does nothing. The group is denoted by |trial_name| and
  77. // |group_name|. This must be called whenever a FieldTrial is prepared (create
  78. // the trial and append groups) and needs to have a variations::VariationID
  79. // associated with it so Google servers can recognize the FieldTrial.
  80. // Thread safe.
  81. COMPONENT_EXPORT(VARIATIONS)
  82. void AssociateGoogleVariationID(IDCollectionKey key,
  83. const std::string& trial_name,
  84. const std::string& group_name,
  85. VariationID id);
  86. // As above, but overwrites any previously set id. Thread safe.
  87. COMPONENT_EXPORT(VARIATIONS)
  88. void AssociateGoogleVariationIDForce(IDCollectionKey key,
  89. const std::string& trial_name,
  90. const std::string& group_name,
  91. VariationID id);
  92. // As above, but takes an ActiveGroupId hash pair, rather than the string names.
  93. COMPONENT_EXPORT(VARIATIONS)
  94. void AssociateGoogleVariationIDForceHashes(IDCollectionKey key,
  95. const ActiveGroupId& active_group,
  96. VariationID id);
  97. // Retrieve the variations::VariationID associated with a FieldTrial group for
  98. // collection |key|. The group is denoted by |trial_name| and |group_name|.
  99. // This will return variations::EMPTY_ID if there is currently no associated ID
  100. // for the named group. This API can be nicely combined with
  101. // FieldTrial::GetActiveFieldTrialGroups() to enumerate the variation IDs for
  102. // all active FieldTrial groups. Thread safe.
  103. COMPONENT_EXPORT(VARIATIONS)
  104. VariationID GetGoogleVariationID(IDCollectionKey key,
  105. const std::string& trial_name,
  106. const std::string& group_name);
  107. // Same as GetGoogleVariationID(), but takes in a hashed |active_group| rather
  108. // than the string trial and group name.
  109. COMPONENT_EXPORT(VARIATIONS)
  110. VariationID GetGoogleVariationIDFromHashes(IDCollectionKey key,
  111. const ActiveGroupId& active_group);
  112. // Deprecated. Use base::AssociateFieldTrialParams() instead.
  113. COMPONENT_EXPORT(VARIATIONS)
  114. bool AssociateVariationParams(const std::string& trial_name,
  115. const std::string& group_name,
  116. const std::map<std::string, std::string>& params);
  117. // Deprecated. Use base::GetFieldTrialParams() instead.
  118. COMPONENT_EXPORT(VARIATIONS)
  119. bool GetVariationParams(const std::string& trial_name,
  120. std::map<std::string, std::string>* params);
  121. // Deprecated. Use base::GetFieldTrialParamsByFeature() instead.
  122. COMPONENT_EXPORT(VARIATIONS)
  123. bool GetVariationParamsByFeature(const base::Feature& feature,
  124. std::map<std::string, std::string>* params);
  125. // Deprecated. Use base::GetFieldTrialParamValue() instead.
  126. COMPONENT_EXPORT(VARIATIONS)
  127. std::string GetVariationParamValue(const std::string& trial_name,
  128. const std::string& param_name);
  129. // Deprecated. Use base::GetFieldTrialParamValueByFeature() instead.
  130. COMPONENT_EXPORT(VARIATIONS)
  131. std::string GetVariationParamValueByFeature(const base::Feature& feature,
  132. const std::string& param_name);
  133. // Deprecated. Use base::GetFieldTrialParamByFeatureAsInt() instead.
  134. COMPONENT_EXPORT(VARIATIONS)
  135. int GetVariationParamByFeatureAsInt(const base::Feature& feature,
  136. const std::string& param_name,
  137. int default_value);
  138. // Deprecated. Use base::GetFieldTrialParamByFeatureAsDouble() instead.
  139. COMPONENT_EXPORT(VARIATIONS)
  140. double GetVariationParamByFeatureAsDouble(const base::Feature& feature,
  141. const std::string& param_name,
  142. double default_value);
  143. // Deprecated. Use base::GetFieldTrialParamByFeatureAsBool() instead.
  144. COMPONENT_EXPORT(VARIATIONS)
  145. bool GetVariationParamByFeatureAsBool(const base::Feature& feature,
  146. const std::string& param_name,
  147. bool default_value);
  148. // Expose some functions for testing.
  149. namespace testing {
  150. // Clears all of the mapped associations. Deprecated, use ScopedFeatureList
  151. // instead as it does a lot of work for you automatically.
  152. COMPONENT_EXPORT(VARIATIONS) void ClearAllVariationIDs();
  153. // Clears all of the associated params. Deprecated, use ScopedFeatureList
  154. // instead as it does a lot of work for you automatically.
  155. COMPONENT_EXPORT(VARIATIONS) void ClearAllVariationParams();
  156. } // namespace testing
  157. } // namespace variations
  158. #endif // COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_