1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_
#define COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_
#include <map>
#include <memory>
#include <string>
#include <vector>
#include "components/variations/active_field_trials.h"
// This file provides various helpers that extend the functionality around
// base::FieldTrial.
//
// This includes several simple APIs to handle getting and setting additional
// data related to Chrome variations, such as parameters and Google variation
// IDs. These APIs are meant to extend the base::FieldTrial APIs to offer extra
// functionality that is not offered by the simpler base::FieldTrial APIs.
//
// The AssociateGoogleVariationID and AssociateVariationParams functions are
// generally meant to be called by the VariationsService based on server-side
// variation configs, but may also be used for client-only field trials by
// invoking them directly after appending all the groups to a FieldTrial.
//
// Experiment code can then use the getter APIs to retrieve variation parameters
// or IDs:
//
// std::map<std::string, std::string> params;
// if (GetVariationParams("trial", ¶ms)) {
// // use |params|
// }
//
// std::string value = GetVariationParamValue("trial", "param_x");
// // use |value|, which will be "" if it does not exist
//
// VariationID id = GetGoogleVariationID(GOOGLE_WEB_PROPERTIES, "trial",
// "group1");
// if (id != variations::kEmptyID) {
// // use |id|
// }
namespace base {
struct Feature;
} // namespace base
namespace variations {
typedef int VariationID;
const VariationID EMPTY_ID = 0;
// A key into the Associate/Get methods for VariationIDs. This is used to create
// separate ID associations for separate parties interested in VariationIDs.
enum IDCollectionKey {
// This collection is used by Google web properties, transmitted through the
// X-Client-Data header.
GOOGLE_WEB_PROPERTIES,
// This collection is used by Google web properties for signed in users only,
// transmitted through the X-Client-Data header.
GOOGLE_WEB_PROPERTIES_SIGNED_IN,
// This collection is used by Google web properties for IDs that trigger
// server side experimental behavior, transmitted through the
// X-Client-Data header.
GOOGLE_WEB_PROPERTIES_TRIGGER,
// This collection is used by Chrome Sync services, transmitted through the
// Chrome Sync experiment labels.
CHROME_SYNC_SERVICE,
// The total count of collections.
ID_COLLECTION_COUNT,
};
// Associate a variations::VariationID value with a FieldTrial group for
// collection |key|. If an id was previously set for |trial_name| and
// |group_name|, this does nothing. The group is denoted by |trial_name| and
// |group_name|. This must be called whenever a FieldTrial is prepared (create
// the trial and append groups) and needs to have a variations::VariationID
// associated with it so Google servers can recognize the FieldTrial.
// Thread safe.
void AssociateGoogleVariationID(IDCollectionKey key,
const std::string& trial_name,
const std::string& group_name,
VariationID id);
// As above, but overwrites any previously set id. Thread safe.
void AssociateGoogleVariationIDForce(IDCollectionKey key,
const std::string& trial_name,
const std::string& group_name,
VariationID id);
// As above, but takes an ActiveGroupId hash pair, rather than the string names.
void AssociateGoogleVariationIDForceHashes(IDCollectionKey key,
const ActiveGroupId& active_group,
VariationID id);
// Retrieve the variations::VariationID associated with a FieldTrial group for
// collection |key|. The group is denoted by |trial_name| and |group_name|.
// This will return variations::kEmptyID if there is currently no associated ID
// for the named group. This API can be nicely combined with
// FieldTrial::GetActiveFieldTrialGroups() to enumerate the variation IDs for
// all active FieldTrial groups. Thread safe.
VariationID GetGoogleVariationID(IDCollectionKey key,
const std::string& trial_name,
const std::string& group_name);
// Same as GetGoogleVariationID(), but takes in a hashed |active_group| rather
// than the string trial and group name.
VariationID GetGoogleVariationIDFromHashes(IDCollectionKey key,
const ActiveGroupId& active_group);
// Associates the specified set of key-value |params| with the variation
// specified by |trial_name| and |group_name|. Fails and returns false if the
// specified variation already has params associated with it or the field trial
// is already active (group() has been called on it). Thread safe.
bool AssociateVariationParams(const std::string& trial_name,
const std::string& group_name,
const std::map<std::string, std::string>& params);
// Retrieves the set of key-value |params| for the variation associated with
// the specified field trial, based on its selected group. If the field trial
// does not exist or its selected group does not have any parameters associated
// with it, returns false and does not modify |params|. Calling this function
// will result in the field trial being marked as active if found (i.e. group()
// will be called on it), if it wasn't already. Currently, this information is
// only available from the browser process. Thread safe.
bool GetVariationParams(const std::string& trial_name,
std::map<std::string, std::string>* params);
// Retrieves the set of key-value |params| for the variation associated with the
// specified |feature|. A feature is associated with at most one variation,
// through the variation's associated field trial, and selected group. See
// base/feature_list.h for more information on features. If the feature is not
// enabled, or if there's no associated variation params, returns false and does
// not modify |params|. Calling this function will result in the associated
// field trial being marked as active if found (i.e. group() will be called on
// it), if it wasn't already. Currently, this information is only available from
// the browser process. Thread safe.
bool GetVariationParamsByFeature(const base::Feature& feature,
std::map<std::string, std::string>* params);
// Retrieves a specific parameter value corresponding to |param_name| for the
// variation associated with the specified field trial, based on its selected
// group. If the field trial does not exist or the specified parameter does not
// exist, returns an empty string. Calling this function will result in the
// field trial being marked as active if found (i.e. group() will be called on
// it), if it wasn't already. Currently, this information is only available from
// the browser process. Thread safe.
std::string GetVariationParamValue(const std::string& trial_name,
const std::string& param_name);
// Retrieves a specific parameter value corresponding to |param_name| for the
// variation associated with the specified |feature|. A feature is associated
// with at most one variation, through the variation's associated field trial,
// and selected group. See base/feature_list.h for more information on
// features. If the feature is not enabled, or the specified parameter does not
// exist, returns an empty string. Calling this function will result in the
// associated field trial being marked as active if found (i.e. group() will be
// called on it), if it wasn't already. Currently, this information is only
// available from the browser process. Thread safe.
std::string GetVariationParamValueByFeature(const base::Feature& feature,
const std::string& param_name);
// Same as GetVariationParamValueByFeature(). On top of that, it converts the
// string value into an int using base::StringToInt() and returns it, if
// successful. Otherwise, it returns |default_value|. If the string value is not
// empty and the conversion does not succeed, it produces a warning to LOG.
int GetVariationParamByFeatureAsInt(const base::Feature& feature,
const std::string& param_name,
int default_value);
// Same as GetVariationParamValueByFeature(). On top of that, it converts the
// string value into a double using base::StringToDouble() and returns it, if
// successful. Otherwise, it returns |default_value|. If the string value is not
// empty and the conversion does not succeed, it produces a warning to LOG.
double GetVariationParamByFeatureAsDouble(const base::Feature& feature,
const std::string& param_name,
double default_value);
// Same as GetVariationParamValueByFeature(). On top of that, it converts the
// string value into a boolean and returns it, if successful. Otherwise, it
// returns |default_value|. The only string representations accepted here are
// "true" and "false". If the string value is not empty and the conversion does
// not succeed, it produces a warning to LOG.
bool GetVariationParamByFeatureAsBool(const base::Feature& feature,
const std::string& param_name,
bool default_value);
// Expose some functions for testing.
namespace testing {
// Clears all of the mapped associations. Deprecated, try to use
// VariationParamsManager instead as it does a lot of work for you
// automatically.
void ClearAllVariationIDs();
// Clears all of the associated params. Deprecated, try to use
// VariationParamsManager instead as it does a lot of work for you
// automatically.
void ClearAllVariationParams();
} // namespace testing
} // namespace variations
#endif // COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_
|
