OpenSearch 記述形式

OpenSearch 記述形式は、ウェブサイトが自分自身のために検索エンジンを記述し、ブラウザーやその他のクライアントアプリケーションがその検索エンジンを使用できるようにするものです。 OpenSearch は、(少なくとも) Firefox、Edge、Internet Explorer、Safari、Chrome が対応しています。(他のブラウザーのドキュメントへのリンクは参考資料をご覧ください。)

また、Firefox では、検索候補や <SearchForm> 要素など、OpenSearch 規格にない追加機能にも対応しています。この記事では、これらの Firefox の追加機能に対応した OpenSearch 互換の検索プラグインの作成に焦点を当てます。

OpenSearch 記述ファイルは、検索プラグインの自動検出で説明されているように通知することができ、ウェブページからの検索エンジンの追加で説明されているようにプログラムでインストールすることができます。

OpenSearch 記述ファイル

検索エンジンを記述する XML ファイルはとてもシンプルで、以下の基本的なテンプレートに従います。書いている検索エンジンに応じて、 [角括弧] で囲まれた部分をカスタマイズする必要があります。

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:moz="http://www.mozilla.org/2006/browser/search/">
  <ShortName>[SNK]</ShortName>
  <Description>[Search engine full name and summary]</Description>
  <InputEncoding>[UTF-8]</InputEncoding>
  <Image width="16" height="16" type="image/x-icon">[https://example.com/favicon.ico]</Image>
  <Url type="text/html" template="[searchURL]">
    <Param name="[key name]" value="{searchTerms}"/>
    <!-- other Params if you need them… -->
    <Param name="[other key name]" value="[parameter value]"/>
  </Url>
  <Url type="application/x-suggestions+json" template="[suggestionURL]"/>
  <moz:SearchForm>[https://example.com/search]</moz:SearchForm>
</OpenSearchDescription>
ShortName
検索エンジンの短い名前です。 HTML やその他のマークアップを使用しない、 16 文字以下のプレーンテキストでなければなりません。
Description
検索エンジンの簡単な説明です。 1024 文字以下のプレーンテキストで、 HTML やその他のマークアップは使用しないでください。
InputEncoding
検索エンジンへ送信する入力欄に使用する文字エンコーディングです。
Image

検索エンジンのアイコンの URI です。可能であれば、 16×16 の画像を image/x-icon 形式で (/favicon.ico など)、 および 64×64 の画像を image/jpeg または image/png 形式で含めてください。

この URI には data: URI スキームを使用することもできます。 (data: URI はアイコンファイルから The data: URI kitchen で生成することができます。)

<Image height="16" width="16" type="image/x-icon">https://example.com/favicon.ico</Image>
  <!-- or -->
<Image height="16" width="16">data:image/x-icon;base64,AAABAAEAEBAAA … DAAA=</Image>

Firefox はアイコンを base64 data: URI としてキャッシュします (検索プラグインはプロファイルsearchplugins/ フォルダーに格納されます)。これを行う際に、 http: および https: URL は data: URI に変換されます。

注: リモートからアイコンを読み込む際 (すなわち、 data: URI とは対照的に https:// URI からの場合)、 Firefox は10 KBより大きなアイコンを拒否します。

Firefox の検索ボックスに表示される Google の検索候補

Url
検索に使う 1 つまたは複数の URL を記述します。 template 属性は検索クエリーのベース URL を指定します。
Firefox は 3 種類の URL に対応しています。
  • type="text/html" は実際の検索結果そのものの URL を指定します。
  • type="application/x-suggestions+json" は検索候補を読み取るための URL を指定します。 Firefox 63 以降では、 type="application/json" をこの別名として受け付けます。
  • type="application/x-moz-keywordsearch" はロケーションバーに入力されるキーワード検索の際に使用する URL を指定します。これは Firefox のみが対応しています。

これらの種類の URL では、ユーザーが検索バーやロケーションバーに入力した検索語に置き換えらえる {searchTerms} を使うことができます。対応している他の動的な検索引数は OpenSearch 1.1 引数に記述されています。

検索候補については、 application/x-suggestions+json URL テンプレートを使用して候補リストを JSON 形式で読み取ります。サーバー上で検索候補の対応を実装する方法の詳細は 検索プラグインでの検索候補の対応を参照してください。

Param
検索クエリと一緒に渡さなければならない引数を、キー/値のペアで指定します。値を指定する際に、 {searchTerms} を使用すると、ユーザーが検索バーに入力した検索語を挿入することができます。
moz:SearchForm
プラグインのサイトの検索ページを開くための URL。これは Firefox にユーザーが直接ウェブサイトを訪れる方法を提供します。
注意: この要素は Firefox 特有で OpenSearch 仕様の一部ではないため、この要素に対応していない他のユーザーエージェントが安全に無視できるようにするために、上の例では "moz:" XML 名前空間接頭辞を使っています。

検索プラグインの自動検出

検索プラグインを提供しているウェブサイトは、 Firefox ユーザがプラグインを簡単にダウンロードしてインストールできるように通知することができます。

自動検出に対応するには、それぞれのプラグインの <link> 要素をウェブページの <head> セクションにします。

<link rel="search"
      type="application/opensearchdescription+xml"
      title="searchTitle"
      href="pluginURL">

太字の項目を以下の説明のように置き換えてください。

searchTitle
"MDC を検索" や 'Yahoo! 検索" のような実行する検索の名前です。この値は、プラグインファイルの <ShortName> と一致させる必要があります。
pluginURL
ブラウザーがダウンロードできる XML 検索プラグインの URL です。

もしサイトが複数の検索プラグインを提供しているなら、すべてを自動検出させることができます。例を示します。

<link rel="search" type="application/opensearchdescription+xml"
      title="MySite: 著者" href="http://example.com/mysiteauthor.xml">

<link rel="search" type="application/opensearchdescription+xml"
      title="MySite: タイトル" href="http://example.com/mysitetitle.xml">

この方法で、著者とタイトルによる検索を行うプラグインをサイトで提供することができます。

Firefox では、検索プラグインで提供されたアイコンがある場合は、検索ボックスのアイコンが変化して示します。 (画像を参照。緑のプラスの記号です。) そのため、ユーザーのインターフェイスで検索ボックスが非表示になっている場合、これを示すことはありません一般に、この動作はブラウザーによって異なります

Firefox での検索プラグインの見え方

OpenSearch プラグインの自動更新の対応

OpenSearch プラグインは自動的に更新することができます。 Url 拡張要素を type="application/opensearchdescription+xml" および rel="self" を付けて設置してください。 template 属性には、自動的に更新する OpenSearch 文書の URL を設定してください。

例:

<Url type="application/opensearchdescription+xml"
     rel="self"
     template="https://example.com/mysearchdescription.xml" />
注: 現時点で、 addons.mozilla.org (AMO) は OpenSearch プラグインの自動更新に対応していません。自分の検索プラグインを AMO に登録したい場合は、送信前に自動更新機能を削除してください。

トラブルシューティングのヒント

検索プラグインの XML に問題があると、検出されたプラグインをに追加する際にエラーが発生します。エラーメッセージが参考にならない場合、以下のヒントが問題を探す手助けになる可能性があります。

  • サーバーは OpenSearch プラグインを、 Content-Type: application/opensearchdescription+xml を使用して提供するべきです。
  • 検索プラグインの XML が整形式であることを確認してください。ファイルを直接 Firefox に読み込むことでチェックすることができます。アンパーサンド (&) を template の URL の中では &amp; にエスケープしなければなりません。タグは最後にスラッシュをまたは対応する終了タグで閉じる必要があります。
  • xmlns 属性は重要です。 — これがないと、 "Firefox could not download the search plugin" というエラーメッセージが出る可能性があります。
  • text/html の URL を含める必要があります。 Atom または RSS の URL 型のみを含む検索プラグインは (有効なものですが、 Firefox は対応していません)、 "could not download the search plugin" エラーを引き起こします。
  • リモートで取得されるファビコンは 10KB 以上でなければなりません (バグ 361923 を参照)。

さらに、検索プラグインサービスはプラグイン開発者に役立つであろうログの仕組みを提供します。 about:config を使い 'browser.search.log' を true に設定してください。検索プラグインが追加されるとログ情報が Firefox のエラーコンソール (ツール ➤ エラーコンソール)に表示されます。

参考資料