Installationsmanifest

Einführung

Ein Installationsmanifest ist eine Datei, die von einer XUL-Anwendung mit einem Add-on Manager benutzt wird, um Information über das zu installierende Add-on zu erhalten. Es enthält Metadaten zur Identifikation des Add-ons und gibt Auskunft darüber, wer es erstellt hat, wo weiterführende Informationen zu finden sind, welche Versionen mit welcher Anwendung kompatibel ist, wie das Add-on zu aktualisieren ist, usw.

Das Format eines Installationsmanifests ist RDF/XML.

Die Datei muss den Namen install.rdf haben und sich auf der obersten Verzeichnisebene in der XPI-Datei eines Add-ons befinden.

Aufbau

Der grundlegende Aufbau eines Installationsmanifests sieht folgendermaßen aus:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <!-- Eigenschaften -->
  </Description>
</RDF>

Einige Eigenschaften sind erforderlich, andere sind optional. Einige sind einfache Zeichenketten, während andere komplexe Ressourcen sind.

Referenz erforderlicher Eigenschaften

Diese Eigenschaften müssen in Ihrem Installationsmanifest korrekt angegeben werden, andernfalls wird Ihr Add-on eventuell nicht installiert.

id

Die ID der Erweiterung, nämlich entweder eine:

• GUID (Firefox 1.0)
• Eine Zeichenkette folgender Form: [email protected]

Letztere Form ist deutlich einfacher zu erzeugen und zu verändern. Firefox 1.5 ist in der Lage sicherzustellen, dass Ihre ID dem einen oder anderen Format entspricht und wird die Installation eines Add-ons verweigern, sollte die ID nicht wohlgeformt sein.

Beispiele

<em:id>[email protected]</em:id>

<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

version

Eine Zeichenkette, welche die Version des vorliegendenAdd-ons angibt.

Für Firefox/Thunderbird 1.0 muss das Format den Regeln genügen, die in "Versionen, Aktualisierung und Kompatibilität von Add-ons" beschrieben sind.
Für Firefox/Thunderbird 1.5, siehe Toolkit Versionsformate.

Beispiele

<em:version>2.0</em:version>

<em:version>1.0.2</em:version>

<em:version>0.4.1.2005090112</em:version>

Firefox 1.5 / XULRunner 1.8 - Add-ons mit einem ungültigen Versionsformat werden nicht installiert. Das Format unterscheidet sich vom 1.0er, ist jedoch dazu abwärtskompatibel.

Für auf addons.mozilla.org bereitgestellte Add-ons - Mozillas Aktualisierungswebseite verpackt Ihr Add-on möglicherweise neu und berichtigt Versionszeichenketten oder weist sie zurück.

type

Ein ganzzahliger Wert, der für den Typ des Add-ons steht.

Beispiele

<em:type>2</em:type>

Diese Eigenschaft wurde in Firefox 1.5 hinzugefügt und ist nur erforderlich für Add-on Typen, die keine Erweiterungen und Themen sind.

Firefox 2 und früher unterstützen einen Wert von "16", welcher Plug-ins repräsentierte. In Firefox 3 wurde dies entfernt.

targetApplication

Ein Objekt, welches eine Ziel-Applikation des Add-ons festlegt. Das bedeutet, dass das Add-on mit der Anwendung arbeitet, welche mit der ID Eigenschaft (<em:id>) festgelegt wurde (eine Liste von Anwendungs-IDs und gültigen min/maxVersions für diese, siehe Valid application versions for add-on developers[engl.]) und welche der minimalen Version (<em:minVersion>) bis und einschließlich der maximalen Version (<em:maxVersion>) entspricht. Diese Versionsangaben sind in der gleichen Weise formatiert, wie auch die version Eigenschaft und wird mit der Anwendungsversion verglichen. Das erlaubt dem Erweiterungsautor, festzulegen, welche Version von Firefox getestet wurde.

