搜索配置模式 (已归档)

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

注意

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

概述

配置是一个 JSON 块,它是一个包含 data 属性的对象,该属性是一个引擎数组。

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

引擎对象

引擎的详细信息位于与其关联的对象的属性中。全局部署的引擎可以简单地列出为

{
  "default": "no",
  "telemetryId": "engine1-telem",
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
    }
  }]
}

The appliesTo 部分是一个对象数组。至少需要一个对象来指定引擎包含在哪些区域/语言环境中。如果 appliesTo 对象列出了其他属性,则这些属性将覆盖顶层的所有属性。

例如,更复杂的引擎定义可能仅对位于特定区域或具有特定语言环境的用户可用。例如

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "region": "us"
    },
    "webExtension": {
      "id": "web-us@ext"
    }
  }, {
    "included": {
      "region": "gb"
    },
    "webExtension": {
      "id": "web-gb@ext"
    }
  }]
}

在这种情况下,被识别为位于美国地区的用户的将使用标识符为 web-us@ext 的 WebExtension。英国地区的用户将获得 web-gb@ext,所有其他用户将获得 web@ext

要指示搜索引擎从特定语言环境目录中提取 _locale 数据,可以使用 webExtension.locales

例如,在此代码块中

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [
    {
      "included": {
        "locales": "en-US"
      },
      "webExtension": {
        "locales": [
          "us"
        ]
      }
    }, {
      "included": {
        "locales": "en-GB"
      },
      "webExtension": {
        "locales": [
          "uk"
        ]
      }
    }
  ]
}

在扩展 weblocales 目录中,应该存在一个 usuk 文件夹。

如果未提供语言环境,则 webExtension.locales 将设置为 SearchUtils.DEFAULT_TAG

搜索扩展目录

语言环境目录示例

特殊属性

$USER_LOCALE

如果 webExtension.locales 属性包含一个值为 "$USER_LOCALE" 的元素,则配置对象中的特殊值将被替换为用户的语言环境。例如

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "locales": {
        "matches": [
          "en-US",
          "en-GB"
        ]
      }
    },
    "webExtension": {
      "locales": ["$USER_LOCALE"]
    }
  }]
}

将根据用户的语言环境报告 [en-US][en-GB] 作为 webExtension.locales 属性。

由于特殊字符串被替换,因此可以通过在一致的前缀/后缀之间添加关键字来搜索自定义文件夹名称。

例如,如果 webExtension.locales["example-$USER_LOCALE"],则语言环境生成器将生成 example-en-USexample-en-GB 形式的语言环境名称。

注意:在 Firefox 100.0 之前,$USER_LOCALE 使用精确匹配。在 Firefox 100.0 中,替换更新为使用标准字符串替换。

从 Firefox 98.0.1 和 97.7.1esr 开始,"$USER_LOCALE" 也可用于 telemetryId 字段。

$USER_REGION

这可以在与 "$USER_LOCALE" 相同的情况下使用,而是用使用用户区域的字符串替换 webExtension.locale

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
    },
    "webExtension": {
      "locales": ["foo-$USER_REGION"]
    }
  }]
}

在此示例中,如果用户的区域为 fr,则 webExtension.locale 将为 foo-fr,代码将在此扩展的 _locales 文件夹的 foo-fr 文件夹中查找 messages.json

注意:"$USER_REGION" 添加于 Firefox 98.0.1 和 97.7.1esr 中,并使用精确匹配。在 Firefox 100.0 中,替换更新为使用标准字符串替换。

“default”

如果引擎在不知道用户区域时应包含在内,则可以在配置中将 "default" 指定为区域。

“override”

如果希望某个部分仅覆盖其他包含的引擎,则可以将 "override" 字段设置为 true。 "override" 仅适用于适用于分发或实验的部分。实验用例添加于 Firefox 81 中。

从 Firefox 96 开始,"override" 部分可能包含 includedexcluded 信息,这些信息将相应地应用。如果它们未提供,则覆盖部分将应用于所有位置。

示例

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    // Complicated and lengthy inclusion rules
  }, {
    "override": true,
    "application": { "distributions": ["mydistrocode"]},
    "params": {
      "searchUrlGetParams": [
        { "name": "custom", "value": "foobar" }
      ]
    }
  }]
}

应用程序范围

引擎配置可以限定到特定应用程序。

名称

可以指定一个或多个应用程序名称。当前支持的唯一应用程序类型是 firefox。如果指定了应用程序名称,则必须将其与部分匹配才能应用。如果没有指定应用程序名称,则该部分将匹配任何配置使用者。

在以下示例中,web@ext 将包含在任何配置使用者中,但 web1@ext 仅包含在 Firefox 桌面版中。

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "name": []
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "name": ["firefox"]
      }
    }
  ]}
}

渠道

可以在数组中指定一个或多个渠道,以将配置限制为仅这些渠道。当前已知的渠道为

  • default:Firefox 的自建版本,或可能是一些自发布版本。

  • nightly:Firefox Nightly 构建。

  • aurora:Firefox 开发者版

  • beta:Firefox Beta

  • release:主要的 Firefox 发布渠道。

  • esr:ESR 渠道。这也将匹配 Firefox 版本,其中显示的版本号包含 esr。我们这样做是为了包括 Linux 发行版和其他 ESR 的手动构建。

