Using Cordova plug-ins in AEM Mobile

Keresés
Experience Manager Mobile Felhasználói útmutató

Ezen az oldalon

Érintett termék: Experience Manager Mobile

某些 Creative Cloud 应用程序、服务和功能在中国不可用。

Requirements

Prerequisite knowledge

  • Understanding of AEM Mobile
  • Knowledge of creating and publishing content through the On-Demand Portal
  • Knowledge about Apache Cordova (http://cordova.apache.org)

Required products

  • AEM Mobile

Cordova extensibility

Experience Manager Mobile Runtime enables users to create rich app experiences with Apache Cordova extensibility and developer tools (Beta) for testing.

Cordova extensibility, available in HTML articles and web overlays in InDesign-based articles, provides access to the following capabilities:

  • Core Cordova plug-ins – Take advantage of core Cordova plug-ins such as Camera, Contacts, Geolocation, and File Sharing.
  • Custom Cordova plug-ins – Leverage plug-ins from the Cordova/Phonegap community or create your own plug-ins. Examples: barcode scanning and mobile databases.
  • AEM Mobile specific plug-ins enabled through Cordova – Plug-ins for local application and content metadata.

 

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.
  • File Access – Allows read/write access to files residing on the device.
  • File Transfer – Allows access to upload and download files.
  • Geolocation – Provides GPS information about the device's location, such as latitude and longitude.
  • Globalization – Uses operations specific to the user's locale, language, and time zone.
  • Media (cordova-plugin-media) – Provides the ability to record and play back audio files on a device.
  • Media Capture – Provides access to the device's audio, image, and video capture capabilities.
  • Network Information – Information about the device's cellular and Wi-Fi connection, and whether the device has an Internet connection.
  • Notification Dialogs – Provides access to some native dialog box UI elements such as alert and beep.
  • Vibration (iOS, Android only) – A way to vibrate 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.)

For more information, see Cordova Core plugins.

For examples, see Download examples from Github.

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.

See https://cordova.apache.org/plugins/

 

Megjegyzés:

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 AEM Mobile specific Cordova plug-ins include the follow APIs:

  • Entity metadata access (content title, entitlement)
  • Device information (platform, version, identifiers)
  • Push Notification information (push token)
  • Thumbnails (background and social sharing image)

For the detailed documentation, see Using AEM Mobile specific Cordova-enabled plug-ins.

Cordova plugin examples

Examples for Cordova plugins are available here:

https://github.com/Adobe-Marketing-Cloud/aemmobile-example-cordova-api/archive/master.zip

Enabling extensibility features in app

  1. Create source HTML content for the content view or web overlay that references the Cordova APIs.

    If your HTML code references the core Cordova plug-ins or AEM Mobile specific Cordova-enabled plug-ins, add this line:

    <script type="text/javascript" src="cordova.js"></script>

    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.

    Include this code in your HTML file:

    document.addEventListener("deviceready", function() {
    // Cordova is now ready,
    // start initializing the rest of the code
}, false);

    For more information, see Cordova Events.

  2. 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.

  3. 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.

    Enabling plug-ins is not required for AEM Mobile specific Cordova-enabled plug-ins.

    Plug-ins for iOS app

    Megjegyzés:

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

  4. 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

  1. 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.

  2. In the On-Demand Portal, build an iOS app and download the .ipa file. (See Building iOS apps for AEM Mobile.)

  3. 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.

  4. Sign the modified .ipa file.

Android workflow for apps that use custom Cordova plugins

  1. 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.

  2. 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.

  3. 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.

  4. 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

Megjegyzés:

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

Installing Dependencies

Please install the necessary dependencies based on the OS:

  • Mac OS X:
    • Node JS (Current is recommended; v6.2.2 or later is required)
    • For iOS development, Xcode (v7.0 or greater)
    • For Android development, Java (depending on OS X version)
  • Windows:

 

Installing the AEM Mobile command line tool (Mac OS)

