Core Cordova plug-ins

The core set of Cordova plug-ins provides access to native device features within AEM Mobile content views using JavaScript. Plug-ins can be enabled or disabled on an app-by-app basis while building apps.

The following core Cordova plugins are available:

Camera – For taking pictures and choosing images from the system's image library.

Contacts – Provides access to the device contacts database. For Windows apps, the only supported API of the plugin is 'pickContact'.

Device Info – Describes the device's hardware and software.

Device Motion (accelerometer) – Provides access to motion sensor that detects the change in movement relative to the current device orientation, in three dimensions along the x, y, and z axis.

Device Orientation (compass) – Sensor that detects the direction or heading that the device is pointed, typically from the top of the device.

WKWebView (iOS only) – You can enable the WKWebView plug-in in order to render HTML files the same way they render in Mobile Safari. This option uses WKWebView (WebKit) instead of UIWebView for HTML articles and web overlays on iOS 9 devices. An app running on iOS 8 devices will still render content using UIWebView. (See Building iOS apps for AEM Mobile.)

Custom Cordova plugins

With the ability to add custom Cordova plugins to an AEM Mobile app, you can create content that leverages the many plugins available from the Cordova/PhoneGap community, or you can create your own custom plugins. For example, you can enable mobile barcode scanning, access geofences, and leverage mobile databases in your app.

The workflow for building apps that use custom Cordova plugins is different from the standard method for building apps. You use the updated AEM Mobile Developer Tool to specify which Cordova plugins you intend to use. For iOS apps, you use the Developer Tool to modify the .ipa you downloaded. For Android apps, you use the Developer Tool to create an .apk file, which you then upload using the new Custom App Shell tab that appears when creating or editing an Android app.

Cordova plugins are restricted to the article level at this time. An article needs to be opened in order for the AEM Mobile app to use the plugin. For iOS devices, if an article is the first item in your top-level collection, that article is loaded when the app is launched and is kept in memory. That article can continue to run and make the same Cordova plugin calls after the user browses to other content. However, the plugins in that top-level article are not available for other articles to reference.

AEM Mobile specific Cordova plug-ins

The AEM Mobile specific Cordova-enabled plug-ins are a set of JavaScript APIs that provide access to specific data related to the AEM Mobile Runtime application and its content from within the article content view. To utilize the AEM Mobile Cordova plug-ins, content must be enabled for extensibility by having the "Enable Extensibility Features" option in article properties selected. These plug-ins are enabled automatically in AEM Mobile apps.

The cordova.js file is included automatically in your app; you just need to load it at run time.

The Cordova plug-ins and the AEM Mobile specific Cordova-enabled plug-ins require Cordova to be fully loaded before it can be used safely. Otherwise, your script that calls a certain Cordova API might fail because Cordova isn't loaded yet.

When Cordova is ready, it will trigger a deviceready event, which you can use to determine when to start your code.

For each content that uses these plug-ins, select “Enable Extensibility Features” in content properties. (Edit content properties in the Content & Layouts section of the On-Demand Portal.)

You can also enable the extensibility features for the articles via the On-Demand Services API. When creating or updating the article entity metadata, set the parameter isTrustedContent to true (boolean). This value is set to false by default.

By default, "Enable extensibility features" is turned off for all articles. You can change the default in project settings.

For an app that uses core (not custom) Cordova plug-ins, build an app that enables the Cordova plug-ins. (For custom Cordova plug-ins, follow the steps in the next section.)

Use the Plug-ins tab when building an app to enable the APIs you'll be using in your contents.

For best results, select only the Cordova plug-ins that you plan to use.

Test the app.

Workflow for building apps that use custom Cordova plugins

If you use custom Cordova plug-ins in your app, you need to use the AEM Mobile Developer Tool to specify which Cordova plug-ins you use. You then use the developer tool to either modify the .ipa file (iOS) or create a .apk app shell (Android) that you can upload while building your Android app.

These steps are necessary only if you want to use custom Cordova plug-ins in your app. Use the developer tool to specify all plugins—custom, core, and AEM Mobile-specific— used in your app. When you use the developer tool to modify or build an app, any settings you specify in the “Plug-ins” tab when building the app are ignored. Use the developer tool to specify all Cordova plug-in information.

Custom Cordova Plugins Video

Custom Cordova Plugins Video

iOS workflow for apps that use custom Cordova plugins

Create content that uses Cordova plugins. Follow the above steps in “Enabling extensibility feature in app” to allow extensibility in each article that uses Cordova plugins.

