// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// This file was exported from google3, do not edit manually.
// See README.chromium for details.

edition = "2023";

option optimize_for = LITE_RUNTIME;
option java_package = "org.chromium.components.variations";

package variations;

import "components/variations/proto/layer.proto";

option features.enum_type = CLOSED;
option features.utf8_validation = NONE;

// This defines the Protocol Buffer representation of a Finch study as sent to
// clients of the Finch server.
//
// Next tag: 20
message Study {
  // The name of the study. Should not contain spaces or special characters.
  // Ex: "my_study"
  string name = 1 [features.field_presence = LEGACY_REQUIRED];

  // DEPRECATED: Prefer end_date instead.
  // 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, and users will be assigned
  // groups based on the default_experiment_name. This will take precedence over
  // a corresponding hardcoded field trial in the client.
  //
  // Ex: 1330893974  (corresponds to 2012-03-04 20:46:14Z)
  int64 expiry_date = 3;

  // Consistency setting for a study.
  enum Consistency {
    // OPEN enum type causes unknown values get preserved in the field directly,
    // as opposed to the field defaulting to the first value. We then validate
    // this explicitly in processed_study.cc.
    option features.enum_type = OPEN;

    SESSION = 0;    // Can't change within a session.
    PERMANENT = 1;  // Can't change for a given user.
  }

  // Consistency setting for this study.
  // Ex: PERMANENT
  Consistency consistency = 7 [default = SESSION];

  // Optionally specifies which layer the study is a part of. A study must
  // specify both the ID of the layer and the ID(s) of the layer member(s)
  // within that layer to which the study should be constrained.
  LayerMemberReference layer = 16;

  // Name of the experiment that gets the default experience. This experiment
  // must be included in the list below. If not specified, a generic default
  // experiment name is used.
  // Ex: "default"
  string default_experiment_name = 8;

  // Specifies under which conditions a Google web experiment ID or a Google web
  // trigger experiment ID is visible to Google web properties. An ID is visible
  // if it is included in the X-Client-Data header of a request to a Google web
  // property.
  enum GoogleWebVisibility {
    // The experiment ID is included in the header regardless of the context
    // in which the request is initiated.
    //
    // Use this option only when necessary. This is the default at the
    // Experiment level to match the previous behavior.
    ANY = 0;

    // Only requests initiated from a first-party context include the
    // experiment ID. This option is preferred.
    //
    // The following requests are considered to be from a first-party context:
    // requests initiated by (i) the browser, (ii) a Chrome internal page,
    // (iii) a main frame with a Google-owned domain, and (iv) a subframe
    // whose associated main frame has a Google-owned domain. See
    // IsFirstPartyContext() in variations_http_headers.cc for details.
    FIRST_PARTY = 1;
  }

  // The start date for Google web visibility visibility in Unix time format.
  // (Seconds since midnight January 1, 1970 UTC). It specifies the exact date
  // when Google web IDs reporting for a particular study should commence. The
  // Google web visibility start and end dates provide more finely-grained
  // control over when an experiment reports its Google web IDs. If omitted, the
  // client will default to the de-facto behavior of always reporting Google web
  // IDs when the study is active.
  int64 google_web_visibility_start_date = 17;

  // The end date for Google web visibility in Unix time format. (Seconds since
  // midnight January 1, 1970 UTC). It defines the specific date on which Google
  // web ID reporting for a study should cease.
  int64 google_web_visibility_end_date = 18;

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

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

    // The name of the experiment within the study.
    // Ex: "bucketA"
    string name = 1 [features.field_presence = LEGACY_REQUIRED];

    // The cut of the total probability taken for this experiment (the x in
    // x / N, where N is the sum of all x’s).  Ex: "50"
    uint32 probability_weight = 2 [features.field_presence = LEGACY_REQUIRED];

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

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

    // Optional visibility setting affecting the experiment ID fields. See
    // GoogleWebVisibility enum for details.
    GoogleWebVisibility google_web_visibility = 16 [default = ANY];

    // Optional ID used to uniquely identify this experiment when activating
    // integrations with the Android Google App.
    // IMPORTANT: This field is only approved for integrations with the Android
    // Google App and must receive a privacy review before extending to other
    // apps.
    uint64 google_app_experiment_id = 15;

    // Specifies the feature association parameters for this experiment group.
    //
    // Next tag: 5
    message FeatureAssociation {
      // Optional list of features to enable when this experiment is selected.
      // Command-line overrides take precedence over this setting. No feature
      // listed here should exist in the |disable_feature| list.
      repeated string enable_feature = 1;

      // Optional list of features to disable when this experiment is selected.
      // Command-line overrides take precedence over this setting. No feature
      // listed here should exist in the |enable_feature| list.
      repeated string disable_feature = 2;

      // Similar to |forcing_flag|, this is an optional name of a feature which
      // will cause this experiment to be activated, if that feature is enabled
      // from the command-line. Experiment with this set are not eligible for
      // selection via a random dice roll.
      // Mutually exclusive with |forcing_flag|, |forcing_feature_off| or
      // having a non-zero |probability_weight|.
      string forcing_feature_on = 3;

      // Similar to |forcing_flag|, this is an optional name of a feature which
      // will cause this experiment to be activated, if that feature is disabled
      // from the command-line. Experiment with this set are not eligible for
      // selection via a random dice roll.
      // Mutually exclusive with |forcing_flag|, |forcing_feature_on| or having
      // a non-zero |probability_weight|.
      string forcing_feature_off = 4;
    }

    FeatureAssociation feature_association = 12;

    // 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.
    // Mutually exclusive with |forcing_feature_on|, |forcing_feature_off| or
    // having a non-zero |probability_weight|.
    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;
    }

    Type type = 7 [default = NORMAL];
  }

  // 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.
  // These names must match those in tools/variations/fieldtrial_to_struct.py.
  enum Platform {
    PLATFORM_WINDOWS = 0;
    PLATFORM_MAC = 1;
    PLATFORM_LINUX = 2;
    PLATFORM_CHROMEOS = 3;
    PLATFORM_ANDROID = 4;
    PLATFORM_IOS = 5;
    PLATFORM_ANDROID_WEBVIEW = 6;
    PLATFORM_FUCHSIA = 7;
    // PLATFORM_ANDROID_WEBLAYER was sunsetted and reserved.
    // Tracking bug: b/305377215
    reserved 8;
    reserved PLATFORM_ANDROID_WEBLAYER;
    // PLATFORM_CHROMEOS_LACROS was sunsetted and reserved.
    // Tracking bug: b/435674999
    reserved 9;
    reserved PLATFORM_CHROMEOS_LACROS;
  }

  // Possible form factors Chrome is running on.
  // The set of field trials to apply is determined at application startup. For
  // foldables--which are devices that can change from phone-sized to
  // tablet-sized--this can cause problems. When folding/unfolding, while
  // ChromeTabbedActivity may be recreated, the Chrome application intentionally
  // is not. For foldables, this means that a feature that's limited in the
  // Finch config to 'phone' or 'tablet' only may incorrectly be (un)available
  // after (un)folding. Rather than using the Finch form_factor field, features
  // that should only be enabled on a phone-sized or tablet-sized screen should
  // check the current UI mode in client Java or C++ code.
  enum FormFactor {
    // Chrome Desktop on Windows, Mac, Linux, or ChromeOS.
    DESKTOP = 0;

    // Phone-based mobile Chrome, e.g. an Android phone or iPhone.
    PHONE = 1;  // beware of foldables; see comment by enum definition.

    // Tablet-based mobile Chrome, e.g. an Android tablet or iPad.
    TABLET = 2;  // beware of foldables; see comment by enum definition.

    // ChromeOS running in single-app Kiosk mode.
    KIOSK = 3;

    // ChromeOS running on Meet Hardware devices e.g. Chromebox For Meetings.
    MEET_DEVICE = 4;

    // Chrome running on Android TV.
    TV = 5;

    // Chrome running on Android Auto.
    AUTOMOTIVE = 6;

    // Chrome running on Android Foldable.
    FOLDABLE = 7;
  }

  // Possible browser process CPU architectures on which Chrome is running.
  enum CpuArchitecture {
    X86_64 = 0;
    ARM64 = 1;
    X86_32 = 2;
    ARM32 = 3;

    // A Mac-only value, indicating an x86-64 binary running on an arm64 host
    // via "Rosetta 2" binary translation.
    TRANSLATED_X86_64 = 4;
  }

  // Possible states of the policy restriction filter.
  enum PolicyRestriction {
    // No restriction configs apply to clients that do not have a
    // "ChromeVariations" policy set or if it is set to the variations enabled
    // value.
    NONE = 0;

    // Critical studies apply to both clients that have all variations enabled
    // or if the "ChromeVariations" policy is set to only allow critical
    // variations.
    CRITICAL = 1;

    // Critical-only studies apply *only* to clients that have the
    // "ChromeVariations" policy set to only allow critical variations.
    CRITICAL_ONLY = 2;
  }

  // Filtering criteria specifying whether this study is applicable to a given
  // Chrome instance.
  //
  // Next tag: 28
  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)
    int64 start_date = 1;

    // The end 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)
    // Mutually exclusive with expiry_date. The difference between end_date and
    // expiry_date is that, when end_date is past, the field trial will not be
    // created. When expiry_date is past, the trial is still created, but will
    // be disabled, causing it to select its default group.
    int64 end_date = 13;

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

    // The maximum Chrome version for this study. See |min_version| above for
    // formatting and examples. Inclusive. (To check for a match, iterate over
    // each component checking <= until '.*' or the end of the string is
    // reached.)
    //
    // If not specified, there is no maximum Chrome version.
    string max_version = 3;

    // The minimum OS version for this study, allowing a trailing wildcard '.*'
    // for pattern matching. Inclusive. (To check for a match, iterate over each
    // component checking >= until '.*' or the end of the string is reached.) OS
    // versions are sanitized into a list of digits separated by dots like so:
    //  Windows:  "6.2.7601 SP1"      --> "6.2.7601.1"
    //  Mac OS X: "10.11.2"           --> "10.11.2"
    //  Linux:    "4.13.0-32-generic" --> "4.13.0"
    //
    // If not specified, there is no minimum OS version.
    string min_os_version = 16;

    // The maximum OS version for this study. See |min_os_version| above for
    // formatting and examples. Inclusive. (To check for a match, iterate over
    // each component checking <= until '.*' or the end of the string is
    // reached.)
    //
    // If not specified, there is no maximum OS version.
    string max_os_version = 17;

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

    // List of platforms that will receive this study. At least one platform
    // is required. If omitted, the study won't apply to any platform.
    // Ex: [PLATFORM_WINDOWS, PLATFORM_MAC]
    repeated Platform platform = 5
        [features.repeated_field_encoding = EXPANDED];

    // List of locales that will receive this study. If omitted, the study
    // applies to all locales, unless |exclude_locale| is specified. Mutually
    // exclusive with |exclude_locale|.
    // Ex: ["en-US", "en-GB"]
    repeated string locale = 6;

    // List of locales that will be excluded from this study. If omitted, the
    // study applies to all locales unless |locale| is specified. Mutually
    // exclusive with |locale|.
    // Ex: ["en-US", "en-GB"]
    repeated string exclude_locale = 12;

    // List of form factors that will receive this study. If omitted, the study
    // applies to all form factors, unless |exclude_form_factor| is specified.
    // Mutually exclusive with |exclude_form_factor|.
    // Ex: [PHONE, TABLET]
    repeated FormFactor form_factor = 7
        [features.repeated_field_encoding = EXPANDED];

    // List of form factors that will be excluded from this study. If omitted,
    // the study applies to all form factors unless |form_factor| is specified.
    // Mutually exclusive with |form_factor|.
    // Ex: [PHONE, TABLET]
    repeated FormFactor exclude_form_factor = 14
        [features.repeated_field_encoding = EXPANDED];

    // List of hardware classes that will receive this study.
    // This supports ChromeOS and Android.
    //
    // This does a case insensitive match on the same hardware class field that
    // is reported to UMA in the SystemProfileProto's |hardware.hardware_class|
    // field.
    //
    // If omitted, the study applies to all hardware classes unless
    // |exclude_hardware_class| is specified. Mutually exclusive with
    // |exclude_hardware_class|.
    // Ex: ["veyron_minnie", "daisy"]
    repeated string hardware_class = 8;

    // List of hardware classes that will be excluded in this study.
    // This supports ChromeOS and Android.
    //
    // This does a case insensitive match on the same hardware class field that
    // is reported to UMA in the SystemProfileProto's |hardware.hardware_class|
    // field.
    //
    // If omitted, the study applies to all hardware classes unless
    // |hardware_class| is specified. Mutually exclusive with |hardware_class|.
    // Ex: ["veyron_minnie", "daisy"]
    repeated string exclude_hardware_class = 9;

    // List of lowercase ISO 3166-1 alpha-2 country codes that will receive this
    // study. If omitted, the study applies to all countries unless
    // |exclude_country| is specified. Mutually exclusive with
    // |exclude_country|.
    // Ex: ["in", "us"]
    repeated string country = 10;

    // List of lowercase ISO 3166-1 alpha-2 country codes that will be excluded
    // from this study. If omitted, the study applies to all countries unless
    // |country| is specified. Mutually exclusive with |country|.
    // Ex: ["in", "us"]
    repeated string exclude_country = 11;

    // Specifies whether the config should apply to low-end devices only. This
    // is currently only supported on Android.
    bool is_low_end_device = 15;

    // Specifies whether the config should apply to enterprise or non-enterprise
    // only. If omitted, the config applies to both groups.
    // - On windows and mac, machines on a domain network are considered
    //   enterprise.
    // - On ChromeOS, registered mode determines enterprise status.
    // - Android, iOS, and linux consider all clients as non-enterprise.
    bool is_enterprise = 18;

    // Specifies the restrictions applied by the "ChromeVariations" policy to
    // the study. See the definition of the PolicyRestriction enum for details.
    PolicyRestriction policy_restriction = 19 [default = NONE];

    // Browser process CPU architectures that should receive or not receive this
    // study. If |cpu_architecture| is omitted, the default behavior is for the
    // study to apply to all CPU architectures not listed in
    // |exclude_cpu_architecture|.
    repeated CpuArchitecture cpu_architecture = 20
        [features.repeated_field_encoding = EXPANDED];

    repeated CpuArchitecture exclude_cpu_architecture = 21
        [features.repeated_field_encoding = EXPANDED];

    // Specifies that the config should apply only to clients where at least
    // one of the signed in users is a member of at least one of the specified
    // groups.
    // The values are the gaia ID of the google group.
    repeated int64 google_group = 22;

    // Specifies that the config should apply only to clients where none
    // of the signed in users are a member of any of the specified groups.
    // The values are the gaia ID of the google group.
    repeated int64 exclude_google_group = 23;

    // List of hardware manufacturers that will receive this study.
    //
    // This does a case insensitive match on the hardware manufacturer.
    //
    // If omitted, the study applies to all hardware manufacturers unless
    // |exclude_hardware_manufacturer| is specified. Mutually exclusive with
    // |exclude_hardware_manufacturer|.
    // Ex: ["google", "lenovo"]
    // Supported only on Android starting in M150.
    repeated string hardware_manufacturer = 24;

    // List of hardware manufacturers that will be excluded from this study.
    //
    // This does a case insensitive match on the hardware manufacturer.
    //
    // If omitted, the study applies to all hardware manufacturers unless
    // |hardware_manufacturer| is specified. Mutually exclusive with
    // |hardware_manufacturer|.
    // Ex: ["google", "lenovo"]
    // Supported only on Android starting in M150.
    repeated string exclude_hardware_manufacturer = 25;

    // Specifies that the config should apply only to clients where the browser
    // or at least one of the signed in users is affiliated with a customer that
    // is a member of at least one of the specified enterprise groups.
    // The values are the enterprise group IDs.
    repeated string enterprise_group = 26;

    // Specifies that the config should apply only to clients where the browser
    // and all of the signed in users are not affiliated with a customer that is
    // a member of any of the specified enterprise groups.
    // The values are the enterprise group IDs.
    repeated string exclude_enterprise_group = 27;
  }

  // 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.
  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.
  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 {
    // OPEN enum type causes unknown values get preserved in the field directly,
    // as opposed to the field defaulting to the first value. We then validate
    // this explicitly in processed_study.cc.
    option features.enum_type = OPEN;

    // The study will be activated when its state is queried by the client.
    // This is recommended for most studies that include client code.
    ACTIVATE_ON_QUERY = 0;

    // The study will be automatically activated when it is created. This
    // is recommended for studies that do not have any client logic.
    ACTIVATE_ON_STARTUP = 1;

    // The study is first activated when it is queried. On browser restarts, the
    // study remains active unless the client would be assigned to a different
    // group. This is recommended to avoid problems of differential triggering
    // associated with ACTIVATE_ON_QUERY and for studying longer-term effects
    // without activation on start up. Only valid for studies using PERMANENT
    // consistency.
    // Supported starting with version 142.0.7444.48.
    STICKY_AFTER_QUERY = 2;
  }

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

  // WIP: Do not use yet.
  // Indicates that this study config is runtime mutable and will apply to users
  // as they receive a new Finch config (without needing a Chrome restart).
  // TODO: b/482451024 - Document this feature.
  bool runtime_mutable = 19;
}