When developing on Windows, please run all commands in PowerShell instead of the Command Prompt.

  1. Launch Terminal.

  2. Run the following to install the AEM Mobile command line tool via Node.js:

    npm install -g aemm

    If a user permission denied message appears, try running the above script with “sudo”:

    sudo npm install -g aemm

    Once completed, this will create a symbolic link so that you can run the AEM Mobile command line tool (aemm) in any directory from in Terminal.

Updating the developer tool

Run npm install -g aemm (or sudo npm install -g aemm) again whenever an updated version of the AEM Mobile Developer Tool becomes available.

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.

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

    aemm platform install android

  2. 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:

  1. 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.

  1. From Terminal, get the list of available simulator versions:

    aemm app install --list

  2. 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

    Megjegyzés:

    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:

  1. In Terminal, navigate to the directory that you want to manage the new project in.
  2. Create the directory structure (replace "<project name>" with your project name:
aemm project create <project-name>

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:

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

    cd <drag and drop the project-name directory>

  2. (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

  3. Open, install, and run the simulator build.

    aemm run <platform>

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

  4. 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.

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

    aemm run <platform> --list

  2. 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:

  1. From Terminal, navigate into the created project directory:

     cd <drag and drop the project-name directory>

  2. 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.

  1. Make sure that Node JS v6.2.2 or later is installed.

    If you previously installed the LTE version, we recommend that you download and install the current version.

  2. From Terminal, navigate into the created project directory:

    cd <drag and drop the project-name directory>

  3. Add the Cordova plug-ins (both core and custom) that you want to include in your app:

    aemm plugin add [plugin_0] [plugin_1] [...]

    To enable the standard Cordova plug-ins used in AEM Mobile apps:

    aemm plugin add aemm-plugin-application aemm-plugin-user aemm-plugin-context aemm-plugin-device aemm-plugin-inappbrowser aemm-plugin-fullscreen-video aemm-plugin-navto aemm-plugin-html-contract

    To change the default from UIWebView to WKWebView (same as selecting "WKWebView" in Plug-ins tab):

    aemm plugin add https://github.com/adobe-marketing-cloud-mobile/cordova-plugin-wkwebview-engine.git#2.0.0

    This currently uses version 2.0.0, but is subject to update. You can find the latest version to use here: https://github.com/adobe-marketing-cloud-mobile/cordova-plugin-wkwebview-engine/releases

    To enable all the core Cordova plug-ins used in AEM Mobile apps (remove the ones you don't want to use):

    aemm plugin add cordova-plugin-camera cordova-plugin-compat cordova-plugin-contacts cordova-plugin-device cordova-plugin-device-motion cordova-plugin-device-orientation cordova-plugin-dialogs cordova-plugin-file cordova-plugin-file-transfer cordova-plugin-geolocation cordova-plugin-globalization cordova-plugin-media cordova-plugin-media-capture cordova-plugin-network-information cordova-plugin-vibration

    Use this command to view a list of plugins added to the project:

    aemm plugin list

    Use this command to remove plugins previously added:

    aemm plugin remove [plugin]

    Use the help command to view additional information:

    aemm plugin help

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.

Megjegyzés:

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.

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

    sudo aemm platform install ios
aemm platform add ios

  2. 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.

  3. 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

    Megjegyzés:

    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:

     

    sudo /usr/libexec/PlistBuddy -c "Set DefaultProperties:CODE_SIGNING_REQUIRED NO" "$(xcode-select -p)/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/SDKSettings.plist"

    This workaround is required whenever Xcode is updated.

  4. (iOS) Package the .ipa file.

    aemm package ios --device <drag and drop .ipa file>

    Example:

    aemm package ios --device /Users/jdoe/Downloads/coffee_2062.ipa

  5. Do one of the following actions:

    • (iOS) Sign the modified .ipa file.
    • (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.

For more information, see Creating HTML articles for AEM Mobile.