Install Manifests

はじめに

インストールマニフェスト (Install Manifest) はアドオンの使えるXULアプリケーションで、アドオンがアプリケーションにインストールされる必要な情報を持っています。例えば、アドオンを特定するための ID や、作成者名などの情報、適合バージョン、アドオン自身のバージョンなどを含んでいます。

インストールマニフェストの形式は RDF/XML です。

ファイル名は必ず install.rdf とし、XPIファイル(パッケージ)の最上位(直下)におきます。

レイアウト

基本的なインストールマニフェストは下記のようになってます:

<?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">
    <!-- properties -->
  </Description>
</RDF>

プロパティには必須項目とオプション項目があります。また、プロパティに設定する値には単純に文字列を配置するものと、決められたものを設定するものがあります。

必須のプロパティ

インストールマニフェストには以下の必ず設定しなくてはならないプロパティがあります。以下の項目を正しく設定しないと、アドオンがインストールされないので注意が必要です。

id

アドオンの id :

• Firefox 1.0: GUID (Windowsは guidgen で生成/ Unixは uuidgen で生成)
• Firefox 1.5 以降: [email protected] のようなフォーマット

後者の id は作りやすく、扱いやすいです。Firefox 1.5は id が正しいかを判定し、不正なid（フォーマットに合致しない id ）の場合はインストールを行いません。

例

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

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

version

アドオンのバージョン情報を記述します。

例

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

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

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

Firefox/Thunderbird 1.0 - Extension Versioning, Update and Compatibility で決められた形式に従わなくてはなりません。 Firefox/Thunderbird 1.5 / XULRunner 1.8 - Toolkit version format に沿うようにしてください。正しいバージョン名を記述しない場合はインストールされません。また、Firefox 1.0 などで用いた記述方式はサポートされていません。 addons.mozilla.org - Mozilla のアップデートサイトではアドオンを再パッケージするため、バージョン情報を校正したり、不正なバージョン情報を拒否したりするかもしれません。

type

追加機能の種類を下記の数値で表します。

例(拡張機能の場合)

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

このプロパティは Firefox 1.5 で追加されました。なお、拡張機能/テーマ以外の場合は必ず記述しなくてはなりません。

Firefox 2 およびそれ以前のバージョンは、「プラグイン」を示すために 16 という値をサポートしていました。Firefox 3 ではこの機能は取り除かれました。

targetApplication

拡張の対象となる(拡張も含む)アプリケーションを指定します。 アドオンが動くアプリケーション(ターゲットアプリケーション)を下記のプロパティにより限定します。

• ターゲットアプリケーションのidプロパティ(<em:id>)

包括的なアプリケーションIDのリストは Mozilla Addons FAQ の "Valid App Versions for Addon Developers" に記述されています。

• 特定のバージョン以降を指定するminVersionプロパティ (<em:minVersion>)
• 特定のバージョン以前を指定するmaxVersionプロパティ (<em:maxVersion>)

minVersion および maxVersion の値はversion プロパティと同じフォーマットで記述します。アプリケーションはこれらの値を元にインストールできるかを判断されます。これにより、配布者はこのプロパティによりテストに適合したものを提供することができます。

ノート: Firefox 1.0-1.0.6 では共通のバージョンが 1.0 となります。 Firefox 1.5 でのセキュリティアップデートや安定性向上のためのアップデートでのバージョンは 1.5.0.1, 1.5.0.2, などとなります。 アドオンの対応バージョンをFirefox/Thunderbird 1.5とする場合は maxVersion を 1.5.0.* とします。

インストールマニフェストは上記のプロパティの最低1つを指定しなくてはなりません。(特にアドオンマネージャを搭載する Firefox / Thunderbird について)アドオンの対応するアプリケーションが複数ある場合はさらに指定しなくてはなりません。

例

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

Gecko 1.9 ベースのアプリケーションでは、ツールキットのバージョンが指定された minVersion と maxVersion にマッチしているすべてのツールキットアプリケーションに対して互換性があることを示すための特殊な targetApplication の id として、[email protected]が利用できます。

