Custom Config
Cordova 5.2 以前のバージョンをサポートしていた Monaca フレームワークでは、
AndroidManifest.xml
( Android の場合 ) または MonacaApp-Info.plist
( iOS の場合 ) を編集すれば、アプリのデフォルトの挙動を制御することができました。Cordova 6.2 以降のバージョンをサポートする Monaca フレームワークでは、仕様が変更され、 AndroidManifest.xml
と MonacaApp-Info.plist
のいずれのファイルも使用しなくなりました。このため、最新の Monaca フレームワーク ( Cordova 6.2 以降をサポート ) を使用する場合、iOS または Android アプリの設定をカスタマイズするときには、Custom Config プラグインを使用する必要があります。こちらの Cordova プラグイン ( iOS と Android の両方に使用可 ) を使用すると、フック用のスクリプト ( プラグイン側で提供 ) を経由して、設定ファイルの情報を書き換えることができます。具体的には、
config.xml
ファイル内に、カスタマイズ用の preference または/および config-file ブロックを記述し、このスクリプト経由で、プラットフォーム側の設定に適用します。Cordova 7以降では、Android プロジェクトの構造に後方互換性のない変更が導入されました。 この変更をサポートするために、Custom Config プラグイン v5 がリリースされました。
注意すべき事項は次のとおりです。
- 1.Custom Config プラグイン v5 では、プロジェクトの Android プラットフォームのバージョンを検出し、正しいパスを使用する必要があります。
- 2.
config.xml
でサポートされているすべてのカスタム設定要素には、 Custom Config プラグイン v5 で使用するためのプレフィックスcustom-
を付ける必要があります。<config-file>
=><custom-config-file>
<preference>
=><custom-preference>
<resource>
=><custom-resource>
- これは、Android プラットフォーム v7 が、config.xml 内の
<config-file>
ブロックを解析しようとするためです。Custom Config プラグインが解析する<config-file>
ブロックは、Cordova でも解析されるため、ビルドエラーが発生する可能性があります。(詳細はこちら を参照してください。) - <preference name="cordova-custom-config-autorestore" value="true" />
- Custom Config プラグイン v5 では、Android プラットフォームが v7か、v6(またはそれ以下)かどうかを検出します。
- Android プラットフォーム v6 の場合、デフォルトではプレフィックスのないカスタム設定要素をサポートします。
- Android プラットフォーム v7 の場合、デフォルトではプレフィックスのないカスタム設定要素をサポートしません。
parse_unprefixed
プリファレンスを明示的に設定することによってオーバーライドできます。<preference name="cordova-custom-config-parse_unprefixed" value="true" />
- 1.Monaca クラウド IDE から
設定 → Cordova プラグインの管理
を選択します。 - 2.利用可能なプラグイン 項目の
Custom Config
プラグインにカーソルを置き、有効
ボタンをクリックします。

