> For the complete documentation index, see [llms.txt](https://ja.docs.monaca.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ja.docs.monaca.io/reference/third_party_phonegap/custom_config.md). # 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 ブロックを記述し、このスクリプト経由で、プラットフォーム側の設定に適用します。 ## Custom Config プラグイン v5 の変更点 Cordova 7以降では、Android プロジェクトの構造に後方互換性のない変更が導入されました。この変更をサポートするために、Custom Config プラグイン v5 がリリースされました。注意すべき事項は次のとおりです。 1. Custom Config プラグイン v5 では、プロジェクトの Android プラットフォームのバージョンを検出し、正しいパスを使用する必要があります。 2. `config.xml` でサポートされているすべてのカスタム設定要素には、 Custom Config プラグイン v5 で使用するためのプレフィックス `custom-` を付ける必要があります。 * `` => `` * `` => `` * `` => `` * これは、Android プラットフォーム v7 が、config.xml 内の `` ブロックを解析しようとするためです。Custom Config プラグインが解析する `` ブロックは、Cordova でも解析されるため、ビルドエラーが発生する可能性があります。(詳細は[こちら](https://github.com/dpa99c/cordova-custom-config/issues/135) を参照してください。) * ただし、[プラグインの制御 ( preference を使用 )](/reference/third_party_phonegap/custom_config.md#puraguinno-preference-wo)は、`` として指定する必要があります。 ```markup ``` * Custom Config プラグイン v5 では、Android プラットフォームが v7か、v6（またはそれ以下）かどうかを検出します。 * Android プラットフォーム v6 の場合、デフォルトではプレフィックスのないカスタム設定要素をサポートします。 * Android プラットフォーム v7 の場合、デフォルトではプレフィックスのないカスタム設定要素をサポートしません。 * `parse_unprefixed` プリファレンスを明示的に設定することによってオーバーライドできます。 ```markup ``` ## プラグインの有効化 ( Monaca 上での処理 ) 1. Monaca クラウド IDE から**`設定 → Cordova プラグインの管理`** を選択します。 2. *利用可能なプラグイン* 項目の `Custom Config` プラグインにカーソルを置き、`有効`ボタンをクリックします。 ![](/files/-MgOf2fmJRq20eUGVYXX) ## 設定このプラグインには、実行ファイルのようなものはありません。代わりに、フック用のスクリプトを使用して、各プラットフォームの設定ファイルに対して、`config.xml` ファイル内に設定した preference を適用 ( 上書きまたは追加 ) します。たとえば、iOS の場合、preference の name 属性は、iOS 設定ファイルの key と紐づけされています。よって、このプラグインを使用する場合、カスタマイズに必要な設定 ( preference の name 属性などを使用 ) を、あらかじめ、`config.xml` 内に記述しておきます。適用処理は、プロジェクトのビルド時に、スクリプト側で行ってくれます。このプラグインを使用し変更した設定ファイルの内容は、原則、元に戻すことができません。ただし、次の preference を使用して、元に戻せるように設定することもできます ( 自動リストア機能、`config.xml` の最上位の `` 要素内に追加 )。 ```markup ``` ## peference を使用したカスタマイズ設定 preference は、`config.xml` ファイル内で、`` 要素を使用し設定します。 ```markup ``` preference を設定する場合には、次の点に、注意が必要です。 1. `` 要素のブロック「外」に置かれた preferenceは、すべてのプラットフォームに対して適用されます。 2. `` 要素のブロック「内」に置かれた preferenceは、指定されているプラットフォームに対してのみ、適用されます。 3. platform 要素のブロック内に置かれている preferenceは、置かれていないものより、優先されます。 4. 特定のプラットフォーム向けの preferenceは、プラットフォーム名が指定された `` 要素 ( 例 : name="ios-somepref" ) のブロック内に置きます。 ## config-file を使用したカスタマイズ設定 `` ブロックを使用すれば、プラットフォーム別のカスタマイズ設定 ( 群 ) を、ひとまとめにして定義できます ( `config.xml` 内 )。適用先となるファイルでは、これらのカスタマイズ設定は、XML のサブツリーとして挿入されます。 config-file の設定時には、次の点に注意が必要です。 1. `` 要素は、``要素のブロック内に置きます。これ以外の場合、設定は無視されます。 2. config-file 要素の `target` 属性には、更新対象のファイルを指定します (`AndroidManifest.xml` または `*-Info.plist`)。 3. config-file の `parent` 属性には、親となる要素 ( Androidの場合、`AndroidManifest.xml` 内 )、または、親となる key ( iOSの場合、`*-Info.plist` 内 )を指定します。この親の子要素、または、key の valueとして、設定内容が挿入されます。 4. `` 要素に指定された target ( ファイル ) と parent (ファイル内の位置 )の組み合わせを使用して、カスタマイズ設定の適用場所を指定します。 5. 同一の target と parent 属性が設定された config-fileが複数ある場合、最後の config-file が適用されます。 6. config-file 内に定義された要素 (ファイル、適用する箇所、適用する内容 )を使用して、適用先ファイルの内容が上書きされます (または、指定された内容が追加されます )。 7. config-file内に定義されている要素が重複している場合、最後に定義されている要素が適用されます。ただし、``要素のように、`name` 属性の設定で一意に識別できる場合を除きます。 ## Android Android では、このプラグインを使用してカスタマイズできる対象は、現在、`platforms/android/AndroidManifest.xml` 内の設定だけです。Manifest ファイル内の詳細は、[アプリマニフェスト ( 外部サイト )](http://developer.android.com/guide/topics/manifest/manifest-intro.html) をご確認ください。なお、Android 向けの設定は、`config.xml` ファイルの `` ブロック内に置きます。 ### Android 向けの preference の設定方法 `config.xml` 内の `` 要素を使用して、`AndroidManifest.xml` 内の要素に、指定した属性を反映させます。たとえば、`config.xml` に、次の要素を追加すると... ```markup ``` `AndroidManifest.xml` には、次の設定が追加されます。 ```markup ``` `AndroidManifest.xml` 内に定義されているデフォルトの設定を削除する場合には、`` 要素に `delete="true"` を設定します。たとえば、`config.xml` に次の設定を追加した場合、 `AndroidManifest.xml` 内の `` を削除できます。 ```markup ``` #### 名前空間の設定方法 {% hint style="info" %} `config.xml` の preference に `android:` ( 名前空間を指定 ) を指定する場合、 `` 要素 ( ルート要素 ) にも、andorid の名前空間を設定する必要があります。 {% endhint %} 名前空間を指定する属性は、次のように記述します。 ```markup xmlns:android="http://schemas.android.com/apk/res/android" ``` `` 要素は、次のように記述します。 ```markup ``` #### XPath peference を使用したカスタマイズ設定 Android のマニフェストに適用する preference には、XPath も使用できます。preference の name に、要素と属性を XPath 形式で指定して、カスタマイズ設定の適用先を示します。具体的には、preference の name に指定する値に、`android-manifest` を先頭に付け、その後ろに、XPath 形式で要素と属性を指定して、value の値の適用先となる場所を示します。次に例を記します。 ```markup ``` 上記の preference を適用すると、次のように、`launchMode` 属性に、`singleTask` が設定されます。 ```markup ``` manifest 内に、複数の activity が存在する場合、XPath の記述内にも、activity の name を指定します。次に例を記します。 ```markup ``` {% hint style="info" %} Cordova 4.2.0 以前のバージョンでは、プロジェクトの作成時、activity の name には、 `CordovaApp` が使用されていました。Cordova 4.3.0 以降では、 `MainActivity` となっています。 {% endhint %} `` 要素 ( ルート要素 ) 内にある属性を適用先とする場合、要素名は省略して、属性だけを指定します。例 : ```markup ``` ### Android 向けの config-file ブロックの設定方法 `AndroidManifest.xml` に適用するカスタマイズ設定が複数ある場合は、`` を使用して定義します。これらのカスタマイズ設定は、`AndroidManifest.xml` ファイル内で、XML のサブツリーに変換されます。`` 内の要素は、parent で指定されている要素の下に挿入されます。 `` 要素には、次の 2 種類の属性を指定できます。 1. `target`: `AndroidManifest.xml` を常に指定します。 2. `parent`: XPath の記法を使用して、`AndroidManifest.xml` 内の親となる要素を指定します。この要素下に、XML のサブツリーとして、指定された値が挿入されます。 * `` 要素 ( ルート要素 ) にブロックを挿入する場合には、`parent="/*"` を使用します。 * `` の子孫ノード下にブロックを挿入する場合には、`./` 形式の記法も使用できます。たとえば、`parent="./application/activity"` を指定した場合、`/manifest/application/activity` 下に、ブロックが挿入されます。例 : ```markup

``` `AndroidManifest.xml` 内では、次のようになります。 ```markup

``` {% hint style="info" %} parent 要素に指定された値が XML のサブツリー側に定義されている値と重複する場合、既存の要素は上書きされます。 {% endhint %} 例 : ```markup ``` 上記の内容を使用すれば、既存の `` 要素が書き換えられます。なお、このような場合には、preference の使用を推奨します。 ```markup ``` ### 例 Android 向けの設定のサンプルを、次に記します ( `config.xml` ファイル内 )。 ```markup

``` ## iOS iOS では、このプラグインを使用してカスタマイズできる対象は、現在、プロジェクトの plist ( `*-Info.plist`、config-file ブロックを使用 )、および、設定情報 ( `project.pbxproj`、preference 要素を使用 ) です。なお、iOS 向けの設定は、 `config.xml` ファイルの `` ブロック内に置きます。 ### iOS 向けの preference の設定方法 `config.xml` の `` 要素を使用して、 `*-Info.plist` の設定を更新します。preference は、 `` の形式で設定します。次に例を記します。 ```markup /> ``` #### ビルド設定用の preferences ビルド設定は、`project.pbxproj` 内の `XCBuildConfiguration` を使用して、現在行っています。使用する key/value に関しては、制限はありません。 `XCBuildConfiguration` ブロック内にすでに存在する key を指定した場合、key の value は上書きされます。指定した key がどの `XCBuildConfiguration` にも存在しない場合、指定した value とともに、各 `XCBuildConfiguration` に key が追加されます。デフォルトでは、Release と Debug の両方の `XCBuildConfiguration` ブロックに value が適用されますが、`config.xml` の `` 要素に、`buildType` 属性を追加すれば、ビルドの種類を指定でき、ブロックを絞り込めます。この属性に指定できる値は、`debug` または `release` です。 ```markup ``` デフォルトでは、`XCBuildConfiguration` への挿入時、key と value は、ダブルクォーテーションで囲われます。次に例を記します。 ```markup ``` `project.pbxproj` 内では、次のようになります。 ```markup "IPHONEOS_DEPLOYMENT_TARGET" = "7.0"; ``` クォーテーションの付記方法 ( 上記がデフォルトの仕様 ) は、`` の `quote` 属性を使用して、変更できます。この属性には、次の値を使用できます。 * `none`: key と valueのいずれにも、クォーテーションは付記されません。 * `key`: key だけに、クォーテーションが付記されます。 * `value`: value だけに、クォーテーションが付記されます。 * `both`: key と value のいずれにも、クォーテーションが付記されます。例 : ```markup ``` `project.pbxproj` 内では、次のようになります。 ```markup IPHONEOS_DEPLOYMENT_TARGET = 7.0; ``` #### .xcconfig ファイル 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 に設定します。 ```markup ``` preference に設定した値が、対応する `.xcconfig` ファイル内に存在しない場合は、`xcconfigEnforce="true"` を使用すれば、強制的に、ファイルに設定を追加できます。次に例を記します。 ```markup ``` 更新された `.xcconfig` ファイルのバックアップが、`plugins/cordova-custom-config/backup/ios` 下に作成されます。デフォルトでは、 `prepare` コマンドを実行するたびに、バックアップファイルが適用されます。この自動リストア機能を無効にする場合には、 `` に設定します ( `config.xml` 内 )。なお、`.xcconfig` の更新時、`quote` 属性は無視されます。よって、preference で指定している name と value を使用して、`.xcconfig` を更新しても、クォーテーションは付記されません。 #### CODE\_SIGN\_IDENTITY 設定用の preference Cordova では、リリースビルド向けに使用される CODE\_SIGN\_IDENTITY は、build-release.xcconfig に置かれます。一方、デバッグビルド向けでは、`build.xcconfig` に置かれます。 `buildType="release"` を指定して、CODE\_SIGN\_IDENTITY 用の preference を設定した場合 ( `config.xml` 内 )、 `build-release.xcconfig` 内に記述されているデフォルト設定が上書きされます。次に例を記します。 ```markup ``` `buildType="debug"` を指定して、CODE\_SIGN\_IDENTITY 用の preference を設定した場合 ( `config.xml` 内 )、 `build.xcconfig` 内に記述されているデフォルト設定が上書きされます。次に例を記します。 ```markup ``` 上記のような上書き処理を無効にする場合には、 `xcconfigEnforce="false"` を設定します。次に例を記します。 ```markup ``` `buildType="debug"` に設定した場合には、`xcconfigEnforce="true"` にして、`build.xcconfig` 内のデフォルト設定を上書きするか、または、`build.xcconfig` ではなく、`build-debug.xcconfig` 内に CODE\_SIGN\_IDENTITY を新規に挿入することもできます。ただし、後者のような処理をしても、`build-debug.xcconfig` の設定を使用して、`build.xcconfig` 内の設定が後から更新されるため、結局は、`build.xcconfig` 内のデフォルト設定は上書きされます。次に例を記します。 ```markup ``` ### iOS 向けの config-file ブロックの設定方法 `` 要素を使用してカスタマイズできる対象は、現在、プロジェクトの `.plist` ファイル (`platforms/ios/{PROJECT_NAME}/{PROJECT_NAME}-Info.plist`) だけです。次の 3 種類の属性を使用できます。 1. `target`: `*-Info.plist` を指定します。 2. `platform`: `ios` を指定します。 3. `parent`: カスタマイズ設定を適用する key 名を指定します。例 : ```markup ``` 上記の内容を適用した場合、`{PROJECT_NAME}-Info.plist` は、次のようになります。 ```markup NSLocationAlwaysUsageDescription ``` 挿入する value には、`` 要素内に記述されている子要素が使用されます。`.plist` ファイル内の対応する `` 下に、子要素の内容が置かれます。例 : ```markup This app requires constant access to your location in order to track your position, even when the screen is off. ``` `plist` ファイルでは、次のようになります。 ```markup NSLocationAlwaysUsageDescription This app requires constant access to your location in order to track your position, even when the screen is off. ``` #### 例 iOS 向けの設定のサンプルを、次に記します ( `config.xml` ファイル内 )。 ```markup

myapp myapp2 myapp3

UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown

location

This app requires constant access to your location in order to track your position, even when the screen is off.

This app will now only track your location when the screen is on and the app is displayed.

NSAllowsArbitraryLoads

``` ## プラグインの制御 ( preference を使用 ) このプラグインでは、プラグイン自体の動作をカスタマイズするため、数種類の preference を用意しています。各 preference の name には、他の name との競合を避けるため、 `cordova-custom-config` が先頭に付記されています。次に例を記します。 ```markup ``` 次の preference が使用できます。 * `cordova-custom-config-autorestore`: ( デフォルトでは、`false` ) `true` に設定された場合、変更前の設定情報にロールバックします ( ロールバックに使用される情報は、このプラグインのインストール時にバックアップされたものです )。 * `cordova-custom-config-stoponerror`: ( デフォルトでは、`false` ) `prepare` コマンドの実行時、この値が `true` に設定されている場合、エラーが発生したときには ( 指定されたプラットフォームの設定ファイルの更新時 )、`prepare` 処理が終了します。false の場合、エラーが発生したときでも、設定情報の更新および `prepare` 処理は、継続して行われます ( エラーがログに出力されます )。関連項目: * [基本プラグイン](/reference/core-cordova-plugins.md) * [Monaca 提供プラグイン](/reference/power_plugins.md)