Cordova Custom Config Plugin
Last updated
Was this helpful?
Last updated
Was this helpful?
For Cordova 5.2 or lower, basic behaviour of Android or iOS applications can be configured by editing AndroidManifest.xml
or MonacaApp-Info.plist
file respectively. However, for Cordova 6.2 or higher, both AndroidManifest.xml
and MonacaApp-Info.plist
files are removed from Monaca framework.
Therefore, in order to config iOS/Android application settings, you will need to use Cordova Custom Config plugin. This Cordova plugin for iOS and Android provides hook scripts to update platform configuration files based on custom preferences and config-file data defined in config.xml
file that are not supported out-of-the-box by Cordova.
The recent release of cordova@7.0.0 has introduced backwardly-incompatible breaking changes to the structure of Android projects generated by Cordova.
Therefore a new major version of this plugin (v5) has been released to support these changes. Here are things to be aware of:
The location of AndroidManifest.xml has changed in cordova-android@7 but cordova-custom-config@5 should detect which version of cordova-android platform is present in the project and use the correct path.
All custom config elements supported by this plugin in config.xml should now be prefixed with custom- for use with cordova-custom-config@5
<config-file>
=> <custom-config-file>
<preference>
=> <custom-preference>
<resource>
=> <custom-resource>
This is because cordova-android@7 now attempts to parse <config-file>
blocks in the config.xml, so <config-file>
blocks intended for this plugin to parse will be picked up by Cordova and can cause build errors (see ) for an example.
should still however be specified as <preference>
The plugin will detect if the platform project is cordova-android@7 or cordova-android@6 (or below)
If cordova-android@6, by default the plugin will support non-prefixed custom config elements
If cordova-android@7, by default the plugin will NOT support non-prefixed custom config elements
This can be overridden by explicitly setting the parse_unprefixed
preference
From the IDE menu, go to Configure → Cordova Plugin Settings
.
Under Available Plugins section, hover over the Custom Config
plugin and click Enable
button.
There are no run-time source files included in this plugin. It includes hook scripts which are used to apply preferences dictated by custom keys in the config.xml
file of the project to the relevant platform config files. Therefore, in order to use this plugin, you need to include the relevant keys in your config.xml
and the scripts will take care of the rest when you build your project.
By default, any changes made by this plugin to platform config files are irreversible. However, if you want the changes made to be reversible, you can enable auto-backup/restore functionality by adding the following preference inside the top-level <widget>
element of your config.xml
:
Preferences are set by defining a <preference>
element in the config.xml
file. For example:
While setting the preferences, please be aware of the following points:
Preferences defined outside of the <platform>
element will apply
to all platforms.
Preferences defined inside a <platform>
element will apply only to
the specified platform.
Platform preferences take precedence over common preferences.
Platform-specific preferences must be prefixed with the platform
name (e.g. name="ios-somepref"
) and be defined inside a <platform>
element.
<config-file>
blocks allow platform-specific chunks of the configuration to be defined as an XML subtree in the config.xml
file, which is then applied to the appropriate platform configuration file by the plugin.
While setting the config blocks, please be aware of the following points:
<config-file>
elements must be defined inside a <platform>
element, otherwise they will be ignored.
config-file target
attributes specify the target file to update.
(AndroidManifest.xml
or *-Info.plist
)
config-file parent
attributes specify the parent element
(AndroidManifest.xml
) or parent key (*-Info.plist
) that the
child data will replace or be appended to.
<config-file>
elements are uniquely indexed by target and parent
for each platform.
If there are multiple config-file's defined with the same target and
parent, the last config-file will be used.
Elements defined within a config-file will replace or be appended to
the same elements relative to the parent element.
If a unique config-file contains multiples of the same elements
(other than <uses-permission>
elements which are selected by by
the uses-permission name
attribute), the last defined element will
be retrieved.
<preference>
elements in config.xml
are used to set attributes on elements in the AndroidManifest.xml
. For example, if you add the following element to the config.xml
:
then the following line will be added to AndroidManifest.xml
:
Sometimes, you may want to remove some default settings in AndroidManifest.xml
. You can do delete them by using the delete="true"
attribute of the <preference>
element. For example, if you add the following line in config.xml
, it will delete the existing node <uses-permission android:name="android.permission.WRITE_CONTACTS" />
within AndroidManifest.xml
:
The namespace attribute fragment is:
so your <widget>
element should look something like this:
Android manifest preferences are set by using XPaths in the preference name to define which element attribute the value should be applied to. The preference name should be prefixed with android-manifest
then follow with an XPath which specifies the element and attribute to apply the value to. For example,
This preference specifies that the launchMode
attribute should be given a value of singleTask
which will be resulted as:
If your manifest contains other activities, you should specify the activity name in the XPath. For example:
If the attribute you are setting is on the root <manifest>
element, just omit the element name and specify the attribute. For example:
<config-file>
blocks are used to define chunks of configuration of an XML subtree which will be inserted into AndroidManifest.xml
. The child elements inside the <config-file>
block will be inserted under the parent element.
<config-file>
element has two attributes such as:
target
: must be set to AndroidManifest.xml
.
parent
: defines an Xpath to the parent element in the AndroidManifest.xml
under which the XML subtree block should be inserted:
to insert a block under the root <manifest>
element, use parent="/*"
.
to insert a block under a descendant of <manifest>
, use an Xpath prefixed with ./
. For example, parent="./application/activity"
will insert the block under /manifest/application/activity
.
For example:
will result in AndroidManifest.xml
with:
For example:
will replace the existing <application>
element. In this case, it would be better to use a preference:
Below is an example of a config.xml
file for Android configuration:
The plugin currently supports custom configuration of the project plist (*-Info.plist
) using config blocks, and project settings (project.pbxproj
) using preference elements. All iOS-specific config should be placed inside the <platform name="ios">
in config.xml
file.
<preference>
elements in config.xml
are used to set preferences in the *-Info.plist
. Preferences should be defined in the format: <preference name="ios-SOME_BLOCK_TYPE-SOME_KEY" value="SOME_VALUE" />
. For example:
Currently, XCBuildConfiguration
is the only supported block type in the project.pbxproj
. However, there is no constraint on the list of keys for which values may be set.
If an entry already exists in an XCBuildConfiguration
block for the specified key, the existing value will be overwritten with the specified value. If no entry exists in any XCBuildConfiguration
block for the specified key, a new key entry will be created in each XCBuildConfiguration
block with the specified value.
By default, values will be applied to both "Release" and "Debug" XCBuildConfiguration
blocks. However, the block type can be specified by adding a buildType
attribute to the <preference>
element in the config.xml
. The value can be either debug
or release
. For example:
By default, both the key (preference name) and value will be quote-escaped when inserted into the XCBuildConfiguration
block. For example:
will appear in project.pbxproj
as:
The default quoting can be override by setting the quote
attribute on the <preference>
element. The valid values are:
none
: don't quote key or value
key
: quote key but not value
value
: quote value but not key
both
: quote both key and value
For example:
will appear in project.pbxproj
as:
Cordova uses .xcconfig
files in /platforms/ios/cordova/
to override Xcode project settings in project.pbxproj
with build-type specific values. build.xcconfig
is overridden by settings in build-debug.xcconfig
and build-release.xcconfig
for the corresponding build type.
When applying a custom preference, the plugin will look for an existing entry in the .xcconfig
file that corresponds to the buildType attribute.
If buildType attribute is debug
or release
, the plugin will
look in build-debug.xcconfig
or build-release.xcconfig
respectively.
If buildType is not specified or set to none
, the plugin will
look in build.xcconfig
.
By default, if an entry is found in the .xcconfig
file which corresponds to the custom preference name in the config.xml
, the value in the .xcconfig
file will be overwritten with the value in the config.xml
. To prevent the plugin from overwriting the value of a specific preference in the corresponding .xcconfig
file, set the preference attribute xcconfigEnforce="false"
. For example:
If a preference value doesn't already exist in the corresponding .xcconfig
file, you can force its addition by setting the preference attribute xcconfigEnforce="true"
. This will append it to the corresponding .xcconfig
file. For example:
A backup copy of any modified .xcconfig
file will be made in plugins/cordova-custom-config/backup/ios
. By default, these backups will be restored prior to the next prepare operation. Auto-restore of the backups can be disabled by setting <preference name="cordova-custom-config-autorestore" value="false" />
in the config.xml
.
Preference names and values will not be quote-escaped in .xcconfig
files, so the quote
attribute has no effect on them.
Cordova places its default CODE_SIGN_IDENTITY for Release builds in build-release.xcconfig
but for Debug builds in build.xcconfig
.
If you set a CODE_SIGN_IDENTITY preference in the config.xml
with buildType="release"
, the plugin will overwrite the defaults in build-release.xcconfig
. For example:
If you set a CODE_SIGN_IDENTITY preference in the config.xml
with buildType="debug"
, the plugin will overwrite the defaults in build.xcconfig
. For example:
You can prevent the CODE_SIGN_IDENTITY preferences being overwritten by setting xcconfigEnforce="false"
. For example:
You can force the plugin to add a new entry for CODE_SIGN_IDENTITY preference with buildType="debug"
to build-debug.xcconfig
, rather than overwriting the defaults in build.xcconfig
by setting xcconfigEnforce="true"
. This will still override the defaults in build.xcconfig
, because build-debug.xcconfig
overrides build.xcconfig
. For example:
<config-file>
elements are currently only used to set preferences in the project .plist
file (platforms/ios/{PROJECT_NAME}/{PROJECT_NAME}-Info.plist
). This element has 3 attributes such as:
target
: should be set to *-Info.plist
.
platform
: should be set to ios
.
parent
: is used to determine which key name to use for the custom
preference.
For example:
will result in {PROJECT_NAME}-Info.plist
as:
The value of the preference is set by the child elements of the <config-file>
element. These will appear directly below the preference <key>
in the .plist
file.
For example:
will appear in the plist
file as:
Below is an example of a config.xml
file for iOS configuration:
The plugin supports some preferences which are used to customize the behavior of the plugin. Each preference name is prefixed with cordova-custom-config
to avoid name clashes. For example:
The following preferences are currently supported:
cordova-custom-config-autorestore
: (set to false
by default) if set to true
, the plugin will restore a backup of platform configuration files taken at plugin installation time.
cordova-custom-config-stoponerror
: (set to false
by default) if set to true
and an error occurs while updating config for a given platform during a prepare
operation, the error will cause the prepare
operation to fail. If false, the plugin will log the error but will proceed and attempt to update any other platforms, before allowing the prepare operation to continue.
See Also:
The plugin currently supports setting of custom config only in platforms/android/AndroidManifest.xml
. For a list of possible manifest values, please refer to . All Android-specific config should be placed inside the <platform name="android">
in config.xml
file.