OpenSearch-Beschreibungsformat

Das OpenSearch-Beschreibungsformat kann verwendet werden, um die Webschnittstelle einer Suchmaschine zu beschreiben. Dies ermöglicht es einer Website, eine Suchmaschine für sich selbst zu beschreiben, sodass ein Browser oder eine andere Client-Anwendung diese Suchmaschine nutzen kann. OpenSearch wird von (mindestens) Firefox, Edge, Safari und Chrome unterstützt. (Siehe Referenzmaterial für Links zu Dokumentationen anderer Browser.)

Firefox unterstützt auch zusätzliche Funktionen, die nicht im OpenSearch-Standard enthalten sind, wie z. B. Suchvorschläge. Dieser Artikel konzentriert sich auf die Erstellung von OpenSearch-kompatiblen Such-Plugins, die diese zusätzlichen Firefox-Funktionen unterstützen.

OpenSearch-Beschreibungsdateien können wie in Autodiscovery von Such-Plugins beschrieben angekündigt werden.

Warnung: OpenSearch-Plugins können nicht mehr auf addons.mozilla.org (AMO) hochgeladen werden. Die Suchmaschinen-Funktion muss die WebExtension API mit chrome settings in der manifest.json-Datei verwenden.

OpenSearch-Beschreibungsdatei

Die XML-Datei, die eine Suchmaschine beschreibt, folgt der untenstehenden Grundvorlage. Abschnitte in [eckigen Klammern] sollten für das spezifische Plugin, das Sie schreiben, angepasst werden.

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]"/>
  <Url type="application/x-suggestions+json" template="[suggestionURL]"/>
</OpenSearchDescription>
ShortName

Ein kurzer Name für die Suchmaschine. Er muss 16 oder weniger Zeichen einfachen Textes enthalten, ohne HTML oder andere Markup-Elemente.

Description

Eine kurze Beschreibung der Suchmaschine. Sie muss 1024 oder weniger Zeichen einfachen Textes enthalten, ohne HTML oder andere Markup-Elemente.

InputEncoding

Die Zeichenkodierung, die beim Senden der Eingaben an die Suchmaschine verwendet wird.

Image

URL eines Icons für die Suchmaschine. Wenn möglich, fügen Sie ein 16×16-Bild vom Typ image/x-icon (z. B. /favicon.ico) und ein 64×64-Bild vom Typ image/jpeg oder image/png ein.

Die URL kann auch das data: URL-Schema verwenden. (Sie können eine data:-URL aus einer Icon-Datei bei The data: URL kitchen generieren.)

xml
<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 speichert das Icon als data:-URL im base64-Format (Such-Plugins werden im searchplugins/-Ordner des Profils gespeichert). http:- und https:-URLs werden in data:-URLs umgewandelt, wenn dies geschieht.