在以下示例中,web@ext 将仅在默认渠道上设置为默认值,而 web1@ext 将在发布和 esr 渠道上设置为默认值。

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "default": "yes",
      "application": {
        "channel": ["default"]
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "default": "yes",
      "application": {
        "channel": ["release", "esr"]
      }
    }
  ]}
}

分发

可以在 appliesTo 部分中指定要包含或排除的分发。 application 部分中的 distributions 字段是分发标识符数组。这些标识符与 distribution.id 首选项提供的标识符相匹配。

在以下示例中,web@ext 仅包含在 cake 分发中。 web1@ext 将从 apples 分发中排除,但包含在主桌面应用程序和所有其他分发中。

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "distributions": ["cake"]
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "excludedDistributions": ["apples"]
      }
    }
  ]}
}

版本

可以指定最小版本和最大版本以将配置限制为特定范围。这些可能是开放式的。版本比较使用 版本比较器 执行。

注意:与 maxVersion 的比较是小於比较。 maxVersion 不会直接匹配。

在以下示例中,web@ext 将包含在 72.0a1 之后的任何版本中,而 web1@ext 将仅包含在 68.0a1 和 71.x 版本之间。

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "application": {
        "minVersion": "72.0a1"
      }
    }
  ]}
},
{
  "webExtension": {
    "id": "web1@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
      "default": "yes",
      "application": {
        "minVersion": "68.0a1"
        "maxVersion": "72.0a1"
      }
    }
  ]}
}

实验

我们可以通过在 appliesTo 中的部分赋予 experiment 值来运行实验,然后 Search Service 可以选择性地传入匹配的 experiment 值以匹配这些部分。

除非传入匹配的 experiment,否则具有 experiment 的部分将不会使用,例如

{
  "webExtension": {
    "id": "web@ext"
  },
  "appliesTo": [{
    "included": {
      "everywhere": true
    },
    "experiment": "nov-16",
    "webExtension": {
      "id": "web-experimental@ext"
    }
  }, {
    "included": {
      "everywhere": true
    },
    "webExtension": {
      "id": "web-gb@ext"
    }
  }]
}

引擎默认值

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

  1. 普通浏览模式,

  2. 隐私浏览模式。

如果对于特定区域/语言环境对,未为隐私浏览模式指定引擎,则使用普通模式引擎。

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

引擎可能针对特定区域/语言环境是默认的,也可能不是。 default 属性是一个三态值,其状态为 yesyes-if-no-otherno。以下是如何应用它们的示例。

{
  "webExtension": {
    "id": "engine1@ext"
  },
  "appliesTo": [{
    "included": {
      "region": "us"
    },
    "default": "yes"
  }, {
    "excluded": {
      "region": "us"
    },
    "default": "yes-if-no-other"
  }]
},
{
  "webExtension": {
    "id": "engine2@ext"
  },
  "appliesTo": [{
    "included": {
      "region": "gb"
    },
    "default": "yes"
  }]
},
  "webExtension": {
    "id": "engine3@ext"
  },
  "default": "no"
  "appliesTo": [{
    "included": {
      "everywhere": true
    },
  }]
},
{
  "webExtension": {
    "id": "engine4@ext"
  },
  "defaultPrivate": "yes",
  "appliesTo": [{
    "included": {
      "region": "fr"
    }
  }]
}

在此示例中,对于普通模式

  • engine1@ext 是美国地区的默认引擎,以及除英国以外的所有其他地区。

  • engine2@ext 仅在英国地区为默认引擎。

  • engine3@ext 和 engine4 在任何地方都不是默认引擎。

在隐私浏览模式下

  • engine1@ext 是美国地区的默认引擎,以及除英国和法国以外的所有其他地区。

  • engine2@ext 仅在英国地区为默认引擎。

  • engine3@ext 在任何地方都不是默认引擎。

  • engine4@ext 是法国地区的默认引擎。

引擎排序

orderHint 字段指示在向用户显示引擎时,相对于其他引擎的建议排序,除非用户自定义了其排序。

引擎的默认排序基于引擎是否为默认引擎以及 orderHint 字段的组合。排序结构如下。

  1. 普通模式下的默认引擎。

  2. 隐私浏览模式下的默认引擎(如果与普通模式引擎不同)。

  3. 其他引擎,按照从最高 orderHint 到最低的顺序排列。

示例

{
  "webExtension": {
    "id": "engine1@ext"
  },
  "orderHint": 2000,
  "default": "no",
},
{
  "webExtension": {
    "id": "engine2@ext"
  },
  "orderHint": 1000,
  "default": "yes"
},
{
  "webExtension": {
    "id": "engine3@ext"
  },
  "orderHint": 500,
  "default": "no"
}

这将导致以下顺序:engine2@ext, engine1@ext, engine3@ext