Use the AEM Mobile Developer Tool to set up a project, test your content, and identify which Cordova plugins are used in the app. Then use the developer tool to modify the downloaded .ipa file so that it includes the Cordova information you specified.

For details, see the section below about using the AEM Mobile Developer Tool.

Sign the modified .ipa file.

Android workflow for apps that use custom Cordova plugins

Create content that uses Cordova plugins. Follow the above steps in “Enabling extensibility feature in app” to allow extensibility in each article that uses Cordova plugins.

Use the AEM Mobile Developer Tool to set up a project, test your content, and specify the Cordova plugins you plan to use in your app. Then use the developer tool to create an app shel (.apk file) that includes the Cordova information you specfied.

For details, see the section below about using the AEM Mobile Developer Tool.

In the On-Demand Portal, build an Android app. In the "Custom App Shell" tab, specify the .apk file that you built using the developer tool.

In the On-Demand Portal, download and sign the .apk file.

Using the AEM Mobile Developer Tool

The AEM Mobile Developer Tool is a command line utility to help enable a smooth developer workflow. The tool is installed on a developer’s local desktop and provides the following capabilities:

Create projects – Creates an AEM Mobile project folder structure that is ready for local development. This project structure is used only for testing.

Create contents – Creates an AEM Mobile content template that is capable of using the available Cordova and Runtime APIs.

Add Cordova plugins and build an app – If you use custom Cordova plugins in your app, you use the developer tool to specify the plugins and build an app shell (Android) or modify an .ipa file (iOS) that includes the Cordova plugins you specify.

Run on simulator – (1) Launch the simulator, (2) Install the simulator build, and (3) Start the AEM Mobile Runtime simulator build that will display local content from the local environment. Step 1 is ignored if the target simulator is launched, and step 2 is ignored if the simulator build is installed.

Help – Displays help for the command line commands.

AEM Mobile command structure

The AEM Mobile Developer Tool is required for two main workflows:

Developing and testing content that uses Cordova plugins.

Building apps that include custom Cordova plugins.

License Agreement

Märkus.

By installing the software listed below, I acknowledge that I have read and agreed to the terms of the Adobe.com Terms of Use.

Configuring the environment for Android

To emulate the Android build, you have to install the necessary Android SDK and configure the environment for running the Android emulator.

From the terminal, run the following command to install the necessary SDK and configurations:

aemm platform install android

You may be prompted for the Android SDK license agreement. Please enter y to accept the agreement or n to decline it. If declined, you will not be able to install the necessary SDKs and run the Android emulator.

Configuring the environment for iOS (sudo aemm platform install ios) is required only for building apps that use custom Cordova plugins.

Installing the simulator build

The AEM Mobile command line tool requires the AEM Mobile Runtime simulator build that it will install and run when building the project. This process is required for testing HTML content using the simulator. It is not required for building apps with custom Cordova plugins.

To install the AEM Mobile Runtime simulator build, please do one of the following:

From Terminal, run the following command to install the latest version of the simulator build:

aemm app install <platform>

The available <platform> values are as follows: ios, android

Alternatively, you can specify the simulator build version. This will allow you to install an older version from the list of available simulator builds.

From Terminal, get the list of available simulator versions:

aemm app install --list

Specify the simulator version in the installation process:

aemm app install <platform> <simulator-version>

For example, to install simulator version 2016.4 on iOS:

aemm app install ios 2016.4

Märkus.

If you get a error message when trying to run the Simulator, launch Xcode and sign the license agreement, if appropriate. You can also enter sudo xcodebuild –license accept in Terminal.

Creating a project

The AEM Mobile command line tool has a required directory structure to build and test the project. You use this project only for testing. After you test the content, you can then add it to your project in the On-Demand Portal.

To set up this project structure, do the following:

In Terminal, navigate to the directory that you want to manage the new project in.

This will create the directory with the specified <project-name> and a sample content directory within that called “SampleArticle”.

Running the simulator

Now that the project directory is created, you can start building the app. This process is required for testing HTML content using the simulator. It is not required for building apps with custom Cordova plugins.

To open the simulator (if not already opened), install the AEM Mobile Runtime simulator build (if not already installed), and run the simulator, do the following:

From Terminal, navigate into the created project directory by using the following command:

cd <drag and drop the project-name directory>

(Optional) Set the default orientation that the emulator/simulator will be launched in. The options are landscape or portrait mode.

aemm config --set screenOrientation <<orientation>>

For example, to specify the orientation to be in landscape mode:

aemm config --set screenOrientation landscape

Using this will also replace the existing default orientation mode, if available. To get the current default orientation mode:

aemm config --get screenOrientation

