variations/proto/study.proto

// Copyright (c) 2012 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.

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

package variations;

// This defines the Protocol Buffer representation of a Chrome Variations study
// as sent to clients of the Variations server.
//
// Next tag: 13
message Study {
  // The name of the study. Should not contain spaces or special characters.
  // Ex: "my_study"
  required string name = 1;

  // The expiry date of the study in Unix time format. (Seconds since midnight
  // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time
  //
  // A study that has expired will be disabled, which will take precedence over
  // a corresponding hardcoded field trial in the client.
  //
  // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
  optional int64 expiry_date = 3;

  // Consistency setting for a study.
  enum Consistency {
    SESSION = 0;  // Can't change within a session.
    PERMANENT = 1;  // Can't change for a given user.
  }

  // Consistency setting for this study. Optional - defaults to SESSION.
  // Ex: PERMANENT
  optional Consistency consistency = 7 [default = SESSION];

  // Name of the experiment that gets the default experience. This experiment
  // must be included in the list below.
  // Ex: "default"
  optional string default_experiment_name = 8;

  // An experiment within the study.
  //
  // Next tag: 10
  message Experiment {
    // A named parameter value for this experiment.
    //
    // Next tag: 3
    message Param {
      // The name of the parameter.
      optional string name = 1;

      // The value of the parameter.
      optional string value = 2;
    }

    // The name of the experiment within the study.
    // Ex: "bucketA"
    required string name = 1;

    // The cut of the total probability taken for this experiment (the x in
    // x / N, where N is the sum of all xs).  Ex: "50"
    required uint32 probability_weight = 2;

    // Optional id used to uniquely identify this experiment for Google web
    // properties.
    optional uint64 google_web_experiment_id = 3;

    // Optional id used to allow this experiment to trigger experimental
    // behavior on Google web properties.
    optional uint64 google_web_trigger_experiment_id = 8;

    // Optional id used to uniquely identify this experiment for Google Update.
    optional uint64 google_update_experiment_id = 4;

    // Optional name of a Chrome flag that, when present, causes this experiment
    // to be forced. If the forcing_flag field is set, users will not be
    // assigned to this experiment unless that flag is present in Chrome's
    // command line.
    optional string forcing_flag = 5;

    // Parameter values for this experiment.
    repeated Param param = 6;

    enum Type {
      // Regular experiment group. This is the default value and can be omitted.
      NORMAL = 0;

      // Changes to this experiment group are ignored for the purposes of
      // kill-switch triggering. Included to allow the flexibility to not
      // trigger this logic for specific cases (e.g. a group rename without
      // any functionality changes).
      IGNORE_CHANGE = 1;

      // This is a kill-switch group that should be killed at "best effort"
      // priority, e.g. with a hot dog menu badge. The experiment must have a
      // probability_weight of 0.
      KILL_BEST_EFFORT = 2;

      // This is a kill-switch group that should be killed with "critical"
      // priority. Depending on platform this may result in showing a
      // non-dismissible restart prompt with a timer. This should only be used
      // in very serious emergency circumstances. The experiment must have a
      // probability_weight of 0.
      KILL_CRITICAL = 3;
    }
    optional Type type = 7 [default = NORMAL];

    // A UI string to override, and the new value to use.
    message OverrideUIString {
      // The first 32 bits of the MD5 hash digest of the resource name to
      // override.
      // e.g. Hash("IDS_BOOKMARK_BAR_UNDO")
      optional fixed32 name_hash = 1;

      // The new value of the string being overridden.
      // e.g. "Undo"
      optional string value = 2;
    }
    repeated OverrideUIString override_ui_string = 9;
  }

  // List of experiments in this study. This list should include the default /
  // control experiment.
  //
  // For example, to specify that 99% of users get the default behavior, while
  // 0.5% of users get experience "A" and 0.5% of users get experience "B",
  // specify the values below.
  // Ex: { "default": 990, "A": 5, "B": 5 }
  repeated Experiment experiment = 9;

  // Possible Chrome release channels.
  // See: http://dev.chromium.org/getting-involved/dev-channel
  enum Channel {
    // UNKNOWN value is defined here for the benefit of code using this enum
    // type, but is not actually meant to be encoded in the protobuf.
    UNKNOWN = -1;
    CANARY = 0;
    DEV = 1;
    BETA = 2;
    STABLE = 3;
  }

  // Possible Chrome operating system platforms.
  enum Platform {
    PLATFORM_WINDOWS  = 0;
    PLATFORM_MAC      = 1;
    PLATFORM_LINUX    = 2;
    PLATFORM_CHROMEOS = 3;
    PLATFORM_ANDROID  = 4;
    PLATFORM_IOS      = 5;
  }

  // Possible form factors Chrome is running on.
  enum FormFactor {
    DESKTOP = 0;
    PHONE   = 1;
    TABLET  = 2;
  }

  // Filtering criteria specifying whether this study is applicable to a given
  // Chrome instance.
  //
  // Next tag: 10
  message Filter {
    // The start date of the study in Unix time format. (Seconds since midnight
    // January 1, 1970 UTC). See: http://en.wikipedia.org/wiki/Unix_time
    // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
    optional int64 start_date = 1;

    // The minimum Chrome version for this study, allowing a trailing '*'
    // character for pattern matching. Inclusive. (To check for a match, iterate
    // over each component checking >= until a * or end of string is reached.)
    // Optional - if not specified, there is no minimum version.
    // Ex: "17.0.963.46", "17.0.963.*", "17.*"
    optional string min_version = 2;

    // The maximum Chrome version for this study; same formatting as
    // |min_version| above. Inclusive. (To check for a match, iterate over each
    // component checking <= until a * or end of string is reached.)
    // Optional - if not specified, there is no maximum version.
    // Ex: "19.*"
    optional string max_version = 3;

    // List of channels that will receive this study. If omitted, the study
    // applies to all channels.
    // Ex: [BETA, STABLE]
    repeated Channel channel = 4;

    // List of platforms that will receive this study. If omitted, the study
    // applies to all platforms.
    // Ex: [PLATFORM_WINDOWS, PLATFORM_MAC]
    repeated Platform platform = 5;

    // List of locales that will receive this study. If omitted, the study
    // applies to all locales.
    // Ex: ["en-US", "en-CA"]
    repeated string locale = 6;

    // List of form factors that will receive this study. If omitted, the study
    // applies to all form factors.
    // Ex: [PHONE, TABLET]
    repeated FormFactor form_factor = 7;

    // List of ChromeOS hardware classes that will receive this study. Each
    // entry is treated as a substring of the actual device hardware_class,
    // so "FOO" will match the client's hardware class "Device FOOBAR". If
    // omitted, the study applies to all hardware classes unless
    // |exclude_hardware_class| is specified. Mutually exclusive with
    // |exclude_hardware_class|.
    repeated string hardware_class = 8;

    // List of ChromeOS hardware classes that will be excluded in this
    // study. Each entry is treated as a substring of the actual device
    // hardware_class, so "FOO" will match the client's hardware class
    // "Device FOOBAR". If omitted, the study applies to all hardware classes
    // unless |hardware_class| is specified. Mutually exclusive with
    // |hardware_class|.
    repeated string exclude_hardware_class = 9;
  }

  // Filtering criteria for this study. A study that is filtered out for a given
  // client is equivalent to that study not being sent at all.
  optional Filter filter = 10;

  // Randomization seed to be used when |consistency| is set to PERMANENT. If
  // not specified, randomization will be done using the trial name.
  optional uint32 randomization_seed = 11;

  // Specifies whether the study starts as active initially, or whether it
  // requires the client to query its state before it is marked as active.
  enum ActivationType {
    // The study will be activated when its state is queried by the client.
    // This is recommended for most studies that include client code.
    ACTIVATION_EXPLICIT  = 0;
    // The study will be automatically activated when it is created. This
    // is recommended for studies that do not have any client logic.
    ACTIVATION_AUTO      = 1;
  }

  // Activation type for this study. Defaults to ACTIVATION_EXPLICIT if omitted.
  optional ActivationType activation_type = 12;
}