このプラグインには、実行ファイルのようなものはありません。代わりに、フック用のスクリプトを使用して、各プラットフォームの設定ファイルに対して、
config.xml
ファイル内に設定した preference を適用 ( 上書きまたは追加 ) します。たとえば、iOS の場合、preference の name 属性は、iOS 設定ファイルの key と紐づけされています。よって、このプラグインを使用する場合、カスタマイズに必要な設定 ( preference の name 属性などを使用 ) を、あらかじめ、config.xml
内に記述しておきます。適用処理は、プロジェクトのビルド時に、スクリプト側で行ってくれます。このプラグインを使用し変更した設定ファイルの内容は、原則、元に戻すことができません。ただし、次の preference を使用して、元に戻せるように設定することもできます ( 自動リストア機能、
config.xml
の最上位の <widget>
要素内に追加 )。<preference name="cordova-custom-config-autorestore" value="true" />
preference は、
config.xml
ファイル内で、<preference>
要素を使用し設定します。<custom-preference name="android-launchMode" value="singleTop" />
preference を設定する場合には、次の点に、注意が必要です。
- 1.
<platform>
要素のブロック 「 外 」 に置かれた preferenceは、すべてのプラットフォームに対して適用されます。 - 2.
<platform>
要素のブロック 「 内 」 に置かれた preferenceは、指定されているプラットフォームに対してのみ、適用されます。 - 3.platform 要素のブロック内に置かれている preferenceは、置かれていないものより、優先されます。
- 4.特定のプラットフォーム向けの preferenceは、プラットフォーム名が指定された
<platform>
要素 ( 例 : name="ios-somepref" ) のブロック内に置きます。
<config-file>
ブロックを使用すれば、プラットフォーム別のカスタマイズ設定 ( 群 ) を、ひとまとめにして定義できます ( config.xml
内 )。適用先となるファイルでは、これらのカスタマイズ設定は、XML のサブツリーとして挿入されます。config-file の設定時には、次の点に注意が必要です。
- 1.
<config-file>
要素は、<platform>
要素のブロック内に置きます。これ以外の場合、設定は無視されます。 - 2.config-file 要素の
target
属性には、更新対象のファイルを指定します(AndroidManifest.xml
または*-Info.plist
)。 - 3.config-file の
parent
属性には、親となる要素 ( Androidの場合、AndroidManifest.xml
内 )、または、親となる key ( iOSの場合、*-Info.plist
内 )を指定します。この親の子要素、または、key の valueとして、設定内容が挿入されます。 - 4.
<config-file>
要素に指定された target ( ファイル ) と parent (ファイル内の位置 )の組み合わせを使用して、カスタマイズ設定の適用場所を指定します。 - 5.同一の target と parent 属性が設定された config-fileが複数ある場合、最後の config-file が適用されます。
- 6.config-file 内に定義された要素 (ファイル、適用する箇所、適用する内容 )を使用して、適用先ファイルの内容が上書きされます (または、指定された内容が追加されます )。
- 7.config-file内に定義されている要素が重複している場合、最後に定義されている要素が適用されます。ただし、
<uses-permission>
要素のように、name
属性の設定で一意に識別できる場合を除きます。
Android では、このプラグインを使用してカスタマイズできる対象は、現在、
platforms/android/AndroidManifest.xml
内の設定だけです。Manifest ファイル内の詳細は、アプリ マニフェスト ( 外部サイト ) をご確認ください。なお、Android 向けの設定は、config.xml
ファイルの <platform name="android">
ブロック内に置きます。config.xml
内の <preference>
要素を使用して、AndroidManifest.xml
内の要素に、指定した属性を反映させます。たとえば、config.xml
に、次の要素を追加すると...<custom-preference name="android-manifest/@android:hardwareAccelerated" value="false" />
AndroidManifest.xml
には、次の設定が追加されます。<manifest android:hardwareAccelerated="false">
AndroidManifest.xml
内に定義されているデフォルトの設定を削除する場合には、<preference>
要素に delete="true"
を設定します。たとえば、config.xml
に次の設定を追加した場合、 AndroidManifest.xml
内の <uses-permission android:name="android.permission.WRITE_CONTACTS" />
を削除できます。<custom-preference name="android-manifest/uses-permission/[@android:name='android.permission.WRITE_CONTACTS']" delete="true" />
config.xml
の preference に android:
( 名前空間を指定 ) を指定する場合、 <widget>
要素 ( ルート要素 ) にも、andorid の名前空間を設定する必要があります。名前空間を指定する属性は、次のように記述します。
xmlns:android="http://schemas.android.com/apk/res/android"
<widget>
要素は、次のように記述します。<widget
id="com.my.app"
version="0.0.1"
xmlns="http://www.w3.org/ns/widgets"
xmlns:cdv="http://cordova.apache.org/ns/1.0"
xmlns:android="http://schemas.android.com/apk/res/android">
Android のマニフェストに適用する preference には、XPath も使用できます。preference の name に、要素と属性を XPath 形式で指定して、カスタマイズ設定の適用先を示します。具体的には、preference の name に指定する値に、
android-manifest
を先頭に付け、その後ろに、XPath 形式で要素と属性を指定して、value の値の適用先となる場所を示します。次に例を記します。<custom-preference name="android-manifest/application/activity/@android:launchMode" value="singleTask" />
上記の preference を適用すると、次のように、
launchMode
属性に、singleTask
が設定されます。<activity android:launchMode="singleTask">
manifest 内に、複数の activity が存在する場合、XPath の記述内にも、activity の name を指定します。次に例を記します。
<custom-preference name="android-manifest/application/activity[@android:name='MainActivity']/@android:launchMode" value="singleTask" />
Cordova 4.2.0 以前のバージョンでは、プロジェクトの作成時、activity の name には、
CordovaApp
が使用されていました。Cordova 4.3.0 以降では、 MainActivity
となっています。<manifest>
要素 ( ルート要素 ) 内にある属性を適用先とする場合、要素名は省略して、属性だけを指定します。 例 :<custom-preference name="android-manifest/@android:installLocation" value="auto" />
AndroidManifest.xml
に適用するカスタマイズ設定が複数ある場合は、<config-file>
を使用して定義します。これらのカスタマイズ設定は、AndroidManifest.xml
ファイル内で、XML のサブツリーに変換されます。<config-file>
内の要素は、parent で指定されている要素の下に挿入されます。<config-file>
要素には、次の 2 種類の属性を指定できます。- 1.
target
:AndroidManifest.xml
を常に指定します。 - 2.
parent
: XPath の記法を使用して、AndroidManifest.xml
内の親となる要素を指定します。この要素下に、XML のサブツリーとして、指定された値が挿入されます。<manifest>
要素 ( ルート要素 ) にブロックを挿入する場合には、parent="/*"
を使用します。<manifest>
の子孫ノード下にブロックを挿入する場合には、./
形式の記法も使用できます。たとえば、parent="./application/activity"
を指定した場合、/manifest/application/activity
下に、ブロックが挿入されます。
例 :
<config-file target="AndroidManifest.xml" parent="./application">
<some-element />
</config-file>
AndroidManifest.xml
内では、次のようになります。<manifest ...>
<application ...>
<some-element />
</application>
</manifest>
parent 要素に指定された値が XML のサブツリー側に定義されている値と重複する場合、既存の要素は上書きされます。
例 :
<config-file target="AndroidManifest.xml">
<application android:name="MyApp" />
</config-file>
上記の内容を使用すれば、既存の
<application>
要素が書き換えられます。なお、このような場合には、preference の使用を推奨します。<preference name="android-manifest/application/@android:name" value="MyApp" />
Android 向けの設定のサンプルを、次に記します (
config.xml
ファイル内 )。<platform name="android">
<!-- custom preferences examples -->
<custom-preference name="android-manifest/application/activity/@android:windowSoftInputMode" value="stateVisible" />
<custom-preference name="android-manifest/@android:installLocation" value="auto" />
<custom-preference name="android-manifest/application/@android:hardwareAccelerated" value="false" />
<custom-preference name="android-manifest/@android:hardwareAccelerated" value="false" />
<custom-preference name="android-manifest/application/activity/@android:configChanges" value="orientation" />
<custom-preference name="android-manifest/application/activity/@android:theme" value="@android:style/Theme.Material" />
<!-- specify activity name -->
<custom-preference name="android-manifest/application/activity[@android:name='MainActivity']/@android:launchMode" value="singleTask" />
<!-- Delete an element -->
<custom-preference name="android-manifest/application/activity[@android:name='DeleteMe']" delete="true" />
<!-- These preferences are actually available in Cordova by default although not currently documented -->
<custom-preference name="android-minSdkVersion" value="10" />
<custom-preference name="android-maxSdkVersion" value="22" />
<custom-preference name="android-targetSdkVersion" value="21" />
<!-- Or you can use a custom-config-file element for them -->
<custom-config-file target="AndroidManifest.xml" parent="/*">
<uses-sdk android:maxSdkVersion="22" android:minSdkVersion="10" android:targetSdkVersion="21" />
</custom-config-file>
<!-- custom config example -->
<custom-config-file target="AndroidManifest.xml" parent="/*">
<supports-screens
android:xlargeScreens="false"
android:largeScreens="false"
android:smallScreens="false" />
<uses-permission android:name="android.permission.READ_CONTACTS" android:maxSdkVersion="15" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
</custom-config-file>
<!-- Add (rather than overwrite) a custom-config-file block -->
<custom-config-file target="AndroidManifest.xml" parent="./" mode="add">
<application android:name="customApplication"></application>
</custom-config-file>
</platform>
iOS では、このプラグインを使用してカスタマイズできる対象は、現在、プロジェクトの plist (
*-Info.plist
、config-file ブロックを使用 )、および、設定情報 ( project.pbxproj
、preference 要素を使用 ) です。なお、iOS 向けの設定は、 config.xml
ファイルの <platform name="ios">
ブロック内に置きます。config.xml
の <preference>
要素を使用して、 *-Info.plist
の設定を更新します。preference は、 <preference name="ios-SOME_BLOCK_TYPE-SOME_KEY" value="SOME_VALUE" />
の形式で設定します。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-ENABLE_BITCODE" value="YES" />/>
ビルド設定は、
project.pbxproj
内の XCBuildConfiguration
を使用して、現在行っています。使用する key/value に関しては、制限はありません。XCBuildConfiguration
ブロック内にすでに存在する key を指定した場合、key の value は上書きされます。指定した key がどの XCBuildConfiguration
にも存在しない場合、指定した value とともに、各 XCBuildConfiguration
に key が追加されます。デフォルトでは、Release と Debug の両方の
XCBuildConfiguration
ブロックに value が適用されますが、config.xml
の <preference>
要素に、buildType
属性を追加すれば、ビルドの種類を指定でき、ブロックを絞り込めます。この属性に指定できる値は、debug
または release
です。<custom-preference name="ios-XCBuildConfiguration-IPHONEOS_DEPLOYMENT_TARGET" value="7.0" buildType="release" />
デフォルトでは、
XCBuildConfiguration
への挿入時、key と value は、ダブルクォーテーションで囲われます。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-IPHONEOS_DEPLOYMENT_TARGET" value="7.0" buildType="release" />
project.pbxproj
内では、次のようになります。"IPHONEOS_DEPLOYMENT_TARGET" = "7.0";
クォーテーションの付記方法 ( 上記がデフォルトの仕様 ) は、
<preference>
の quote
属性を使用して、変更できます。この属性には、次の値を使用できます。none
: key と valueのいずれにも、クォーテーションは付記されません。key
: key だけに、クォーテーションが付記されます。value
: value だけに、クォーテーションが付記されます。both
: key と value のいずれにも、クォーテーションが付記されます。
例 :
<custom-preference name="ios-XCBuildConfiguration-IPHONEOS_DEPLOYMENT_TARGET" value="7.0" buildType="release" quote="none" />
project.pbxproj
内では、次のようになります。IPHONEOS_DEPLOYMENT_TARGET = 7.0;
Cordova では、
/platforms/ios/cordova/
の .xcconfig
ファイルを使用して、Xcode プロジェクトの project.pbxproj
ファイル内の設定を上書きします ( ビルドの種類に応じて、適用先の場所が変わります )。また、build.xcconfig
の内容は、build-debug.xcconfig
または build-release.xcconfig
を適用して、上書きされます ( どちらのファイルが使用されるかは、指定したビルドの種類で決まります )。カスタマイズ設定を適用するとき、プラグインは、最初に、buildType 属性を参照して、次に、対応する
.xcconfig
ファイルにアクセスして、対象の設定値を確認します。- buildType 属性が
debug
の場合にはbuild-debug.xcconfig
、release
の場合にはbuild-release.xcconfig
にアクセスします。 - buildType が指定されていない場合、または、
none
に設定されている場合、build.xcconfig
にアクセスします。
config.xml
内に記述され ている preference の name と一致する設定が、.xcconfig
ファイル内に存在する場合、デフォルトでは、config.xml
側に記述されている値を使用して、.xcconfig
側の値が上書きされます。このような上書き処理を無効にする場合には、xcconfigEnforce="false"
を、preference に設定します。<custom-preference name="ios-XCBuildConfiguration-SOME_PREFERENCE" value="Some value" buildType="debug" xcconfigEnforce="false" />
preference に設定した値が、対応する
.xcconfig
ファイル内に存在しない場合は、xcconfigEnforce="true"
を使用すれば、強制的に、ファイルに設定を追加できます。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-SOME_PREFERENCE" value="Some value" buildType="debug" xcconfigEnforce="true" />
更新された
.xcconfig
ファイルのバックアップが、plugins/cordova-custom-config/backup/ios
下に作成されます。デフォルトでは、 prepare
コマンドを 実行するたびに、バックアップファイルが適用されます。この自動リストア機能を無効にする場合には、 <preference name="cordova-custom-config-autorestore" value="false" />
に設定します ( config.xml
内 )。なお、
.xcconfig
の更新時、quote
属性は無視されます。よって、preference で指定している name と value を使用して、.xcconfig
を更新しても、クォーテーションは付記されません。Cordova では、リリースビルド向けに使用される CODE_SIGN_IDENTITY は、build-release.xcconfig に置かれます。一方、デバッグビル ド向けでは、
build.xcconfig
に置かれます。buildType="release"
を指定して、CODE_SIGN_IDENTITY 用の preference を設定した場合 ( config.xml
内 )、 build-release.xcconfig
内に記述されているデフォルト設定が上書きされます。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-CODE_SIGN_IDENTITY" value="iPhone Distribution: My Release Profile (A1B2C3D4)" buildType="release" />
buildType="debug"
を指定して、CODE_SIGN_IDENTITY 用の preference を設定した場合 ( config.xml
内 )、 build.xcconfig
内に記述されているデフォルト設定が上書きされます。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-CODE_SIGN_IDENTITY" value="iPhone Distribution: My Debug Profile (A1B2C3D4)" buildType="debug" />
上記のような上書き処理を無効にする場合には、
xcconfigEnforce="false"
を設定します。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-CODE_SIGN_IDENTITY" value="iPhone Distribution: My Release Profile (A1B2C3D4)" buildType="release" xcconfigEnforce="false" />
buildType="debug"
に設定した場合には、xcconfigEnforce="true"
にして、build.xcconfig
内のデフォルト設定を上書きするか、または、build.xcconfig
ではなく、build-debug.xcconfig
内に CODE_SIGN_IDENTITY を新規に挿入することもできます。ただし、後者のような処理をしても、build-debug.xcconfig
の設定を使用して、build.xcconfig
内の設定が後から更新されるため、結局は、build.xcconfig
内のデフォルト設定は上書きされます。次に例を記します。<custom-preference name="ios-XCBuildConfiguration-CODE_SIGN_IDENTITY" value="iPhone Distribution: My Debug Profile (A1B2C3D4)" buildType="debug" xcconfigEnforce="true" />
<config-file>
要素を使用してカスタマイズできる対象は、現在、プロジェクトの .plist
ファイル (platforms/ios/{PROJECT_NAME}/{PROJECT_NAME}-Info.plist
) だけです。次の 3 種類の属性を使用できます。- 1.
target
:*-Info.plist
を指定します。 - 2.
platform
:ios
を指定します。 - 3.
parent
: カスタマイズ設定を適用する key 名を指定します。
例 :
<config-file platform="ios" target="*-Info.plist" parent="NSLocationAlwaysUsageDescription">
上記の内容を適用した場合、
{PROJECT_NAME}-Info.plist
は、次のようになります。<plist version="1.0">
<dict>
<key>NSLocationAlwaysUsageDescription</key>
</dict>
</plist>
挿入する value には、
<config-file>
要素内に記述されている子要素が使用されます。.plist
ファイル内の対応する <key>
下に、子要素の内容が置かれます。例 :
<config-file platform="ios" target="*-Info.plist" parent="NSLocationAlwaysUsageDescription">
<string>
This app requires constant access to your location in order to track your position, even when the screen is off.
</string>
</config-file>
plist
ファイルでは、次のようになります。<key>
NSLocationAlwaysUsageDescription
</key>
<string>
This app requires constant access to your location in order to track your position, even when the screen is off.
</string>
iOS 向けの設定のサンプルを、次に記します (
config.xml
ファイル内 )。<platform name="ios">
<!-- Set ENABLE_BITCODE to YES in XCode project file override NO value in /ios/cordova/build.xcconfig -->
<custom-preference name="ios-XCBuildConfiguration-ENABLE_BITCODE" value="YES" />