123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185 |
- // 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 "base/metrics/field_trial.h"
- #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_ANY_CONTEXT, "trial", "group1");
- // if (id != variations::EMPTY_ID) {
- // // use |id|
- // }
- 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 {
- // The IDs in this collection are used by Google web properties and are
- // transmitted via the X-Client-Data header. These IDs are transmitted in
- // first- and third-party contexts.
- GOOGLE_WEB_PROPERTIES_ANY_CONTEXT,
- // The IDs in this collection are used by Google web properties and are
- // transmitted via the X-Client-Data header. When kRestrictGoogleWebVisibility
- // is enabled, these IDs are transmitted in only first-party contexts;
- // otherwise, these IDs are transmitted in first- and third-party contexts.
- GOOGLE_WEB_PROPERTIES_FIRST_PARTY,
- // 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,
- // The IDs in this collection are used by Google web properties to trigger
- // server-side experimental behavior and are transmitted via the X-Client-Data
- // header. These IDs are transmitted in first- and third-party contexts.
- GOOGLE_WEB_PROPERTIES_TRIGGER_ANY_CONTEXT,
- // The IDs in this collection are used by Google web properties to trigger
- // server-side experimental behavior and are transmitted via the X-Client-Data
- // header. When kRestrictGoogleWebVisibility is enabled, these IDs are
- // transmitted in only first-party contexts; otherwise, these IDs are
- // transmitted in first- and third-party contexts.
- GOOGLE_WEB_PROPERTIES_TRIGGER_FIRST_PARTY,
- // This collection is used by the Google App and is passed at the time
- // the cross-app communication is triggered.
- GOOGLE_APP,
- // 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.
- COMPONENT_EXPORT(VARIATIONS)
- 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.
- COMPONENT_EXPORT(VARIATIONS)
- 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.
- COMPONENT_EXPORT(VARIATIONS)
- 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::EMPTY_ID 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.
- COMPONENT_EXPORT(VARIATIONS)
- 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.
- COMPONENT_EXPORT(VARIATIONS)
- VariationID GetGoogleVariationIDFromHashes(IDCollectionKey key,
- const ActiveGroupId& active_group);
- // Deprecated. Use base::AssociateFieldTrialParams() instead.
- COMPONENT_EXPORT(VARIATIONS)
- bool AssociateVariationParams(const std::string& trial_name,
- const std::string& group_name,
- const std::map<std::string, std::string>& params);
- // Deprecated. Use base::GetFieldTrialParams() instead.
- COMPONENT_EXPORT(VARIATIONS)
- bool GetVariationParams(const std::string& trial_name,
- std::map<std::string, std::string>* params);
- // Deprecated. Use base::GetFieldTrialParamsByFeature() instead.
- COMPONENT_EXPORT(VARIATIONS)
- bool GetVariationParamsByFeature(const base::Feature& feature,
- std::map<std::string, std::string>* params);
- // Deprecated. Use base::GetFieldTrialParamValue() instead.
- COMPONENT_EXPORT(VARIATIONS)
- std::string GetVariationParamValue(const std::string& trial_name,
- const std::string& param_name);
- // Deprecated. Use base::GetFieldTrialParamValueByFeature() instead.
- COMPONENT_EXPORT(VARIATIONS)
- std::string GetVariationParamValueByFeature(const base::Feature& feature,
- const std::string& param_name);
- // Deprecated. Use base::GetFieldTrialParamByFeatureAsInt() instead.
- COMPONENT_EXPORT(VARIATIONS)
- int GetVariationParamByFeatureAsInt(const base::Feature& feature,
- const std::string& param_name,
- int default_value);
- // Deprecated. Use base::GetFieldTrialParamByFeatureAsDouble() instead.
- COMPONENT_EXPORT(VARIATIONS)
- double GetVariationParamByFeatureAsDouble(const base::Feature& feature,
- const std::string& param_name,
- double default_value);
- // Deprecated. Use base::GetFieldTrialParamByFeatureAsBool() instead.
- COMPONENT_EXPORT(VARIATIONS)
- 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, use ScopedFeatureList
- // instead as it does a lot of work for you automatically.
- COMPONENT_EXPORT(VARIATIONS) void ClearAllVariationIDs();
- // Clears all of the associated params. Deprecated, use ScopedFeatureList
- // instead as it does a lot of work for you automatically.
- COMPONENT_EXPORT(VARIATIONS) void ClearAllVariationParams();
- } // namespace testing
- } // namespace variations
- #endif // COMPONENTS_VARIATIONS_VARIATIONS_ASSOCIATED_DATA_H_
|