搜索配置模式¶

本文档概述了 search-config-v2 模式以及各个子部分如何交互的详细信息。有关完整的字段和说明，请参阅模式本身。

注意

在示例中，仅显示相关属性。

概述¶

配置是一个 JSON 块，一个对象，具有 data 属性，其值为一个包含 engine、defaultEngines 和 engineOrders 记录类型的数组。

{
  data: [
    {
      // defaultEngines details
    },
    {
      // engine 1 details
    },
    {
      // engine 2 details
    },
    {
      // engineOrders details
    },
  ]
}

环境¶

每个记录类型中都包含一个 environment 属性，用于根据用户检测到的环境确定应用该记录的部分或全部内容。 environment 中有许多不同的属性。可以单独使用或组合使用这些属性来构建匹配规则。以下是这些属性的列表。

allRegionsAndLocales

"environment": { "allRegionsAndLocales": true }
指示此部分适用于所有地区和语言环境。可能会被 excludedRegions/excludedLocales 修改。

applications

"environment": { "applications": ["firefox"] }
此属性指定将应用该记录的应用程序。
我们支持的一些应用程序包括 firefox、firefox-android、firefox-ios、focus-android 和 focus-ios。

channels

"environment": { "channels": ["default"] }
可以在数组中指定一个或多个通道，以将配置限制为仅这些通道。以下是通道列表：
- default：Firefox 自建版本，或可能是一些自行分发的版本。
- nightly：Firefox Nightly 构建版本。
- aurora：Firefox 开发者版。
- beta：Firefox Beta 版。
- release：主要的 Firefox 发布渠道。
- esr：ESR 渠道。这也会匹配 Firefox 版本，其中显示的版本号包含 esr。我们这样做是为了包含 Linux 发行版和其他手动构建的 ESR 版本。

distributions

"environment": { "distributions": ["distribution-name"] }
记录对象适用的发行版标识符数组。
这些标识符与 distribution.id 首选项提供的标识符匹配。

excludedDistributions

"environment": { "distributions": ["distribution-excluded"] }
记录对象不适用的发行版标识符数组。

excludedLocales

"environment": { "excludedLocales": ["de"] }
此部分应排除的语言环境数组。

excludedRegions

"environment": { "excludedRegions": ["ca"] }
此部分应排除的地区数组。

experiment

"environment": { "experiment": "experimental" }
可以通过为 experiment 属性赋予值来运行实验。
实验值也应提供给 Nimbus 上 searchConfiguration 功能的 experiment 属性。

locales

"environment": { "locales": ["en-US"] }
此部分适用的语言环境数组。

regions

"environment": { "regions": ["ca"] }
此部分适用的地区数组。
"unknown" 可用于应用于我们无法检测到用户所在地区的情况。但是，目前预计不会使用此值。

maxVersion 和 minVersion

可以指定最小版本和最大版本以将配置限制为特定范围。这些范围可以是开放式的。版本比较使用版本比较器进行。
注意：与 maxVersion 的比较是小于比较。不会直接匹配 maxVersion。
"environment": { "minVersion": "72.0a1" } 指示记录对象将在 72.0a1 之后的任何版本中包含。
"environment": { "minVersion": "68.0a1", "maxVersion": "72.0a1" } 指示记录对象仅在 68.0a1 和 71.x 版本之间包含。

引擎对象¶

每个引擎对象都表示可能呈现给用户的搜索引擎。每个引擎对象在应用程序中都被视为一个单独的引擎，具有独立的设置。

{
  "base": {
    "classification": "general"
    "name": "engine1 name",
    "partnerCode": "bar",
    "urls": {
      "search": {
        "base": "https://www.example.com",
        "params": [
          {
            "name": "code",
            "value": "{partnerCode}"
          }
        ],
        "searchTermParamName": "q"
      },
    },
  },
  "identifier": "engine1",
  "recordType": "engine",
  "variants": [
    {
      "environment": { "allRegionsAndLocales": true }
    }
  ]
}

必需的**顶级**属性是：

base 定义引擎的基本详细信息。必需的基本属性是 classification、name 和 urls。
- urls 可以是不同类型的 URL。这些各种类型包括 search、suggestions 和 trending URL。url 属性包含基本 URL 和任何查询字符串参数以构建完整的 URL。如果使用 engine1 搜索 kitten，则搜索 URL 将构建为 https://www.example.com/?code=bar&q=kitten。请注意，来自基本 URL 的 partnerCode 会插入到搜索 URL 的 {partnerCode} 值的参数中。
identifier 标识搜索引擎，并在内部用于设置遥测 ID。
recordType 对象的记录类型。对于引擎对象，始终为 engine。
variants 指定引擎包含的环境，其中详细说明了地区、语言环境和其他环境属性。