name

UI(アドオン一覧)に表示される名前。

例

<em:name>My Extension</em:name>

オプションのプロパティ

必要であれば、下記のプロパティを記述します。

bootstrap

A Boolean value that tells the application whether the extension is boot-strappable. At the moment this only works for add-ons with em:type="2". The default value is false. For more information, see Bootstrapped extensions.

unpack

A true or false value that tells the application whether the extension requires its files be unpacked into a directory in order to work or whether the extension can be loaded direct from the XPI. In versions before Gecko 2.0 all extensions were unpacked, in Gecko 2.0 and later the default is to not unpack. If an extension includes the following then it must request unpacking:

• Binary XPCOM components
• Plugins
• Search plugins
• DLLs loaded with ctypes
• Dictionaries
• Window icons

Examples

<Description about="urn:mozilla:install-manifest">
   <em:id>[email protected]</em:id>
   <em:unpack>true</em:unpack>
   ...
</Description>

localized

アドオンの名前、説明文、貢献者名、その他のメタデータをローカライズすることができます。ローカライズされた説明文は、どの言語においてその情報を使うのかを示す最低一つの em:locale を含んでいなければなりません。

例

この例は、アプリケーションが de-DE のロケール設定で起動している際に表示されるアドオンのメタデータのセットを示すものです。

<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>

このページもしくは他の箇所で説明されている、以下のプロパティを、localized プロパティの中に含めることができます。

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

より詳しい情報については拡張機能のローカライズを参照してください。

description

UI (アドオン一覧)に表示される説明。持っている機能を説明するのに用いられます。表示領域が狭いため、短く記述したほうが良いでしょう。

例

<em:description>Advanced foo tools.</em:description>

creator

作成者/メインプログラマの名前。アドオンの情報に表示されます。

例

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

もしくは

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

developer

開発者の名前。複数の名前を記述することができます。 Firefox 2.0での新機能です。

例

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

translator

翻訳者(ロケール作成者)の名前。複数の名前を記述することができます。 Firefox 2.0 での新機能です。

例

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

contributor

寄付者/貢献者の名前。複数の名前を記述することができます。

例

<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

アドオンのホームページアドレス。アドオンの情報からアクセスできます。

例

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

updateURL

拡張を更新するためのアップデートマニフェストファイルへのリンク(URL)。このプロパティを定義した場合、拡張マネージャが定期的に更新がないかを自動的にチェックします。

Gecko 1.9 ベースのアプリケーションではセキュリティ上の理由から、updateURL に https の URL を指定するか、もしくは updateKey を含める必要があります。

更新を提供するサーバは必ず text/rdf 形式で送信を行うようにしてください。text/xml 形式でも可能のようです(mozdev.org プロジェクトはそのように設定されている)

アドオンマネージャは以下に示す部分に値を入れて、PHP や CGI で RDF を動的に生成する手助けをします。

例

<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>

addons.mozilla.org: Mozilla のアップデートサイトを利用する場合は updateURL プロパティを指定しなくてもいいでしょう。 アドオンマネージャを使っている Firefox や Thunderbird などの Mozilla アプリケーションはデフォルトで addons.mozilla.org に更新がないかを問い合わせます。新しいバージョンのアドオンをアップデートサイトにアップロードするたびに自動的にこのプロパティを更新/追加を行います。

アップデートマニフェストのフォーマット: アップデートマニフェスト Update Manifest は RDF/XML 形式です。詳細は右のリンクを辿ってってください。アップデートマニフェストのサンプルは Extension Versioning, Update and Compatibility / Enabling Extension Updates (external) を参照してください。

updateKey

通常の http 通信を通じて取得された更新情報の RDF データのセキュリティを保証するために、あなたはデータの内容を検証するための電子署名を使わなくてはなりません。そのため、あなたは暗号鍵の公開鍵をアドオンの install.rdf の updateKey エントリに含める必要があります。これは McCoy というツールを使うことで生成できます。このエントリ中の改行や空白文字はすべて無視されます。

例

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

optionsURL

