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 chrome_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, which will take precedence over
  24   // a corresponding hardcoded field trial in the client.
  25   //
  26   // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
  27   optional int64 expiry_date = 3;
  28
  29   // Consistency setting for a study.
  30   enum Consistency {
  31     SESSION = 0;  // Can't change within a session.
  32     PERMANENT = 1;  // Can't change for a given user.
  33   }
  34
  35   // Consistency setting for this study. Optional - defaults to SESSION.
  36   // Ex: PERMANENT
  37   optional Consistency consistency = 7 [default = SESSION];
  38
  39   // Name of the experiment that gets the default experience. This experiment
  40   // must be included in the list below.
  41   // Ex: "default"
  42   optional string default_experiment_name = 8;
  43
  44   // An experiment within the study.
  45   //
  46   // Next tag: 7
  47   message Experiment {
  48     // A named parameter value for this experiment.
  49     //
  50     // Next tag: 3
  51     message Param {
  52       // The name of the parameter.
  53       optional string name = 1;
  54
  55       // The value of the parameter.
  56       optional string value = 2;
  57     }
  58
  59     // The name of the experiment within the study.
  60     // Ex: "bucketA"
  61     required string name = 1;
  62
  63     // The cut of the total probability taken for this experiment (the x in
  64     // x / N, where N is the sum of all x’s).  Ex: "50"
  65     required uint32 probability_weight = 2;
  66
  67     // Optional id used to uniquely identify this experiment for Google web
  68     // properties.
  69     optional uint64 google_web_experiment_id = 3;
  70
  71     // Optional id used to uniquely identify this experiment for Google Update.
  72     optional uint64 google_update_experiment_id = 4;
  73
  74     // Optional name of a Chrome flag that, when present, causes this experiment
  75     // to be forced. If the forcing_flag field is set, users will not be
  76     // assigned to this experiment unless that flag is present in Chrome's
  77     // command line.
  78     optional string forcing_flag = 5;
  79
  80     // Parameter values for this experiment.
  81     repeated Param param = 6;
  82   }
  83
  84   // List of experiments in this study. This list should include the default /
  85   // control experiment.
  86   //
  87   // For example, to specify that 99% of users get the default behavior, while
  88   // 0.5% of users get experience "A" and 0.5% of users get experience "B",
  89   // specify the values below.
  90   // Ex: { "default": 990, "A": 5, "B": 5 }
  91   repeated Experiment experiment = 9;
  92
  93   // Possible Chrome release channels.
  94   // See: http://dev.chromium.org/getting-involved/dev-channel
  95   enum Channel {
  96     // UNKNOWN value is defined here for the benefit of code using this enum
  97     // type, but is not actually meant to be encoded in the protobuf.
  98     UNKNOWN = -1;
  99     CANARY = 0;
 100     DEV = 1;
 101     BETA = 2;
 102     STABLE = 3;
 103   }
 104
 105   // Possible Chrome operating system platforms.
 106   enum Platform {
 107     PLATFORM_WINDOWS  = 0;
 108     PLATFORM_MAC      = 1;
 109     PLATFORM_LINUX    = 2;
 110     PLATFORM_CHROMEOS = 3;
 111     PLATFORM_ANDROID  = 4;
 112     PLATFORM_IOS      = 5;
 113   }
 114
 115   // Possible form factors Chrome is running on.
 116   enum FormFactor {
 117     DESKTOP = 0;
 118     PHONE   = 1;
 119     TABLET  = 2;
 120   }
 121
 122   // Filtering criteria specifying whether this study is applicable to a given
 123   // Chrome instance.
 124   //
 125   // Next tag: 8
 126   message Filter {
 127     // The start date of the study in Unix time format. (Seconds since midnight
 128     // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time
 129     // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
 130     optional int64 start_date = 1;
 131
 132     // The minimum Chrome version for this study, allowing a trailing '*'
 133     // character for pattern matching. Inclusive. (To check for a match, iterate
 134     // over each component checking >= until a * or end of string is reached.)
 135     // Optional - if not specified, there is no minimum version.
 136     // Ex: "17.0.963.46", "17.0.963.*", "17.*"
 137     optional string min_version = 2;
 138
 139     // The maximum Chrome version for this study; same formatting as
 140     // |min_version| above. Inclusive. (To check for a match, iterate over each
 141     // component checking <= until a * or end of string is reached.)
 142     // Optional - if not specified, there is no maximum version.
 143     // Ex: "19.*"
 144     optional string max_version = 3;
 145
 146     // List of channels that will receive this study. If omitted, the study
 147     // applies to all channels.
 148     // Ex: [BETA, STABLE]
 149     repeated Channel channel = 4;
 150
 151     // List of platforms that will receive this study. If omitted, the study
 152     // applies to all platforms.
 153     // Ex: [PLATFORM_WINDOWS, PLATFORM_MAC]
 154     repeated Platform platform = 5;
 155
 156     // List of locales that will receive this study. If omitted, the study
 157     // applies to all locales.
 158     // Ex: ["en-US", "en-CA"]
 159     repeated string locale = 6;
 160
 161     // List of form factors that will receive this study. If omitted, the study
 162     // applies to all form factors.
 163     // Ex: [PHONE, TABLET]
 164     repeated FormFactor form_factor = 7;
 165   }
 166
 167   // Filtering criteria for this study. A study that is filtered out for a given
 168   // client is equivalent to that study not being sent at all.
 169   optional Filter filter = 10;
 170
 171   // Randomization seed to be used when |consistency| is set to PERMANENT. If
 172   // not specified, randomization will be done using the trial name.
 173   optional uint32 randomization_seed = 11;
 174
 175   // Specifies whether the study starts as active initially, or whether it
 176   // requires the client to query its state before it is marked as active.
 177   enum ActivationType {
 178     // The study will be activated when its state is queried by the client.
 179     // This is recommended for most studies that include client code.
 180     ACTIVATION_EXPLICIT  = 0;
 181     // The study will be automatically activated when it is created. This
 182     // is recommended for studies that do not have any client logic.
 183     ACTIVATION_AUTO      = 1;
 184   }
 185
 186   // Activation type for this study. Defaults to ACTIVATION_EXPLICIT if omitted.
 187   optional ActivationType activation_type = 12;
 188 }