Register Login to account
Search this manual

Specifying dependencies

Plugins and behaviors can specify dependencies on additional files, or Cordova plugins for inclusion with the Cordova exporter. Dependencies are added using the AddFileDependency(opts) and AddCordovaPluginReference(opts) methods on both IPluginInfo and IBehaviorInfo. Remote scripts can also be added with AddRemoteScriptDependency, but this is not recommended.

File dependencies

A file dependency refers to another file in the addon. Note the file must be bundled with the addon; you cannot refer to URLs elsewhere on the Internet. There are five kinds of file dependency, which correspond to the type property in the options object:

copy-to-output
This simply causes the file to be copied to the output folder when exporting. The file is also available in preview mode. This is useful for bundling additional resources, such as an image file that needs to be loaded at runtime, or a script that is dynamically loaded.
inline-script
A script dependency that is directly included in the output script file (normally named c3runtime.js).
Consequently this script will also be minified on export along with the addon runtime script. This is a convenient way to break up a large runtime script.
external-dom-script
A script dependency that is included via the addition of an extra <script> tag in the exported HTML file. Note in worker mode the script is loaded in the DOM, so is not directly available to the runtime code in the worker. The script is not minified on export. This is suitable for large external libraries that the addon references.

external-runtime-script
A script dependency that is included via the addition of an extra <script> tag in the exported HTML file, or loaded on the worker with importScripts() in worker mode. This means the script is always directly available to runtime code. However the dependency must be designed to work in a Web Worker, e.g. not assuming the DOM is present. The script is not minified on export.
external-css
A stylesheet dependency that is included via the addition of an extra <link rel="stylesheet"> tag in the exported HTML file, in case the addon needs to specify CSS styles.

To add a file dependency, call AddFileDependency with an options object, such as in this example:

this._info.AddFileDependency({
	filename: "mydependency.js",
	type: "external-script"
});

The options object uses the following properties.

filename
Name of the dependency file in the addon. This must be bundled with the addon; it cannot refer to a URL. It is recommended to bundle the script with your addon, but if you must use a URL, see the section Remote script dependencies. The file path is relative to the root (the location of addon.json).
type
One of the types described above, e.g. "external-script".
fileType
When type is "copy-to-output", this must specify the MIME type of the file. For example if including "image.png" as a "copy-to-output" dependency, the fileType
must be set to "image/png".

Cordova plugin dependencies

Addons can specify dependencies on Cordova plugins. These only apply to the Cordova exporter, which covers both Android and iOS. When exporting a Cordova project, the additional Cordova plugin dependencies are automatically included in the exported config.xml. This allows convenient integration of a Construct addon with a Cordova plugin.

To add a Cordova plugin dependency, call AddCordovaPluginReference with an options object, such as in this example:

this._info.AddCordovaPluginReference({
	id: "cordova-plugin-inappbrowser"
});

If you wish to provide variables to the Cordova plugin, use the variables property of the options object to pass an array of [variableName, pluginProperty] pairs. In this case the plugin must also be passed in the plugin property. An example is shown below.

const property = new SDK.PluginProperty("integer", "test-property", 0);

this._info.SetProperties([
	property
]);

this._info.AddCordovaPluginReference({
	id: "cordova-plugin-inappbrowser",
	plugin: this,
	variables: [
		["MY_VAR", property]
	]
});

See Cordova plugin variables for more information.

The options object uses the following properties.

id
The ID of the Cordova plugin to reference.
version Optional
A version spec for the Cordova plugin, e.g. "1.0.4". If this is not specified, the latest version will be used.
platform Optional
Specify a specific platform the Cordova plugin applies to. By default this is "all" meaning it will be used in both Android and iOS exports. However it can be set to "android" or "ios" to only be included when exporting to a specific platform. This is useful to switch between different Cordova plugins on different platforms.
variables Optional
Specify variables to be used with the Cordova plugin as an array of [variableName, pluginProperty] pairs. The variable name is bound to a SDK.PluginProperty. When the project is exported a variable is added under the plugin reference in config.xml with the given name and a value taken from the specified property. When variables are specified, the plugin property must also be set.
plugin Optional
Used to specify the plugin when using variables. Normally this should be set to this.

Note for security reasons the Scirra mobile app build service does not allow arbitrary Cordova plugins to be used. The build service uses an allowlist of allowed Cordova plugins. If you'd like a Cordova plugin to be added to the allowlist, please file an issue on the Construct 3 issue tracker. Please note we cannot guarantee that Cordova plugins will be allowed, and approval is subject to a security review. Other build services, such as using PhoneGap Build or compiling with the Cordova CLI, do not impose this restriction.

Remote script dependencies

Plugins and behaviors may also specify remote script dependencies. These are loaded from a cross-origin URL, e.g. https://example.com/api.js.

Use AddRemoteScriptDependency to add a remote URL to load a script from, e.g.:

this._info.AddRemoteScriptDependency("https://example.com/api.js");

This will produce the following tag on export, loaded before the runtime:

<script src="https://example.com/api.js"></script>
Addon SDK Manual 2021-08-31