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 5 #ifndef COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_ 6 #define COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_ 7 8 #include <map> 9 #include <string> 10 11 #include "base/metrics/field_trial.h" 12 #include "components/variations/active_field_trials.h" 13 14 // This file provides various helpers that extend the functionality around 15 // base::FieldTrial. 16 // 17 // This includes several simple APIs to handle getting and setting additional 18 // data related to Chrome variations, such as parameters and Google variation 19 // IDs. These APIs are meant to extend the base::FieldTrial APIs to offer extra 20 // functionality that is not offered by the simpler base::FieldTrial APIs. 21 // 22 // The AssociateGoogleVariationID and AssociateVariationParams functions are 23 // generally meant to be called by the VariationsService based on server-side 24 // variation configs, but may also be used for client-only field trials by 25 // invoking them directly after appending all the groups to a FieldTrial. 26 // 27 // Experiment code can then use the getter APIs to retrieve variation parameters 28 // or IDs: 29 // 30 // std::map<std::string, std::string> params; 31 // if (GetVariationParams("trial", ¶ms)) { 32 // // use |params| 33 // } 34 // 35 // std::string value = GetVariationParamValue("trial", "param_x"); 36 // // use |value|, which will be "" if it does not exist 37 // 38 // VariationID id = GetGoogleVariationID(GOOGLE_WEB_PROPERTIES, "trial", 39 // "group1"); 40 // if (id != variations::kEmptyID) { 41 // // use |id| 42 // } 43 44 namespace variations { 45 46 typedef int VariationID; 47 48 const VariationID EMPTY_ID = 0; 49 50 // A key into the Associate/Get methods for VariationIDs. This is used to create 51 // separate ID associations for separate parties interested in VariationIDs. 52 enum IDCollectionKey { 53 // This collection is used by Google web properties, transmitted through the 54 // X-Client-Data header. 55 GOOGLE_WEB_PROPERTIES, 56 // This collection is used by Google web properties for IDs that trigger 57 // server side experimental behavior, transmitted through the 58 // X-Client-Data header. 59 GOOGLE_WEB_PROPERTIES_TRIGGER, 60 // This collection is used by Google update services, transmitted through the 61 // Google Update experiment labels. 62 GOOGLE_UPDATE_SERVICE, 63 // The total count of collections. 64 ID_COLLECTION_COUNT, 65 }; 66 67 // Associate a variations::VariationID value with a FieldTrial group for 68 // collection |key|. If an id was previously set for |trial_name| and 69 // |group_name|, this does nothing. The group is denoted by |trial_name| and 70 // |group_name|. This must be called whenever a FieldTrial is prepared (create 71 // the trial and append groups) and needs to have a variations::VariationID 72 // associated with it so Google servers can recognize the FieldTrial. 73 // Thread safe. 74 void AssociateGoogleVariationID(IDCollectionKey key, 75 const std::string& trial_name, 76 const std::string& group_name, 77 VariationID id); 78 79 // As above, but overwrites any previously set id. Thread safe. 80 void AssociateGoogleVariationIDForce(IDCollectionKey key, 81 const std::string& trial_name, 82 const std::string& group_name, 83 VariationID id); 84 85 // Retrieve the variations::VariationID associated with a FieldTrial group for 86 // collection |key|. The group is denoted by |trial_name| and |group_name|. 87 // This will return variations::kEmptyID if there is currently no associated ID 88 // for the named group. This API can be nicely combined with 89 // FieldTrial::GetActiveFieldTrialGroups() to enumerate the variation IDs for 90 // all active FieldTrial groups. Thread safe. 91 VariationID GetGoogleVariationID(IDCollectionKey key, 92 const std::string& trial_name, 93 const std::string& group_name); 94 95 // Associates the specified set of key-value |params| with the variation 96 // specified by |trial_name| and |group_name|. Fails and returns false if the 97 // specified variation already has params associated with it or the field trial 98 // is already active (group() has been called on it). Thread safe. 99 bool AssociateVariationParams(const std::string& trial_name, 100 const std::string& group_name, 101 const std::map<std::string, std::string>& params); 102 103 // Retrieves the set of key-value |params| for the variation associated with 104 // the specified field trial, based on its selected group. If the field trial 105 // does not exist or its selected group does not have any parameters associated 106 // with it, returns false and does not modify |params|. Calling this function 107 // will result in the field trial being marked as active if found (i.e. group() 108 // will be called on it), if it wasn't already. Currently, this information is 109 // only available from the browser process. Thread safe. 110 bool GetVariationParams(const std::string& trial_name, 111 std::map<std::string, std::string>* params); 112 113 // Retrieves a specific parameter value corresponding to |param_name| for the 114 // variation associated with the specified field trial, based on its selected 115 // group. If the field trial does not exist or the specified parameter does not 116 // exist, returns an empty string. Calling this function will result in the 117 // field trial being marked as active if found (i.e. group() will be called on 118 // it), if it wasn't already. Currently, this information is only available from 119 // the browser process. Thread safe. 120 std::string GetVariationParamValue(const std::string& trial_name, 121 const std::string& param_name); 122 123 // Expose some functions for testing. 124 namespace testing { 125 126 // Clears all of the mapped associations. 127 void ClearAllVariationIDs(); 128 129 // Clears all of the associated params. 130 void ClearAllVariationParams(); 131 132 } // namespace testing 133 134 } // namespace variations 135 136 #endif // COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_ 137