オプションダイアログの chrome:// URL を指定してください。このオプションは拡張機能のインストールマニフェストでしか有効になりません。このプロパティが設定されていると、拡張機能一覧のコンテキストメニュー(右クリックメニュー)から設定(オプション)ダイアログを開くことができるようになります。

例

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

aboutURL

説明ダイアログの chrome:// URL を指定してください。このオプションは拡張機能のインストールマニフェストでしか有効になりません。このプロパティが設定されていると、拡張機能一覧のコンテキストメニュー(右クリックメニュー)から説明ダイアログを開くことができるようになります。指定しない場合は、デフォルトのダイアログが表示されます。

例

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

The type of user-interface used for displaying the options. Accepted values are:

optionsType defaults to 1 if there is an optionsURL included in install.rdf or 2 if there is no optionsURL and the file options.xul exists in the root of the add-on.

<em:optionsType>2</em:optionsType>

iconURL

アドオン一覧に表示するアイコン(32x32)の chrome:// URL を指定します。指定しない場合はアプリケーションのデフォルトのアイコンが使われます。

例

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

A chrome:// URL to a 64x64 pixel icon to display in the add-on's details view . If this property is not specified, the smaller icon above will be used.

<em:icon64URL>chrome://myext/skin/icon64.png</em:icon64URL>

アドオンが対応する OS (プラットフォーム)を指定します。OS_TARGET の値のみ もしくは OS_TARGET の値 と TARGET_XPCOM_ABI の値を _ (アンダーコア)で繋げた文字列を指定します。

OS_TARGET の値は 普通コマンドライン上で 'uname -s' と入力し、帰ってきた値を記述します。例えば、以下のようになります:

• WINNT Windows NT, 2000, XP 以降
• Linux すべての Linux
• Darwin すべての MacOS X

個々のマニフェストファイルにより複数の targetPlatform プロパティを指定することができます。複数のうちどれかの値が条件を満たす場合はアドオンがインストールされます。逆に、どれも条件を満たさない場合はインストールされません。インストールされない場合はその旨の警告が表示されます。

例

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

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

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

普通は、特定のOSにのみ対応しているテーマや拡張のためにこの属性のみを使うでしょう。(コンパイルされた)バイナリデータを含む拡張のために、この属性のみならず、コンパイルした ABI (s) も含んでください。複数のバージョンのバイナリを同封したい場合は Platform-specific Subdirectories も利用してください。

ノート

• 同じマニフェストファイルで、ABIを含む値と含まない値を一緒に使うことができるかもしれません。あるアプリケーションのOSに対する値が特定のABIを含んだものにヒットした場合、ABIはOSとABIの組み合わせが一致しないときにアドオンをインストールしないことを重要だと判断します。
• ABIがわからない Firefox / Thunderbird が存在することがあります。(希少なプラットフォームや正規版でないもの) そのような環境で、アドオンがプラットフォームについて詳細なABIを要求するときはインストールされません。

Firefox 1.5 このプロパティは Firefox/Thunderbird 1.5 で追加されました。以前のバージョンではこれらの制限を無視し、どのOSに対してもインストールを行ってしまいます。

A Boolean value indicating if the add-on should be enabled when the version of the application is greater than its max version. By default, the value of this property is false meaning that the compatibility checking will not be performed against the max version.

<em:strictCompatibility>true</em:strictCompatibility>

Usually, there is no need to restrict the compatibility: not all new releases will break your extension and, if it is hosted on AMO, you'll get notice several weeks in advance if a potential risk has been detected. Moreover, an extension being disabled, even for a short period, leads to a bad experience for the user. About the only time you should need to set this if your add-on does things that are likely to be broken by Firefox updates. You do not need to set this flag if your add-on has a binary component, since add-ons with binary components are always subject to strict compatibility checking (because binary components need to be rebuilt for every major application release anyway).

廃止されたプロパティ リファレンス

以下のリファレンスはアドオンマネージャの古いバージョンで必須とされていたプロパティです。最新環境ではこれらのプロパティは一新されさらに良い構成となっています。

file

