components/variations/variations_associated_data.h

   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", &params)) {
  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   // This collection is used by Chrome Sync services, transmitted through the
  64   // Chrome Sync experiment labels.
  65   CHROME_SYNC_SERVICE,
  66   // The total count of collections.
  67   ID_COLLECTION_COUNT,
  68 };
  69
  70 // Associate a variations::VariationID value with a FieldTrial group for
  71 // collection |key|. If an id was previously set for |trial_name| and
  72 // |group_name|, this does nothing. The group is denoted by |trial_name| and
  73 // |group_name|. This must be called whenever a FieldTrial is prepared (create
  74 // the trial and append groups) and needs to have a variations::VariationID
  75 // associated with it so Google servers can recognize the FieldTrial.
  76 // Thread safe.
  77 void AssociateGoogleVariationID(IDCollectionKey key,
  78                                 const std::string& trial_name,
  79                                 const std::string& group_name,
  80                                 VariationID id);
  81
  82 // As above, but overwrites any previously set id. Thread safe.
  83 void AssociateGoogleVariationIDForce(IDCollectionKey key,
  84                                      const std::string& trial_name,
  85                                      const std::string& group_name,
  86                                      VariationID id);
  87
  88 // As above, but takes an ActiveGroupId hash pair, rather than the string names.
  89 void AssociateGoogleVariationIDForceHashes(IDCollectionKey key,
  90                                            const ActiveGroupId& active_group,
  91                                            VariationID id);
  92
  93 // Retrieve the variations::VariationID associated with a FieldTrial group for
  94 // collection |key|. The group is denoted by |trial_name| and |group_name|.
  95 // This will return variations::kEmptyID if there is currently no associated ID
  96 // for the named group. This API can be nicely combined with
  97 // FieldTrial::GetActiveFieldTrialGroups() to enumerate the variation IDs for
  98 // all active FieldTrial groups. Thread safe.
  99 VariationID GetGoogleVariationID(IDCollectionKey key,
 100                                  const std::string& trial_name,
 101                                  const std::string& group_name);
 102
 103 // Same as GetGoogleVariationID(), but takes in a hashed |active_group| rather
 104 // than the string trial and group name.
 105 VariationID GetGoogleVariationIDFromHashes(IDCollectionKey key,
 106                                            const ActiveGroupId& active_group);
 107
 108 // Associates the specified set of key-value |params| with the variation
 109 // specified by |trial_name| and |group_name|. Fails and returns false if the
 110 // specified variation already has params associated with it or the field trial
 111 // is already active (group() has been called on it). Thread safe.
 112 bool AssociateVariationParams(const std::string& trial_name,
 113                               const std::string& group_name,
 114                               const std::map<std::string, std::string>& params);
 115
 116 // Retrieves the set of key-value |params| for the variation associated with
 117 // the specified field trial, based on its selected group. If the field trial
 118 // does not exist or its selected group does not have any parameters associated
 119 // with it, returns false and does not modify |params|. Calling this function
 120 // will result in the field trial being marked as active if found (i.e. group()
 121 // will be called on it), if it wasn't already. Currently, this information is
 122 // only available from the browser process. Thread safe.
 123 bool GetVariationParams(const std::string& trial_name,
 124                         std::map<std::string, std::string>* params);
 125
 126 // Retrieves a specific parameter value corresponding to |param_name| for the
 127 // variation associated with the specified field trial, based on its selected
 128 // group. If the field trial does not exist or the specified parameter does not
 129 // exist, returns an empty string. Calling this function will result in the
 130 // field trial being marked as active if found (i.e. group() will be called on
 131 // it), if it wasn't already. Currently, this information is only available from
 132 // the browser process. Thread safe.
 133 std::string GetVariationParamValue(const std::string& trial_name,
 134                                    const std::string& param_name);
 135
 136 // Expose some functions for testing.
 137 namespace testing {
 138
 139 // Clears all of the mapped associations.
 140 void ClearAllVariationIDs();
 141
 142 // Clears all of the associated params.
 143 void ClearAllVariationParams();
 144
 145 }  // namespace testing
 146
 147 }  // namespace variations
 148
 149 #endif  // COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_