これまで、4回にわたりCordovaプラグインを理解するための説明を行いました。過去4回の説明については、以下を参照していください。

上記の説明では、Cordovaプラグインを管理するためのPlugmanというツールで作成できる雛形のCordovaプラグインを使用したため、Cordovaプラグインの設定については、最小限の設定になっています。

基本的に、Cordovaプラグインの設定は、plugin.xmlで行います。今回は、Cordovaコミュニティーが提供しているCordovaプラグインを参考に、利用頻度が高いplugin.xmlの設定について説明していきたいと思います。

plugin.xmlで利用できる設定については、以下を参照してください。

Plugin.xml API

<engines> 要素

<engines> 要素では、Cordovaが提供しているフレームワークのバージョンを指定することで、Cordovaプラグインをインストールする対象を指定する事ができます。<engines> 要素を利用する場合は、子要素として<engine> 要素が必要になります。

cordova-plugin-camera@8.0.0のplugin.xmlでは、以下の<engines> 要素が設定されています。

<engines>
    <engine name="cordova" version=">=9.0.0"/>
    <engine name="cordova-android" version=">=12.0.0" />
    <engine name="cordova-ios" version=">=5.1.0" />
</engines>

Monacaプロジェクトをビルドした際に、<engines> 要素の設定を満たしていない場合は、以下のようなビルドエラーが出力されます。

Discovered saved plugin "cordova-plugin-camera". Adding it to the project
Installing "cordova-plugin-camera" for android
Plugin doesn't support this project's cordova-android version. cordova-android: 8.0.0, failed version requirement: >=12.0.0
Skipping 'cordova-plugin-camera' for android

<preference> 要素

<preference> 要素では、plugin.xml内で使用できる変数を作成する事ができます。cordova-plugin-geolocation@5.0.0のplugin.xmlでは、以下の<preference> 要素が設定されています。default属性を指定することで、デフォルト値を設定する事ができます。

<preference name="GPS_REQUIRED" default="true"/>

<preference> 要素で指定した変数を利用する場合は、Cordovaプラグインをインストールする際に、下記のvariableオプションで指定します。

cordova plugin add cordova-plugin-geolocation --variable GPS_REQUIRED="false"

Monacaプロジェクトでcordova-plugin-geolocationのvariableオプションを指定する場合は、MonacaクラウドIDEのメニュー、

設定>Cordovaプラグインの管理>有効なプラグイン>cordova-plugin-geolocation

の設定画面を開き、インストールパラメータ項目に、

GPS_REQUIRED=false

を入力し、OKボタンをクリックします。

plugin.xml内では、$PREFERENCE_NAMEという構文を使用して参照する事ができます。cordova-plugin-geolocation@5.0.0のplugin.xmlでは、以下のように設定されています。

<uses-feature android:name="android.hardware.location.gps" android:required="$GPS_REQUIRED" />

<dependency> 要素

<dependency> 要素では、Cordovaプラグインが依存する他のCordovaプラグインを指定できます。

cordova-plugin-media@7.0.0のplugin.xmlでは、以下の<dependency> 要素が設定されています。

<dependency id="cordova-plugin-file" version="^8.0.0" />

設定内容から、cordova-plugin-media@7.0.0では、依存するCordovaプラグインとして、cordova-plugin-fileのバージョン8系が指定されています。cordova-plugin-media@7.0.0がインストールされる際には、cordova-plugin-fileのバージョン8系の最新版もインストールされます。

注意点として、ビルド時のCordovaプラグインのインストールの順番は、Monacaプロジェクトに有効またはインポートされたCordovaプラグインの順番でインストールされます。

そのため、cordova-plugin-media@7.0.0を有効にする前に、cordova-plugin-file@7.0.0を有効にした場合は、ビルド時にバージョンの競合が発生し、以下のようなビルドエラーが発生します。

Adding cordova-plugin-file to package.json
Discovered plugin "cordova-plugin-media". Adding it to the project
Installing "cordova-plugin-media" for android
Failed to install 'cordova-plugin-media': CordovaError: Version of installed plugin: "cordova-plugin-file@7.0.0" does not satisfy dependency plugin requirement "cordova-plugin-file@^8.0.0". Try --force to use installed plugin as dependency.
    at /root/.nvm/versions/node/v18.16.1/lib/node_modules/cordova/node_modules/cordova-lib/src/plugman/install.js:526:43
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
Version of installed plugin: "cordova-plugin-file@7.0.0" does not satisfy dependency plugin requirement "cordova-plugin-file@^8.0.0". Try --force to use installed plugin as dependency.

ビルドエラーを解消する場合は、cordova-plugin-file@7.0.0を無効にします。

<framework> 要素

<framework> 要素では、Cordovaプラグインが依存するフレームワークを指定できます。<framework> 要素で依存するフレームワークを指定する際に、バージョンも一緒に指定されているケースがあります。

cordova-plugin-camera@8.0.0のplugin.xmlでは、以下の<framework> 要素が設定されています。

<preference name="ANDROIDX_CORE_VERSION" default="1.6.+"/>
<framework src="androidx.core:core:$ANDROIDX_CORE_VERSION" />

cordova-plugin-camera@8.0.0では、<preference> 要素のANDROIDX_CORE_VERSIONがバージョンに設定されているため、利用者側で任意のバージョンが指定できる形になっています。

Androidで<framework> 要素を使用する場合、以下のようにcustom属性、type属性を指定することで、src属性で指定したgradleファイルを使用して設定を行うこともできます。

<framework src="relative/path/rules.gradle" custom="true" type="gradleReference" />

おわりに

今回は、利用頻度が高いplugin.xmlの設定について説明しました。

Cordovaプラグインを理解しよう（plugin.xml 設定編）

で説明した内容と今回説明した内容を理解することで、数多く公開されているサードパーティー製Cordovaプラグインのplugin.xmlの設定内容を理解できるようになると思います。

Cordovaプラグインは、ネイティブ機能を利用する際には、必須のツールになります。今回の説明を機に、plugin.xmlの設定について理解を深めてください。

Cordovaプラグインを設定しよう（plugin.xml 編）

<engines> 要素

<preference> 要素

<dependency> 要素

<framework> 要素

おわりに

関連