Firefox 1.0 This property pointed to a chrome .jar file that contains chrome packages that require registration with the Chrome Registry.

The <em:file> property has a complex object value. The uri of the value is urn:mozilla:extension:file:jarFile.jar where jarFile.jar is the name of the jar file that contains the chrome package's files. This could also be the name of a directory that contains the chrome package's files, un-jarred (e.g. urn:mozilla:extension:file:directory).

This object has a package property (with a path within the jar file or directory that leads to the location where the contents.rdf file responsible for registering that package is located), a locale property (ditto, but to register the locale) and a skin property (ditto, but to register the theme material).

In extensions for Firefox 1.5, this property is no longer necessary: the chrome.manifest at the top level of the XPI is used to locate chrome to register. If there is no chrome.manifest, this property is still read by the Addon Manager and a chrome.manifest is generated from old-style contents.rdf.

例

<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>

An Install Manifest may specify multiple file properties, one for each jar file or subdirectory that contains chrome to register.

hidden

Firefox 1.0 - 3.5 A boolean value that when true makes the add-on not show up in the add-ons list, provided the add-on is installed in a restricted access area (so it does not work for add-ons installed in the profile). This is for bundling integration hooks to larger applications where having an entry in the Extensions list does not make sense.

アドオン一覧に表示するかどうかを真偽値で設定します。値には true/false を設定します。true が設定されている場合はアドオン一覧に表示されません。アドオンがアクセスが制限された領域にインストールされる場合に設定します。（よって、プロファイルにインストールされるアドオンに対しては効果がありません。）これは、アドオンが一覧に表示されては困る大きなアプリケーションのフックの統合のためにあります。指定しない場合はfalseが設定されます。

例

Examples

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

requires

Firefox 2.0 - 3.6.x. Other versions will ignore the restrictions and install the add-on regardless of the requirements.

See Replacement for install.rdf property "requires" discussion for rationale behind removing this feature and the suggested workaround.

<em:requires> has a similar syntax to the <em:targetApplication> tag (i.e. you must specify <em:id>, <em:minVersion>, <em:maxVersion> when using it). If the add-on specified by the <em:id> tag is not installed or has an incompatible version, the extension manager will disable your extension and show the message "Requires additional items". You can add as many <em:requires> tags as you like. Your extension will be disabled if any of the specified requirements fail. It is not possible to add dependencies that are specific to a <em:targetApplication>. See Extension Dependencies for more details.

このタグは<em:targetApplication>と似た文法を持っています。もし<em:id>タグによって示されたアドオンがインストールされていないか、もしくは非対応のバージョンである場合、拡張機能マネージャはあなたの拡張機能を無効にし、「追加の項目が必要です」というメッセージを表示するでしょう。あなたは複数の<em:requires> タグを好きなだけ追加することができます。指定された条件が一つでも満たされていなければ、あなたの拡張機能は無効化されます。

例

<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>

註

• 現在は、<em:requires>タグの中では<em:id>, <em:minVersion>, <em:maxVersion>だけが解釈されます。
• 今の所、<em:targetApplication>によって依存関係を表現することはできません。詳しい情報については拡張機能の依存関係を参照してください。

このプロパティは Firefox / Thunderbird 2 のために追加されました。これらのアプリケーションの以前のバージョンは、制限事項を無視して、指定された条件とは無関係にアドオンをインストールするでしょう。

用語集

アクセスが制限された領域

アクセスが制限された領域とは、アクセスが制限されたアカウントにおいて、現在のユーザの特権（nsIInstallLocation::restrictedを参照）によって制限されているかどうかにかかわらずその場所へアクセスできないかもしれないインストール場所のことです。 現在の所、($APPDIR)/extensionsフォルダと、HKEY_LOCAL_MACHINE以下に登録されたインストール場所（詳細はWindowsのレジストリを使って拡張機能を追加するを参照してください）が制限されます。

他方で、($PROFILE)/extensionsとHKEY_CURRENT_USERに登録されたインストール場所については制限されません。

追加情報

• install.rdf page on the MozillaZine KB を参照するとさらなる情報や、サンプルを入手することができます