Das Installationsmanifest muss wenigsten eine dieser Objekte festlegen und kann weitere festlegen, wenn das Add-on auf mehrere Anwendungen zielt, die der Add-on Manager unterstützt (z.B. Firefox and Thunderbird).

Beispiele

<em:targetApplication>
 <Description>
  <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> Firefox
  <em:minVersion>1.5</em:minVersion>
  <em:maxVersion>3.0.*</em:maxVersion>
 </Description>
</em:targetApplication>

Auf Gecko 1.9 basierte Anwendungen erlauben Ihnen eine spezielle targetApplication ID [email protected] zu verwenden, um auszudrücken, dass das Add-on kompatibel mit jeder Toolkit-Anwendung ist, die auf die minVersion und maxVersion passt.

name

Der Name des Add-ons - vorgesehen für die Anzeige auf der Benutzeroberfläche.

Beispiele

<em:name>Meine Erweiterung</em:name>

Referenz optionaler Eigenschaften

Abhängig von den Fähigkeiten Ihres Add-ons müssen diese Eigenschaften gegebenenfalls angegeben werden.

bootstrap

Ein boolescher Wert, welcher der Anwendung mitteilt, ob die Erweiterung ohne Neustart installiert, deinstalliert oder aktualisiert werden kann. Das funktioniert zur Zeit nur für Add-ons mit em:type="2". Der Standardwert ist false. Für weitere Informationen, siehe Bootstrapped Extensions.

unpack

Ein boolescher Wert, welcher angibt, ob die Erweiterung es erfordert, dass die ihre Dateien in ein Verzeichnis entpackt werden müssen, damit diese funktioniert oder ob die Erweiterung direkt vom XPI geladen werden kann. In Versionen vor Gecko 2.0 werden alle Erweiterungen entpackt, in Gecko 2.0 und später wird standardmäßig nicht entpackt. Falls eine Erweiterung folgendes enthält, muss diese entpackt werden:

• Binäre XPCOM Komponenten
• DLLs von ctypes geladen
• Suchplugins
• Wörterbücher
• Fenster-Icons

localized

Den Namen, die Beschreibung, die Namen von Mitwirkenden und weitere Metadaten können Sie hiermit sprachlich anpassen. Mindestens ein em:locale muss von der angepassten Beschreibung spezifiziert werden, um anzuzeigen für welche Sprachregionen die Information genutzt werden soll.

Beispiele

Dies legt ein Reihe von Add-on Metadaten fest, die angezeigt werden, wenn die Anwendung im de-DE Sprachpaket läuft.

<em:localized>
  <Description>
    <em:locale>de-DE</em:locale>
    <em:name>Tab Sidebar</em:name>
    <em:description>Zeigt in einer Sidebar Vorschaubilder der Inhalte aller offenen Tabs an.</em:description>
  </Description>
</em:localized>

Die folgenden Eigenschaften, die auch auf dieser Seite genannt werden, können in die Eigenschaft "localized" eingefügt werden:

• name
• description
• creator
• homepageURL
• developer
• translator
• contributor

Weitere Dokumentation lässt sich unter Lokalisierung von Erweiterungsbeschreibungen finden.

description

Eine Kurzbeschreibung des Add-ons - vorgesehen für die Anzeige auf der Benutzeroberfläche. Die Beschreibung sollte in einer kurzen Textzeile Platz finden.

Beispiele

MegaInternetPhoneCall;em:description>Fortgeschrittene foo-Werkzeuge.</em:description>

creator

Der Name des Erstellers/Hauptentwicklers - vorgesehen für die Anzeige auf der Benutzeroberfläche.

Beispiele

<em:creator>John Doe</em:creator>

oder

<em:creator>CoolExtension Team</em:creator>

developer

Entwicklername(n). Sie können diesen Wert mehrfach angeben, um die Namen mehrerer Entwickler anzugeben.

Beispiele