Hinweis: Für Icons, die remote geladen werden (d. h. von https://-URLs anstelle von data:-URLs), lehnt Firefox Icons ab, die größer als 10 Kilobyte sind.

Suchvorschläge von Google, die im Suchfeld von Firefox angezeigt werden

Url

Beschreibt die URL oder URLs, die für die Suche verwendet werden. Das template-Attribut gibt die Basis-URL für die Suchanfrage an.

Firefox unterstützt drei URL-Typen:

  • type="text/html" gibt die URL für die eigentliche Suchanfrage an.
  • type="application/x-suggestions+json" gibt die URL zum Abrufen von Suchvorschlägen an. Ab Firefox 63 wird type="application/json" als Alias dafür akzeptiert.
  • type="application/x-moz-keywordsearch" gibt die URL an, die verwendet wird, wenn eine Schlüsselwortsuche in der Adressleiste eingegeben wird. Dies wird nur in Firefox unterstützt.

Für diese URL-Typen können Sie {searchTerms} verwenden, um die vom Benutzer im Suchfeld oder in der Adressleiste eingegebenen Suchbegriffe zu ersetzen. Andere unterstützte dynamische Suchparameter sind in OpenSearch 1.1 parameter beschrieben.

Für Suchvorschläge wird die application/x-suggestions+json URL-Vorlage verwendet, um eine Vorschlagsliste im JSON-Format abzurufen.

Autodiscovery von Such-Plugins

Websites mit Such-Plugins können diese so ankündigen, dass Firefox-Nutzer die Plugins leicht installieren können.

Um die Autodiscovery zu unterstützen, fügen Sie für jedes Plugin ein <link>-Element in den <head> Ihrer Webseite ein:

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

Ersetzen Sie die Elemente in [eckigen Klammern] wie unten erklärt:

searchTitle

Der Name der durchzuführenden Suche, z. B. "Search MDC" oder "Yahoo! Search". Dieser muss mit dem <ShortName> Ihrer Plugin-Datei übereinstimmen.

pluginURL

Die URL zum XML-Suchplugin, damit der Browser es herunterladen kann.

Wenn Ihre Seite mehrere Such-Plugins bietet, können Sie die Autodiscovery für alle unterstützen. Zum Beispiel:

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

<link
  rel="search"
  type="application/opensearchdescription+xml"
  title="MySite: By Title"
  href="http://example.com/mysitetitle.xml" />

Auf diese Weise kann Ihre Site Plugins anbieten, um nach Autor oder Titel zu suchen.

Hinweis: In Firefox zeigt eine Icon-Änderung im Suchfeld an, dass ein bereitgestelltes Such-Plugin vorhanden ist. (Siehe Bild, das grüne Pluszeichen.) Wenn also kein Suchfeld in der Benutzeroberfläche des Benutzers angezeigt wird, erhalten sie keinerlei Indikation. Im Allgemeinen variiert das Verhalten je nach Browser.

Unterstützung automatischer Updates für OpenSearch-Plugins

OpenSearch-Plugins können automatisch aktualisiert werden. Um dies zu unterstützen, fügen Sie ein zusätzliches Url-Element mit type="application/opensearchdescription+xml" und rel="self" hinzu. Das template-Attribut sollte die URL des OpenSearch-Dokuments sein, zu dem automatisch aktualisiert werden soll.

Zum Beispiel:

xml
<Url type="application/opensearchdescription+xml"
     rel="self"
     template="https://example.com/mysearchdescription.xml" />

Hinweis: Zurzeit unterstützt addons.mozilla.org (AMO) keine automatische Aktualisierung von OpenSearch-Plugins. Wenn Sie Ihr Such-Plugin auf AMO veröffentlichen möchten, entfernen Sie die automatische Update-Funktion, bevor Sie es einreichen.

Tipps zur Fehlersuche

Wenn ein Fehler in Ihrer Suchplugin-XML-Datei vorliegt, können Sie beim Hinzufügen eines entdeckten Plugins auf Fehler stoßen. Wenn die Fehlermeldung nicht hilfreich ist, könnten die folgenden Tipps Ihnen helfen, das Problem zu finden.

  • Ihr Server sollte OpenSearch-Plugins mit Content-Type: application/opensearchdescription+xml bereitstellen.
  • Stellen Sie sicher, dass Ihre Suchplugin-XML richtig formatiert ist. Sie können dies überprüfen, indem Sie die Datei direkt in Firefox laden. Kaufmännische Und-Zeichen (&) in der template-URL müssen als &amp; maskiert werden, und Tags müssen mit einem abschließenden Schrägstrich oder einem passenden End-Tag geschlossen werden.
  • Das xmlns-Attribut ist wichtig — ohne es könnten Sie die Fehlermeldung "Firefox konnte das Such-Plugin nicht herunterladen" erhalten.
  • Sie müssen eine text/html-URL einschließen — Such-Plugins, die nur Atom- oder RSS-URL-Typen beinhalten (was gültig, jedoch von Firefox nicht unterstützt wird), erzeugen ebenfalls die Fehlermeldung "konnte das Such-Plugin nicht herunterladen".
  • Remote abgerufene Favicons dürfen nicht größer als 10KB sein (siehe Firefox Bug 361923).

Zusätzlich bietet der Suchplugin-Dienst einen Protokollierungsmechanismus, der für Plugin-Entwickler nützlich sein kann. Verwenden Sie about:config, um die Voreinstellung browser.search.log auf true zu setzen. Dann werden Protokollinformationen in der Browser-Konsole von Firefox angezeigt (Werkzeuge ➤ Browser-Werkzeuge ➤ Browser-Konsole), wenn Such-Plugins hinzugefügt werden.

Referenzmaterial