components/variations/proto/study.proto

   1 // Copyright (c) 2012 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 syntax = "proto2";
   6
   7 option optimize_for = LITE_RUNTIME;
   8
   9 package variations;
  10
  11 // This defines the Protocol Buffer representation of a Chrome Variations study
  12 // as sent to clients of the Variations server.
  13 //
  14 // Next tag: 13
  15 message Study {
  16   // The name of the study. Should not contain spaces or special characters.
  17   // Ex: "my_study"
  18   required string name = 1;
  19
  20   // The expiry date of the study in Unix time format. (Seconds since midnight
  21   // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time
  22   //
  23   // A study that has expired will be disabled, and users will be assigned
  24   // groups based on the default_experiment_name. This will take precedence over
  25   // a corresponding hardcoded field trial in the client.
  26   //
  27   // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
  28   optional int64 expiry_date = 3;
  29
  30   // Consistency setting for a study.
  31   enum Consistency {
  32     SESSION = 0;  // Can't change within a session.
  33     PERMANENT = 1;  // Can't change for a given user.
  34   }
  35
  36   // Consistency setting for this study. Optional - defaults to SESSION.
  37   // Ex: PERMANENT
  38   optional Consistency consistency = 7 [default = SESSION];
  39
  40   // Name of the experiment that gets the default experience. This experiment
  41   // must be included in the list below.
  42   // Ex: "default"
  43   optional string default_experiment_name = 8;
  44
  45   // An experiment within the study.
  46   //
  47   // Next tag: 11
  48   message Experiment {
  49     // A named parameter value for this experiment.
  50     //
  51     // Next tag: 3
  52     message Param {
  53       // The name of the parameter.
  54       optional string name = 1;
  55
  56       // The value of the parameter.
  57       optional string value = 2;
  58     }
  59
  60     // The name of the experiment within the study.
  61     // Ex: "bucketA"
  62     required string name = 1;
  63
  64     // The cut of the total probability taken for this experiment (the x in
  65     // x / N, where N is the sum of all x’s).  Ex: "50"
  66     required uint32 probability_weight = 2;
  67
  68     // Optional id used to uniquely identify this experiment for Google web
  69     // properties.
  70     optional uint64 google_web_experiment_id = 3;
  71
  72     // Optional id used to allow this experiment to trigger experimental
  73     // behavior on Google web properties.
  74     optional uint64 google_web_trigger_experiment_id = 8;
  75
  76     // Optional id used to uniquely identify this experiment for Google Update.
  77     optional uint64 google_update_experiment_id = 4;
  78
  79     // Optional id used to uniquely identify this experiment for Chrome Sync.
  80     optional uint64 chrome_sync_experiment_id = 10;
  81
  82     // Optional name of a Chrome flag that, when present, causes this experiment
  83     // to be forced. If the forcing_flag field is set, users will not be
  84     // assigned to this experiment unless that flag is present in Chrome's
  85     // command line.
  86     optional string forcing_flag = 5;
  87
  88     // Parameter values for this experiment.
  89     repeated Param param = 6;
  90
  91     enum Type {
  92       // Regular experiment group. This is the default value and can be omitted.
  93       NORMAL = 0;
  94
  95       // Changes to this experiment group are ignored for the purposes of
  96       // kill-switch triggering. Included to allow the flexibility to not
  97       // trigger this logic for specific cases (e.g. a group rename without
  98       // any functionality changes).
  99       IGNORE_CHANGE = 1;
 100
 101       // This is a kill-switch group that should be killed at "best effort"
 102       // priority, e.g. with a hot dog menu badge. The experiment must have a
 103       // probability_weight of 0.
 104       KILL_BEST_EFFORT = 2;
 105
 106       // This is a kill-switch group that should be killed with "critical"
 107       // priority. Depending on platform this may result in showing a
 108       // non-dismissible restart prompt with a timer. This should only be used
 109       // in very serious emergency circumstances. The experiment must have a
 110       // probability_weight of 0.
 111       KILL_CRITICAL = 3;
 112     }
 113     optional Type type = 7 [default = NORMAL];
 114
 115     // A UI string to override, and the new value to use.
 116     message OverrideUIString {
 117       // The first 32 bits of the MD5 hash digest of the resource name to
 118       // override.
 119       // e.g. Hash("IDS_BOOKMARK_BAR_UNDO")
 120       optional fixed32 name_hash = 1;
 121
 122       // The new value of the string being overridden.
 123       // e.g. "Undo"
 124       optional string value = 2;
 125     }
 126     repeated OverrideUIString override_ui_string = 9;
 127   }
 128
 129   // List of experiments in this study. This list should include the default /
 130   // control experiment.
 131   //
 132   // For example, to specify that 99% of users get the default behavior, while
 133   // 0.5% of users get experience "A" and 0.5% of users get experience "B",
 134   // specify the values below.
 135   // Ex: { "default": 990, "A": 5, "B": 5 }
 136   repeated Experiment experiment = 9;
 137
 138   // Possible Chrome release channels.
 139   // See: http://dev.chromium.org/getting-involved/dev-channel
 140   enum Channel {
 141     // UNKNOWN value is defined here for the benefit of code using this enum
 142     // type, but is not actually meant to be encoded in the protobuf.
 143     UNKNOWN = -1;
 144     CANARY = 0;
 145     DEV = 1;
 146     BETA = 2;
 147     STABLE = 3;
 148   }
 149
 150   // Possible Chrome operating system platforms.
 151   enum Platform {
 152     PLATFORM_WINDOWS  = 0;
 153     PLATFORM_MAC      = 1;
 154     PLATFORM_LINUX    = 2;
 155     PLATFORM_CHROMEOS = 3;
 156     PLATFORM_ANDROID  = 4;
 157     PLATFORM_IOS      = 5;
 158   }
 159
 160   // Possible form factors Chrome is running on.
 161   enum FormFactor {
 162     DESKTOP = 0;
 163     PHONE   = 1;
 164     TABLET  = 2;
 165   }
 166
 167   // Filtering criteria specifying whether this study is applicable to a given
 168   // Chrome instance.
 169   //
 170   // Next tag: 12
 171   message Filter {
 172     // The start date of the study in Unix time format. (Seconds since midnight
 173     // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time
 174     // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
 175     optional int64 start_date = 1;
 176
 177     // The minimum Chrome version for this study, allowing a trailing '*'
 178     // character for pattern matching. Inclusive. (To check for a match, iterate
 179     // over each component checking >= until a * or end of string is reached.)
 180     // Optional - if not specified, there is no minimum version.
 181     // Ex: "17.0.963.46", "17.0.963.*", "17.*"
 182     optional string min_version = 2;
 183
 184     // The maximum Chrome version for this study; same formatting as
 185     // |min_version| above. Inclusive. (To check for a match, iterate over each
 186     // component checking <= until a * or end of string is reached.)
 187     // Optional - if not specified, there is no maximum version.
 188     // Ex: "19.*"
 189     optional string max_version = 3;
 190
 191     // List of channels that will receive this study. If omitted, the study
 192     // applies to all channels.
 193     // Ex: [BETA, STABLE]
 194     repeated Channel channel = 4;
 195
 196     // List of platforms that will receive this study. If omitted, the study
 197     // applies to all platforms.
 198     // Ex: [PLATFORM_WINDOWS, PLATFORM_MAC]
 199     repeated Platform platform = 5;
 200
 201     // List of locales that will receive this study. If omitted, the study
 202     // applies to all locales.
 203     // Ex: ["en-US", "en-CA"]
 204     repeated string locale = 6;
 205
 206     // List of form factors that will receive this study. If omitted, the study
 207     // applies to all form factors.
 208     // Ex: [PHONE, TABLET]
 209     repeated FormFactor form_factor = 7;
 210
 211     // List of ChromeOS hardware classes that will receive this study. Each
 212     // entry is treated as a substring of the actual device hardware_class,
 213     // so "FOO" will match the client's hardware class "Device FOOBAR". If
 214     // omitted, the study applies to all hardware classes unless
 215     // |exclude_hardware_class| is specified. Mutually exclusive with
 216     // |exclude_hardware_class|.
 217     repeated string hardware_class = 8;
 218
 219     // List of ChromeOS hardware classes that will be excluded in this
 220     // study. Each entry is treated as a substring of the actual device
 221     // hardware_class, so "FOO" will match the client's hardware class
 222     // "Device FOOBAR". If omitted, the study applies to all hardware classes
 223     // unless |hardware_class| is specified. Mutually exclusive with
 224     // |hardware_class|.
 225     repeated string exclude_hardware_class = 9;
 226
 227     // List of lowercase ISO 3166-1 alpha-2 country codes that will receive this
 228     // study. If omitted, the study applies to all countries unless
 229     // |exclude_country| is specified. Mutually exclusive with
 230     // |exclude_country|.
 231     // Ex: ["in", "us"]
 232     repeated string country = 10;
 233
 234     // List of lowercase ISO 3166-1 alpha-2 country codes that will be excluded
 235     // in this study. If omitted, the study applies to all countries unless
 236     // |country| is specified. Mutually exclusive with |country|.
 237     // Ex: ["in", "us"]
 238     repeated string exclude_country = 11;
 239   }
 240
 241   // Filtering criteria for this study. A study that is filtered out for a given
 242   // client is equivalent to that study not being sent at all.
 243   optional Filter filter = 10;
 244
 245   // Randomization seed to be used when |consistency| is set to PERMANENT. If
 246   // not specified, randomization will be done using the trial name.
 247   optional uint32 randomization_seed = 11;
 248
 249   // Specifies whether the study starts as active initially, or whether it
 250   // requires the client to query its state before it is marked as active.
 251   enum ActivationType {
 252     // The study will be activated when its state is queried by the client.
 253     // This is recommended for most studies that include client code.
 254     ACTIVATION_EXPLICIT  = 0;
 255     // The study will be automatically activated when it is created. This
 256     // is recommended for studies that do not have any client logic.
 257     ACTIVATION_AUTO      = 1;
 258   }
 259
 260   // Activation type for this study. Defaults to ACTIVATION_EXPLICIT if omitted.
 261   optional ActivationType activation_type = 12;
 262 }