引擎变体¶

引擎可能仅对位于特定地区或使用特定语言环境的用户可用。例如，当变体的 environment 部分指定语言环境和地区时

"variants": [
  {
    "environment": { "locales": ["en-US"], "regions": ["US"] }
  }
]

在这种情况下，被识别为位于 en-US 语言环境和 US 地区的用户将能够使用该引擎。

多个变体

当存在多个变体时，将应用最后一个匹配的变体。

"variants": [
  {
    "environment": { "locales": ["en-US"] }
    "partnerCode": "bar"
  },
  {
    "environment": { "locales": ["en-US"], "regions": ["US"]}
    "partnerCode": "foo"
  },
]

在这种情况下，被识别为位于 en-US 语言环境和 US 地区的用户匹配了这两个变体。位于 en-US 语言环境和 US 地区的用户匹配了第一个变体，因为它具有 en-US 语言环境，并且当未指定地区时，表示包含所有地区。然后它匹配了第二个变体，因为它匹配了 en-US 语言环境和 US 地区。结果是，对于此用户，partner code 的值将为 foo。

引擎子变体¶

可以在 variants 内嵌套一个 subVariants 数组。子变体包含与变体相同的属性，除了 subVariants 属性。子变体的目的是将最后一个匹配的子变体和顶级变体的环境属性组合在一起。

"variants": [
  {
    "environment": { "regions": ["US", "CA", "GB"] }
    "subVariants": [
      {
        "environment": { "channels": [ "esr"] },
        "partnerCode": "bar",
      },
    ]
  }
]

在这种情况下，被识别为位于 US 地区和 esr 通道的用户将匹配子变体，并将能够使用应用了 partner code bar 的引擎。

多个子变体

当存在多个子变体时，将应用最后一个匹配的子变体。

"variants": [
  {
    "environment": { "regions": ["US", "CA", "GB"] }
    "subVariants": [
      {
        "environment": { "channels": [ "esr"] },
        "partnerCode": "bar",
      },
      {
        "environment": { "channels": [ "esr"], "locales": ["fr"] },
        "partnerCode": "foo",
      }
    ]
  }
]

在这种情况下，被识别为位于 US 地区、fr 语言环境和 esr 通道的用户匹配了这两个子变体。它匹配了第一个子变体，因为第一个环境具有来自顶级变体的 US 地区、esr 通道和所有语言环境。然后它匹配了第二个变体，因为第二个环境具有来自顶级变体的 US 地区、fr 语言环境和 esr 通道。用户将收到最后一个匹配的子变体，其 partner code 为 foo。

引擎默认值¶

可以将引擎指定为默认值，用于以下两种目的之一：

普通浏览模式，
隐私浏览模式。

如果特定地区/语言环境对的隐私浏览模式未指定引擎，则使用普通模式引擎。

如果应用程序实例不支持单独的隐私浏览模式引擎，则它将仅使用普通模式引擎。

引擎对于特定地区/语言环境可能是或可能不是默认值。defaultEngines 记录的结构为提供 globalDefault 和 globalDefaultPrivate 属性，如果不存在与用户环境匹配的 specificDefaults 部分，则这些属性定义用户的引擎。specificDefaults 部分可以定义与特定用户环境匹配的不同引擎。

{
  "globalDefault": "engine1",
  "globalDefaultPrivate": "engine1",
  "recordType": "defaultEngines",
  "specificDefaults": [
    {
      "default": "engine2",
      "defaultPrivate": "engine3"
      "environment": {
        "locales": [
          "en-CA"
        ],
        "regions": [
          "CA"
        ]
      },
    }
  ]
}

正常模式

除区域 CA 和语言环境 en-CA 外，所有其他区域的默认引擎为 engine1。

仅在 CA 区域和语言环境 en-CA 中，engine2 为默认引擎。

隐私浏览模式

除区域 CA 和语言环境 en-CA 外，所有其他区域的默认隐私引擎为 engine1。

仅在 CA 区域和语言环境 en-CA 中，engine3 为默认隐私引擎。

引擎排序¶

engineOrders 记录类型指示引擎相对于其他引擎的建议排序，这些排序在显示给用户时使用，除非用户自定义了其排序。排序在 order 属性中列出，这是一个有序数组，其中第一个引擎位于最低索引处。

如果用户环境没有匹配的排序，则应用此排序。

默认引擎
默认隐私引擎（如果有）
其他引擎按字母顺序排列。

示例

{
  "orders": [
    {
      "environment": {
        "distributions": [
          "distro"
        ]
      },
      "order": [
        "c-engine",
        "b-engine",
        "a-engine",
      ]
    }
  ]
  "recordType": "engineOrders",
}

这将导致以下顺序：c-engine、b-engine、a-engine，用于发行版 distro。