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 5syntax = "proto2"; 6 7option optimize_for = LITE_RUNTIME; 8 9package 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 15message 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 // DEPRECATED: Prefer end_date instead. 21 // The expiry date of the study in Unix time format. (Seconds since midnight 22 // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time 23 // 24 // A study that has expired will be disabled, and users will be assigned 25 // groups based on the default_experiment_name. This will take precedence over 26 // a corresponding hardcoded field trial in the client. 27 // 28 // Ex: 1330893974 (corresponds to 2012-03-04 20:46:14Z) 29 optional int64 expiry_date = 3; 30 31 // Consistency setting for a study. 32 enum Consistency { 33 SESSION = 0; // Can't change within a session. 34 PERMANENT = 1; // Can't change for a given user. 35 } 36 37 // Consistency setting for this study. Optional - defaults to SESSION. 38 // Ex: PERMANENT 39 optional Consistency consistency = 7 [default = SESSION]; 40 41 // Name of the experiment that gets the default experience. This experiment 42 // must be included in the list below. If not specified, a generic default 43 // experiment name is used. 44 // Ex: "default" 45 optional string default_experiment_name = 8; 46 47 // An experiment within the study. 48 // 49 // Next tag: 14 50 message Experiment { 51 // A named parameter value for this experiment. 52 // 53 // Next tag: 3 54 message Param { 55 // The name of the parameter. 56 optional string name = 1; 57 58 // The value of the parameter. 59 optional string value = 2; 60 } 61 62 // The name of the experiment within the study. 63 // Ex: "bucketA" 64 required string name = 1; 65 66 // The cut of the total probability taken for this experiment (the x in 67 // x / N, where N is the sum of all x’s). Ex: "50" 68 required uint32 probability_weight = 2; 69 70 // Optional id used to uniquely identify this experiment for Google web 71 // properties. 72 optional uint64 google_web_experiment_id = 3; 73 74 // Optional id used to allow this experiment to trigger experimental 75 // behavior on Google web properties. 76 optional uint64 google_web_trigger_experiment_id = 8; 77 78 // Optional id used to uniquely identify this experiment for Chrome Sync. 79 optional uint64 chrome_sync_experiment_id = 10; 80 81 // Specifies the feature association parameters for this experiment group. 82 // 83 // Next tag: 5 84 message FeatureAssociation { 85 // Optional list of features to enable when this experiment is selected. 86 // Command-line overrides take precedence over this setting. No feature 87 // listed here should exist in the |disable_feature| list. 88 repeated string enable_feature = 1; 89 90 // Optional list of features to disable when this experiment is selected. 91 // Command-line overrides take precedence over this setting. No feature 92 // listed here should exist in the |enable_feature| list. 93 repeated string disable_feature = 2; 94 95 // Similar to |forcing_flag|, this is an optional name of a feature which 96 // will cause this experiment to be activated, if that feature is enabled 97 // from the command-line. Experiment with this set are not eligible for 98 // selection via a random dice roll. 99 // Mutually exclusive with |forcing_flag|, |forcing_feature_off| or 100 // having a non-zero |probability_weight|. 101 optional string forcing_feature_on = 3; 102 103 // Similar to |forcing_flag|, this is an optional name of a feature which 104 // will cause this experiment to be activated, if that feature is disabled 105 // from the command-line. Experiment with this set are not eligible for 106 // selection via a random dice roll. 107 // Mutually exclusive with |forcing_flag|, |forcing_feature_on| or having 108 // a non-zero |probability_weight|. 109 optional string forcing_feature_off = 4; 110 } 111 optional FeatureAssociation feature_association = 12; 112 113 // Optional name of a Chrome flag that, when present, causes this experiment 114 // to be forced. If the forcing_flag field is set, users will not be 115 // assigned to this experiment unless that flag is present in Chrome's 116 // command line. 117 // Mutually exclusive with |forcing_feature_on|, |forcing_feature_off| or 118 // having a non-zero |probability_weight|. 119 optional string forcing_flag = 5; 120 121 // Parameter values for this experiment. 122 repeated Param param = 6; 123 124 enum Type { 125 // Regular experiment group. This is the default value and can be omitted. 126 NORMAL = 0; 127 128 // Changes to this experiment group are ignored for the purposes of 129 // kill-switch triggering. Included to allow the flexibility to not 130 // trigger this logic for specific cases (e.g. a group rename without 131 // any functionality changes). 132 IGNORE_CHANGE = 1; 133 134 // This is a kill-switch group that should be killed at "best effort" 135 // priority, e.g. with a hot dog menu badge. The experiment must have a 136 // probability_weight of 0. 137 KILL_BEST_EFFORT = 2; 138 139 // This is a kill-switch group that should be killed with "critical" 140 // priority. Depending on platform this may result in showing a 141 // non-dismissible restart prompt with a timer. This should only be used 142 // in very serious emergency circumstances. The experiment must have a 143 // probability_weight of 0. 144 KILL_CRITICAL = 3; 145 } 146 optional Type type = 7 [default = NORMAL]; 147 148 // A UI string to override, and the new value to use. 149 message OverrideUIString { 150 // The first 32 bits of the MD5 hash digest of the resource name to 151 // override. 152 // e.g. Hash("IDS_BOOKMARK_BAR_UNDO") 153 optional fixed32 name_hash = 1; 154 155 // The new value of the string being overridden. 156 // e.g. "Undo" 157 optional string value = 2; 158 } 159 repeated OverrideUIString override_ui_string = 9; 160 } 161 162 // List of experiments in this study. This list should include the default / 163 // control experiment. 164 // 165 // For example, to specify that 99% of users get the default behavior, while 166 // 0.5% of users get experience "A" and 0.5% of users get experience "B", 167 // specify the values below. 168 // Ex: { "default": 990, "A": 5, "B": 5 } 169 repeated Experiment experiment = 9; 170 171 // Possible Chrome release channels. 172 // See: http://dev.chromium.org/getting-involved/dev-channel 173 enum Channel { 174 // UNKNOWN value is defined here for the benefit of code using this enum 175 // type, but is not actually meant to be encoded in the protobuf. 176 UNKNOWN = -1; 177 CANARY = 0; 178 DEV = 1; 179 BETA = 2; 180 STABLE = 3; 181 } 182 183 // Possible Chrome operating system platforms. 184 // These names must match those in tools/variations/fieldtrial_to_struct.py. 185 enum Platform { 186 PLATFORM_WINDOWS = 0; 187 PLATFORM_MAC = 1; 188 PLATFORM_LINUX = 2; 189 PLATFORM_CHROMEOS = 3; 190 PLATFORM_ANDROID = 4; 191 PLATFORM_IOS = 5; 192 PLATFORM_ANDROID_WEBVIEW = 6; 193 PLATFORM_FUCHSIA = 7; 194 PLATFORM_ANDROID_WEBLAYER = 8; 195 } 196 197 // Possible form factors Chrome is running on. 198 enum FormFactor { 199 // Chrome Desktop on Windows, Mac, Linux, or Chrome OS. 200 DESKTOP = 0; 201 // Phone-based mobile Chrome, e.g. an Android phone or iPhone. 202 PHONE = 1; 203 // Tablet-based mobile Chrome, e.g. an Android tablet or iPad. 204 TABLET = 2; 205 // Chrome OS running in single-app Kiosk mode. 206 KIOSK = 3; 207 } 208 209 // Enum to pass as optional bool. 210 enum OptionalBool { 211 // Neither True nor False. (For cases like missing / unset / default etc.) 212 OPTIONAL_BOOL_MISSING = 0; 213 // Explicit True. 214 OPTIONAL_BOOL_TRUE = 1; 215 // Explicit False. 216 OPTIONAL_BOOL_FALSE = 2; 217 } 218 219 // Possible states of the severity filter. 220 enum PolicyRestriction { 221 // No restriction configs apply to clients that do not have a 222 // "ChromeVariations" policy set or if it is set to the variations enabled 223 // value. 224 NONE = 0; 225 // Critical studies apply to both clients that have all variations enabled 226 // or if the "ChromeVariations" policy is set to only allow critical 227 // variations. 228 CRITICAL = 1; 229 // Critical-only studies apply *only* to clients that have the 230 // "ChromeVariations" policy set to only allow critical variations. 231 CRITICAL_ONLY = 2; 232 } 233 234 // Filtering criteria specifying whether this study is applicable to a given 235 // Chrome instance. 236 // 237 // Next tag: 20 238 message Filter { 239 // The start date of the study in Unix time format. (Seconds since midnight 240 // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time 241 // Ex: 1330893974 (corresponds to 2012-03-04 20:46:14Z) 242 optional int64 start_date = 1; 243 244 // The end date of the study in Unix time format. (Seconds since midnight 245 // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time 246 // Ex: 1330893974 (corresponds to 2012-03-04 20:46:14Z) 247 // Mutually exclusive with expiry_date. The difference between end_date and 248 // expiry_date is that, when end_date is past, the field trial will not be 249 // created. When expiry_date is past, the trial is still created, but will 250 // be disabled, causing it to select its default group. 251 optional int64 end_date = 13; 252 253 // The minimum Chrome version for this study, allowing a trailing '*' 254 // character for pattern matching. Inclusive. (To check for a match, iterate 255 // over each component checking >= until a * or end of string is reached.) 256 // Optional - if not specified, there is no minimum version. 257 // Ex: "17.0.963.46", "17.0.963.*", "17.*" 258 optional string min_version = 2; 259 260 // The maximum Chrome version for this study; same formatting as 261 // |min_version| above. Inclusive. (To check for a match, iterate over each 262 // component checking <= until a * or end of string is reached.) 263 // Optional - if not specified, there is no maximum version. 264 // Ex: "19.*" 265 optional string max_version = 3; 266 267 // The minimum OS version for this study, allowing a trailing '*' character 268 // for pattern matching. Inclusive. (To check for a match, iterate over each 269 // component checking >= until a * or end of string is reached.) OS versions 270 // are sanitized into a list of digits separated by dots like so: 271 // Windows: "6.2.7601 SP1" --> "6.2.7601.1" 272 // Mac OS X: "10.11.2" --> "10.11.2" 273 // Linux: "4.13.0-27-generic" --> "4.13.0" 274 // Optional - if not specified, there is no minimum version. 275 optional string min_os_version = 16; 276 277 // The maximum OS version for this study, allowing a trailing '*' character 278 // for pattern matching. Inclusive. (To check for a match, iterate over each 279 // component checking <= until a * or end of string is reached.) 280 // Optional - if not specified, there is no minimum version. 281 // Ex: See |min_os_version| for details. 282 optional string max_os_version = 17; 283 284 // List of channels that will receive this study. If omitted, the study 285 // applies to all channels. 286 // Ex: [BETA, STABLE] 287 repeated Channel channel = 4; 288 289 // List of platforms that will receive this study. If omitted, the study 290 // applies to all platforms. 291 // Ex: [PLATFORM_WINDOWS, PLATFORM_MAC] 292 repeated Platform platform = 5; 293 294 // List of locales that will receive this study. If omitted, the study 295 // applies to all locales, unless |exclude_locale| is specified. Mutually 296 // exclusive with |exclude_locale|. 297 // Ex: ["en-US", "en-CA"] 298 repeated string locale = 6; 299 300 // List of locales that will be excluded from this study. If omitted, the 301 // study applies to all locales unless |locale| is specified. Mutually 302 // exclusive with |locale|. 303 // Ex: ["en-US", "en-CA"] 304 repeated string exclude_locale = 12; 305 306 // List of form factors that will receive this study. If omitted, the study 307 // applies to all form factors, unless |exclude_form_factor| is specified. 308 // Mutually exclusive with |exclude_form_factor|. 309 // Ex: [PHONE, TABLET] 310 repeated FormFactor form_factor = 7; 311 312 // List of form factors that will be excluded from this study. If omitted, 313 // the study applies to all form factors unless |form_factor| is specified. 314 // Mutually exclusive with |form_factor|. 315 // Takes the same range of values as form_factor, e.g. [PHONE, TABLET]. 316 repeated FormFactor exclude_form_factor = 14; 317 318 // List of hardware classes that will receive this study. 319 // This supports Chrome OS and as of M77, Android. 320 // 321 // Starting with Chrome M67, this does a case insensitive match on the same 322 // hardware class field that is reported to UMA in the SystemProfileProto's 323 // |hardware.hardware_class| field. 324 // 325 // Older versions did a case sensitive substring comparison, which was 326 // problematic for short hardware classes like "eve" that existed as 327 // substrings of other longer ones. 328 // 329 // If omitted, the study applies to all hardware classes unless 330 // |exclude_hardware_class| is specified. Mutually exclusive with 331 // |exclude_hardware_class|. 332 // Ex: ["veyron_minnie", "daisy"] 333 repeated string hardware_class = 8; 334 335 // List of hardware classes that will be excluded in this study. 336 // This supports Chrome OS and as of M77, Android. 337 // 338 // Starting with Chrome M67, this does a case insensitive match on the same 339 // hardware class field that is reported to UMA in the SystemProfileProto's 340 // |hardware.hardware_class| field. 341 // 342 // Older versions did a case sensitive substring comparison, which was 343 // problematic for short hardware classes like "eve" that existed as 344 // substrings of other longer ones. 345 // 346 // If omitted, the study applies to all hardware classes unless 347 // |hardware_class| is specified. Mutually exclusive with |hardware_class|. 348 // Ex: ["veyron_minnie", "daisy"] 349 repeated string exclude_hardware_class = 9; 350 351 // List of lowercase ISO 3166-1 alpha-2 country codes that will receive this 352 // study. If omitted, the study applies to all countries unless 353 // |exclude_country| is specified. Mutually exclusive with 354 // |exclude_country|. 355 // Ex: ["in", "us"] 356 repeated string country = 10; 357 358 // List of lowercase ISO 3166-1 alpha-2 country codes that will be excluded 359 // from this study. If omitted, the study applies to all countries unless 360 // |country| is specified. Mutually exclusive with |country|. 361 // Ex: ["in", "us"] 362 repeated string exclude_country = 11; 363 364 // Specifies whether the config should apply to low-end devices only. This 365 // is currently only supported on Android. 366 optional bool is_low_end_device = 15; 367 368 // Specifies whether the config should apply to enterprise or non-enterprise 369 // only. If omitted, the config applies to both groups. 370 // - On windows and mac, machines on a domain network are considered 371 // enterprise. 372 // - On chromeOS, registered mode determines enterprise status. 373 // - Android, iOS, and linux consider all clients as non-enterprise. 374 optional bool is_enterprise = 18; 375 376 // Specifies the restrictions applied by the "ChromeVariations" policy to 377 // the study. See the definition of the PolicyRestriction enum for details. 378 optional PolicyRestriction policy_restriction = 19 [default = NONE]; 379 } 380 381 // Filtering criteria for this study. A study that is filtered out for a given 382 // client is equivalent to that study not being sent at all. 383 optional Filter filter = 10; 384 385 // Randomization seed to be used when |consistency| is set to PERMANENT. If 386 // not specified, randomization will be done using the trial name. 387 optional uint32 randomization_seed = 11; 388 389 // Specifies whether the study starts as active initially, or whether it 390 // requires the client to query its state before it is marked as active. 391 enum ActivationType { 392 // The study will be activated when its state is queried by the client. 393 // This is recommended for most studies that include client code. 394 ACTIVATE_ON_QUERY = 0; 395 // The study will be automatically activated when it is created. This 396 // is recommended for studies that do not have any client logic. 397 ACTIVATE_ON_STARTUP = 1; 398 } 399 400 // Activation type for this study. Defaults to ACTIVATION_EXPLICIT if omitted. 401 optional ActivationType activation_type = 12; 402} 403