<em:developer>Jane Doe</em:developer>
<em:developer>Koos van der Merwe</em:developer>

translator

Übersetzername(n). Sie können diesen Wert mehrfach angeben, um die Namen mehrerer Übersetzer anzugeben.

Beispiele

<em:translator>Janez Novak</em:translator>
<em:translator>Kari Nordmann</em:translator>

contributor

Name(n) zusätzliche(r) Mitwirkende(r). Sie können diesen Wert mehrfach angeben, um die Namen mehrerer Mitwirkender anzugeben.

Beispiele

<em:contributor>John Doe</em:contributor>

<em:contributor>John Doe</em:contributor>
<em:contributor>Jane Doe</em:contributor>
<em:contributor>Elvis Presley</em:contributor>

homepageURL

Eine Verknüpfung zur Seite des Zusatzes - vorgesehen für die Anzeige auf der Benutzeroberfläche.

Beispiele

<em:homepageURL>https://www.foo.com/</em:homepageURL>

updateURL

Ein Link zu einer Aktualisierungsdatei des Manifests, welches verfügbare Updates für das Add-on festlegt. Das Format ist unten beschrieben. Wenn aktiviert, überprüft der Add-on Manager regelmäßig diese Manifestdatei, um festzustellen, ob neuere Versionen verfügbar sind.

Aus Sicherheitsgründen erfordern Gecko 1.9 Anwendungen, dass Sie eine HTTPS updateURL oder einen updateKeyangeben müssen.

Ihr Server muss diese Datei als text/rdf, text/xml oder application/xml+rdf ausliefern, sonst funktioniert der Update-Checker nicht.

Der Add-on Manager wird die folgenden Werte in der URLersetzen, falls Sie das RDF dynamisch generieren wollen, z.B. mit PHP oder CGI:

Beispiele

<em:updateURL>https://www.foo.com/update.cgi?id=%ITEM_ID%&amp;version=%ITEM_VERSION%</em:updateURL>
<em:updateURL>https://www.foo.com/extension/windows.rdf</em:updateURL>

Für Add-ons, die auf addons.mozilla.org bereitgestellt werden: Sie müssen keine updateURL Eigenschaft angeben. Standardmäßig werden Mozilla Applikationen über den Addon Manager (wie Firefox und Thunderbird) automatisch Anfragen an addons.mozilla.org senden. Jedes Mal, wenn Sie eine neue Version Ihres Add-ons hochladen oder die Kompatibilitätsparameter ändern, wird Ihr Update-Manifest automatisch generiert. Add-ons, die aktuell als experimental markiert sind, werden aus Gründen der Sicherheit nicht aktualisiert.

Format des Update-Manifests: Das Update-Manifest ist eine RDF/XML Datenquelle. Beispiele eines Update-Manifests, siehe Versionen, Aktualisierung und Kompatibilität von Add-ons.

updateKey

Um die Sicherheit eines Updates von RDF Daten zu gewährleisten, welches über HTTP empfangen wird, müssen Sie eine digitale Signatur, um die Inhalte der Daten zu verifizieren, hinzufügen. Um dies zu machen, müssen Sie den öffentlichen Teil des kryptographischen Schlüssel in einem updateKey in der install.rdf Datei des Add-ons notieren. Dieser kann über ein Tool generiert werden: McCoy. Zeilenumbrüche und Leerzeichen werden ignoriert.

Beispiele

 <em:updateKey>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj
               Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD
               NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf
               awB/zH4KaPiY3vnrzQIDAQAB</em:updateKey>

optionsURL

Die chrome:// URL des Dialogfensters für die Optionen der Erweiterung. Nur für Erweiterungen von Nutzen. Sofern diese Eigenschaft angegeben ist, wird bei Auswahl dieser Erweiterung in der Erweiterungsliste die Schaltfläche "Einstellungen" auswählbar, welche auf Klick hin dieses Dialogfenster anzeigt.

