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
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.
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.
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.
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.
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.
Examples for Cordova plugins are available here:
https://github.com/Adobe-Marketing-Cloud/aemmobile-example-cordova-api/archive/master.zip
-
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 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.
-
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.
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.
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.
-
In the On-Demand Portal, build an iOS app and download the .ipa file. (See Building iOS apps for AEM Mobile.)
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.
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.
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.
Please install the necessary dependencies based on the OS:
- Mac OS X:
- Windows:
- Node JS (Current is recommended; v6.2.2 or later is required)
- Java
- VisualStudio Community 2015
- Python (v2.7 is recommended)
- Node JS (Current is recommended; v6.2.2 or later is required)
-
npm install -g aemm
sudo npm install -g aemm
Run npm install -g aemm (or sudo npm install -g aemm) again whenever an updated version of the AEM Mobile Developer Tool becomes available.
To emulate the Android build, you have to install the necessary Android SDK and configure the environment for running the Android emulator.
Configuring the environment for iOS (sudo aemm platform install ios) is required only for building apps that use custom Cordova plugins.
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:
Alternatively, you can specify the simulator build version. This will allow you to install an older version from the list of available simulator builds.
-
aemm app install <platform> <simulator-version>
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.
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.
- 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”.
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:
-
(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>>
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
aemm config --unset screenOrientation
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.
The project creates a default HTML content template, but you can add more to the list by doing the following:
-
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.
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.
-
Make sure that Node JS v6.2.2 or later is installed.
-
aemm plugin add [plugin_0] [plugin_1] [...]
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
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
aemm plugin list
aemm plugin remove [plugin]
aemm plugin help
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.
-
aemm build [platform]
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.
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"
-
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.
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:
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.
A Twitter™ és Facebook közzétételeket a Creative Commons jogi feltételei nem szabályozzák.