To remove the current default orientation mode:

aemm config --unset screenOrientation

Open, install, and run the simulator build.

aemm run <platform>

The available <platform> values are as follows: ios, android

The run command will continuously listen in the terminal, to terminate this, please enter the following key combination in the same terminal window: Ctrl + C

Once the simulator app launches, you should be able to see the “SampleArticle” that was created earlier. Any changes to the files within the “SampleArticle” directory will cause the simulator app to refresh and display the updated contents automatically.

When running the simulator, press Command+Shift+H to return to the home screen.

You can specify which simulator device to use by specifying the device name. This will be handy when testing on a different simulator device.

Get the list of available simulators currently installed in the system:

aemm run <platform> --list

From the list of <uuid><device-name>, specify the device:

aemm run <platform> --target "<device-name>"

For example, to run the simulator in iPhone 6s on iOS 9.2:

aemm run ios --target "iPhone-6s, 9.2"

Creating content

The project creates a default HTML content template, but you can add more to the list by doing the following:

From Terminal, navigate into the created project directory:

cd <drag and drop the project-name directory>

Create additional HTML contents:

aemm article create <article-name>

This will create another HTML content directory with the specified <article-name> within the project directory.

The HTML content folder structure is simply a directory with index.html and all the necessary resources (CSS/JS/images/etc) mapped out in the index.html. So alternatively, you can just create a folder within <project-name directory>/www/<custom-folder> and include the index.html in it instead of running the above script. This could be useful if you have HTML contents already curated elsewhere and wanted to test out the Cordova extensibility. You can drag and drop the HTML content into the <project-name directory>/www/ folder and the simulator will recognize it.

Adding Cordova plugins to the project (for custom Cordova plugins)

These commands are required only if you want to use custom Cordova plug-ins in your app. If you use custom Cordova plug-ins, use the AEM Mobile Developer Tool to specify which Cordova plugins—custom, core, and AEM-Mobile-specific—you use in your app.

Building a custom app (for custom Cordova plugins)

These commands are required only if you want to use custom Cordova plug-ins in your app.

For iOS apps, you modify the .ipa file that you downloaded from the Apps section of the On-Demand Portal.

For Android apps, you build an app shell .apk file that you upload when building the app in the On-Demand Portal.

Note that any settings you added to the "Plug-ins" section while building an app are ignored and replaced with the settings specified using the AEM Mobile Developer Tool.

Märkus.

The "aemm" command was built on the "cordova" command and delegates many commands to cordova-lib. You may experience errors that recommend that you try to run a cordova command. In most cases, please first try to replace cordova with aemm, and then execute the recommended action.

(iOS) Configure the iOS environment to allow Xcode to build an unsigned framework.

sudo aemm platform install ios
aemm platform add ios

Navigate to the created project directory and add the Cordova plug-ins that you want to include in your app as described in the previous section.

Build the Cordova structure (iOS) or build the app shell (Android).

aemm build [platform]

iOS example:

aemm build ios --device --release

Adding --device builds the app for iOS devices instead of the simulator.

Adding --release builds a release version instead of the default debug version.

Android example:

aemm build android --release

Märkus.

If you are unable to build the app, we recommend that you uninstall NodeJS and install the current version of NodeJS (see the NodeJS site for details). In addition, run sudo npm uninstall -g aemm and then run sudo npm install -g aemm.

Resolving the code signing error message

If you have updated XCode, you might get the following error message: "Error: CODE_SIGNING_REQUIRED must be set to NO in order to build for device. You can resolve this by running 'aemm platform install ios'."

If you encounter this issue, the workaround to run the following command in Terminal:

(Android) Upload the .apk app shell you built in the On-Demand Portal. Build, download, and sign the .apk file.

For details about this workflow, see the previous section in this article about building apps that use custom Cordova plugins.

Testing custom Cordova plugins in the simulator

Run the following commands:

aemm build ios
aemm package ios
aemm run ios

Omit the --device parameter to apply the command to the simulator. Running aemm package ios is necessary in order to package the custom plugins into the simulator build. To restore the original simulator build, re-run the aemm app install ios command.

Remote debugging

From the simulator, you can remotely inspect the HTML content like you would in a modern browser. This feature allows you to see and manipulate with the DOM element, check for any errors generated from the console or directly input JavaScript/jQuery commands, and much more. For more information, please refer to the following:

Packaging the contents

The HTML contents within the project directory are also in the required structure for generating the content file for the AEM Mobile On-Demand Services portal. You can select all the HTML contents within the project directory and drag and drop them into the AEM Mobile Packager.