Beispiele

<em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>

aboutURL

Die chrome://-URL des Dialogfensters für Information über die Erweiterung. Nur für Erweiterungen von Nutzen. Sofern diese Eigenschaft angegeben ist, wird bei Auswahl dieser Erweiterung in der Erweiterungsliste ein entsprechender Eintrag im Kontextmenü der Erweiterung verfügbar, welcher auf Auswahl hin dieses Dialogfenster statt einer vorgegebenen Variante anzeigt.

Beispiele

<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>

iconURL

Eine chrome:// URL zu einem 32x32 Icon, welches in der Add-on List angezeigt wird. Wird diese Eigenschaft nicht angegeben, wird das Standardicon verwendet.

<em:iconURL>chrome://myext/skin/icon.png</em:iconURL>

targetPlatform

Eine Zeichenkette, welche die Plattform angibt, die vom Add-on unterstützt wird. Enthält entweder den Wert von OS_TARGET allein oder in Kombination mit TARGET_XPCOM_ABI, getrennt durch einen Unterstrich (_).

Sie können die Eigenschaft targetPlatform je Manifest mehrfach angeben. Passt einer der Werte zu den Parametern, mit denen die Anwendung gebaut wurde, wird das Add-on installiert; anderenfalls erhält der Benutzer eine entsprechende Fehlermeldung.

Beispiele

<em:targetPlatform>WINNT_x86-msvc</em:targetPlatform>

<em:targetPlatform>Linux</em:targetPlatform>

<em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>

<em:targetPlatform>SunOS_sparc-sunc</em:targetPlatform>

Normalerweise verwenden Sie nur den OS Teil für Themes und Erweiterungen, die nicht komplett System-übergreifend sind. Für Erweiterungen mit binären (kompilierten) Komponenten sollten sie aber niemals das OSalleine sonder mit ABI (s) angeben, mit welchen Sie die Komponenten kompiliert haben. Wenn Sie mehrere Versionen der Komponenten einbinden wollen, sollten Sie Plattform-spezifische Unterverzeichnisse verwenden.

Hinweise

• In der gleichen Manifestdatei, können Sie sogar Werte mit und ohne ABI mischen. Wenn ein Wert für das OS der Anwendung auf ein bestimmtes ABI stoßt, welches wichtig für das OS ist, wird die Anwendung die Installation ablehnen, wenn die gefundene OS/ABI Kombination nicht passt. Das bedeutet, wenn alle obigen Beispiele in einem Manifest auftreten, wird das Add-on auf jedem Linux Build installiert werden, egal welches ABI, aber nicht auf einem Windows Cygwin Build.

• Es gibt Builds von Firefox und Thunderbird, welche ihre ABI nicht "wissen" (seltene Plattformen oder keine offiziellen Builds). Diese Builds werden jede Installation eines Add-ons ablehnen, die eine bestimmtes ABI für ihre Plattform erfordern.

Diese Eigenschaft wurde für Firefox/Thunderbird 1.5 hinzugefügt. Vorherige Versionen dieser Anwendungen werden die Einschränkungen ignorieren und das Add-on ungeachtet der Plattform installieren.

requires

Dieses Tag hat ein ähnliches Syntax wie das <em:targetApplication> Tag. Wenn das Add-on ,von dem <em:id> Tag festgelegt, nicht installiert ist oder eine nicht kompatible Version hat, wird der Erweiterungsmanager die Erweiterung deaktivieren und die Nachricht anzeigen "Erfordert zusätzliche Funktionen". Sie können so viele <em:requires> Tags wie Sie möchten hinzufügen. Ihre Erweiterung wird deaktiviert, wenn eines der festlegten Anforderungen fehlschlägt.

Beispiele

<em:requires>
   <Description>
     <!-- Lightning -->
     <em:id>{e2fda1a4-762b-4020-b5ad-a41df1933103}</em:id>
     <em:minVersion>0.5pre</em:minVersion>
     <em:maxVersion>0.5pre</em:maxVersion>
   </Description>
 </em:requires>

Hinweise

• Aktuell werden nur <em:id>, <em:minVersion> und <em:maxVersion> innerhalb des <em:requires> Tag geparst.
• Es ist zur Zeit nicht möglich Abhängigkeiten zu einem <em:targetApplication> hinzuzufügen. Siehe wikimo:Extension Manager:Extension Dependencies für weitere Details.

Diese Eigenschaft wurde in Firefox/Thunderbird 2 hinzugefügt. Vorherige Versionen dieser Anwendungen werden diese Einschränkungen ignorieren und das Add-on unabhängig von den Anforderungen installieren.

Referenz veralteter Eigenschaften

Diese Eigenschaften waren in alten Versionen des Add-on Managers vorhanden, wurden aber mittlerweile durch neuere und bessere Mechanismen ersetzt.

file

Firefox 1.0 Diese Eigenschaft verwies auf eine chrome .jar Datei, die Chrome-Pakete enthielt, die eine Registrierung mit der Chrome-Registry erforderten.

Die <em:file> Eigenschaft hat einen komplexen Objektwert. Die uri des Wertes ist urn:mozilla:extension:file:jarFile.jar wobei jarFile.jar derName der jar Datei ist, welche die Dateien des Chrome-Pakets enthält. Das könnte auch der Name eines Verzeichnisses sein, welches die Dateien des Chrome-Pakets enthält, un-jarred (z.B. urn:mozilla:extension:file:directory). In beiden Fällen müssen die Chrome Paketdatei(en) in dem chrome Unterverzeichnis des XPI Archivs platziert werden.

Dieses Objekt hat eine package Eigenschaft (mit einem Pfad in der jar Datei oder Verzeichnis, welches zum Ort der contents.rdf Datei führt, um die das Paket zu registrieren), eine locale Eigenschaft (genauso, registriert aber die Sprache) und eine skin Eigenschaft (genauso, aber registriert das Theme-Material).

Bei Erweiterungen für Firefox 1.5, ist diese Eigenschaft nicht länger notwendig: Das chrome.manifest im XPI wird verwendet um die Registrierungsareit zu verrichten. Wenn kein chrome.manifest vorhanden ist, wird diese Eigenschaft vom Addon Manager gelesen und ein chrome.manifest wird generiert.

Beispiele

<em:file>
 <Description about="urn:mozilla:extension:file:myext.jar">
  <em:package>content/myext/</em:package>
  <em:locale>locale/en-US/myext/</em:locale>
  <em:skin>skin/classic/myext/<em:skin>
 </Description>
</em:file>

Ein Installationsmanifest kann mehrere file Eigenschaften festlegen, eine für jede jar Datei oder Unterverzeichnis, welches Chrome zum registrieren enthält.

hidden

Firefox 1.0 - 3.5 Ein boolscher Wert, falls true wird das Add-on nicht in der Add-on Liste angezeigt, vorausgesetzt, dass das Add-on in einer Restricted access area installiert ist. (sodass es nicht für installierte Add-ons im Profil arbeitet).

Beispieie

<em:hidden>true</em:hidden>

Glossar

Restricted access area

Ein restricted access area ist ein Installationort, welcher durch einen restricted-access Account eingeschränkt werden kann, unabhängig ob der Ort mit den aktuellen Benutzerrechten eingeschränkt ist oder nicht (siehe nsIInstallLocation::restricted). Zur Zeit sind die ($APPDIR)/extensions Ordner und die Registry Installationsorte unter HKEY_LOCAL_MACHINE (siehe Erweiterungen über die Windows Registrierung hinzufügen für Details) eingeschränkt

Die ($PROFILE)/extensions und HKEY_CURRENT_USER Installationsorte sind hingegen nicht beschränkt.