#aemm

I was recently tapped to assist with a project that involved creating mobile apps using Adobe Experience Manager Mobile (AEMM).  I know PhoneGap/Cordova well enough, and AEMM uses PhoneGap, so why not?!

I was asked to incorporate a custom plugin (one that AEMM does not already support in their platform) into the AEMM app.  This proved quite challenging, so I found myself taking copious notes as I trial and errored various steps. This guide takes you from start to finish!  Special thanks to the handful of Adobe folks that assisted me and reviewed this guide.

(Currently only for iOS AEM apps - please see the main Adobe page on custom plugins for other platform details (Android, etc.).  Feedback? Error correction? Please leave comment below.

Understanding AEMM

Adobe Experience Manager Mobile allows both technical and non-technical users to create and manage custom mobile apps all from one online portal.  Content (HTML, images) is created and updated within the tool, then published (pushed) to user’s mobile devices.  Each time they open the app, the latest updates are downloaded over the air – thus bypassing the app store review processes.  No coding skills are required, but advanced, interactive features can be added by developers.  The AEMM app is essentially a PhoneGap (Cordova) app, so plugins that add native functionality can be included (geolocation, accessing contacts, camera, etc.).  Custom plugins (any that Adobe doesn’t support out of the box) can be used too, but require more effort.

There are two flavors of app builds: “preflight” and “production”.  Preflight is for testing; it allows you to see staged, unpublished content.  Production builds (Preflight turned off) only show published content.

Prerequisite Downloads

An account on AEM Mobile On-Demand portal: https://aemmobile.adobe.com

For building an iOS App, a Mac computer.

XCode (v7.0 or greater)

AEM Mobile Developer Tool & Cordova (see below installation instructions)

Node JS (current stable version recommended)

AEM Mobile Signing Tool: Download from AEM Mobile website: Navigate to Apps page. Click “Download Signing Tool” in upper right hand corner.

Optional: AEM Mobile Packager: Utility to package HTML, JS, and CSS into an AEM Article file for upload to AEM Mobile website.  Not used currently.

Installing AEM Mobile Developer Tool & Cordova

Launch Terminal. Ensure Node.JS is installed beforehand.

Install AEM Mobile Developer Tool:

sudo npm install -g aemm

Install Cordova:

sudo npm install -g cordova

NOTE: AEMM wraps (sits on top of) Cordova commands.

Install the Simulator Build:

aemm app install ios

Configure iOS environment to allow XCode to build an unsigned framework (necessary for custom plugins):

sudo aemm platform install ios

Creating an App with a Custom Plugin

AEMM Prerequisites

Ensure these steps are complete first otherwise the app and custom plugin code may not work in AEMM.

Create Content (Articles) first.  An "Article" is essentially an HTML page with CSS, images, and JavaScript files.

From the AEMM website portal: Content & Layouts -> Content.

Use AEMM Mobile Packager Tool to bundle a set of HTML, CSS, and JavaScript files into an Article (.article) file.

NOTE: Plugins are restricted to the Article level.  The User must open the Article that references the custom plugin in order to execute it.  To access the plugin “globally”, add the custom code that references the custom plugin (JavaScript file) to an AEM App Template.

Ensure Articles have “Extensibility” turned on.  Without it, plugin code will silently fail/not run without warning.  On an individual Article, select an Article, Content Properties button, Article metadata, and check the “Enable extensibility features” box.

Even better, enable for all Articles by default: Project Settings -> Select Project -> Edit Project -> Content tab -> “Enable extensibility features” checkbox.

Create at least one Collection (Content & Layouts -> Collections).  Add desired Articles to the Collection.  Publish the Collection and the Articles.  Without publishing, Articles will not show in the completed App nor will updates be pushed.  Always re-publish Articles after updates are made.

Have an iOS Developer Account ready.  Identify test iOS devices and obtain device UDIDs (can use http://whatsmyudid.com/).  Create Provisioning Profile using UDIDs.

Create the App

Create the initial app using an AEMM template:

aemm project create [project name]

Write code that interacts with the custom plugin.  Add code files to “www” folder.

Create an “index.html” file.  Include reference to “cordova.js”:

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

This file is included at AEMM runtime – do not include an actual file!

In JavaScript file, add event listener for “deviceready” event.  Cordova in AEM will fire this event once Cordova has fully loaded, meaning it’s ok to use plugins. Calling plugin code before deviceready will cause errors.  Add script reference to JS file in index.html.

document.addEventListener(“deviceready”, function() {

               // Cordova ready, may call plugins now

} , false);

3. Change directory into the project (“cd project-name”), then install the iOS framework:

    sudo aemm platform install ios

4. Create or pull down the custom plugin and add it to the local project:

    aemm plugin add [plugin name]

To check that it installed correctly, run: aemm plugin list 

5. Compile/Build the iOS app for the iOS simulator.  Correct any errors:

    aemm build ios

Add --device to build the app for iOS devices instead of the simulator

Add --release to build a release version instead of default debug version

6. Test the plugin independently of AEM via the emulator and then incorporate into AEM.  See below.

Build the App for Release

When all Article content is finalized and the custom plugin works, you can create the complete iOS app.

From AEM Website (https://aemmobile.adobe.com):

Verify that all Content, Articles, and Collections are published.  Publish if not up to date.

Verify that all required Articles have “Enable Extensibility Features” flag turned on.

(First time) Create a new iOS App: Go to Apps page.  Click the Plus button.  Choose “iOS” under Platform, then Next button.

General tab:

Set App Name, Supported devices, etc.

Bundle ID: Must match the ID specified in the Apple Developer Member portal (https://developer.apple.com, “Certificates, Identifiers, & Profiles” -> Identifiers -> App IDs.  Format usually follows: com.companyName.appName. Ex: com.adobe.awesomeapp

Preflight: Disable if creating an App Store/distributed app.

Assets tab: Upload app icon and splash screens.

Plugins tab:  Select additional plugins to include.  Optional.

Click Submit button when ready.  You are taken back to the Apps page, and the App will be built. Adobe takes your project settings and configurations and bundles them into an iOS app file (.ipa).  Once the app has built, click the word “URL” under Downloads column to download the generated IPA file.

(Updates to custom plugin) Since the custom plugin code is injected into the IPA file, you must get a fresh IPA file and re-inject the plugin code.  Go to Apps page.  Select the App.  Click the Pencil Edit button. Make any metadata changes then wait a few moments.  Eventually, the “Submit” button will light up.  Click Submit.  Adobe creates a new app package. Download the generated IPA file. NOTE: This is the only way to force a new app build.

(Updates to Article content) Nothing extra to do.  Once you publish the content, Adobe pushes the changes over the air to the users’ devices.  

From Terminal:

Add the custom plugin to the downloaded IPA file: At this point, the app does not have the custom plugin code.  To add it, first change directory into the app project folder:

cd [app folder]

Run one last sanity check to ensure plugin is installed into the local project.  If it is, it will appear in the output.

aemm plugin list

Then, inject it into the IPA file:

aemm package ios --device [path to IPA file]

ex: aemm package ios --device /Users/joe/Downloads/coffee_app.ipa

A success message will output.

Wrap Up:

Sign the app using an iOS Developer certificate and provisioning profile.

If building a test version of the app, Adobe’s AEMM Signing Tool is handy.

If using AEM Mobile Signing Tool, a new IPA file will appear alongside the current one.  When deploying to devices or the App Store, pick the IPA file that ends with “-signed.ipa”.

Upload the App to the App Store.

(Optional) To copy to a test iOS device using iTunes: Open iTunes.  Using Finder, navigate to location where “-signed.ipa” app is.  In iTunes, click “Library”, then “Apps”.  From Finder, select IPA file and drag/drop it into the iTunes “Apps” window. If it works, a new entry for the app appears in the Apps list.

Plug in iOS test device to computer.  After a few moments, the device icon appears. Click it then choose “Apps”.  The newly added App will appear in the list.  Click the “Install” button, then “Sync” button to install onto the device.

If the app does not install or open properly, double check the device’s UDID in the provisioning profile, as well as the Developer Certificate.

Testing App Plugin Code Locally, before Incorporating into AEM Mobile

AEMM’s project template is slightly different than Cordova’s, unfortunately, so you have to do one extra step.  AEMM moves the “www” content one level lower in their projects (www/SampleArticle/[code] as opposed to www/[code]), so you must copy your code (HTML, CSS, JavaScript files) into the www folder temporarily for testing.

In Terminal, begin in the project directory. Compile/Build the iOS app for the iOS simulator and correct any errors:

aemm build ios

Open the iOS Simulator.  AEMM does not have an “emulate” option, so use Cordova:

cordova emulate ios

Once the Emulator launches, you can debug the web code of the app (JavaScript info/errors to the console, etc.) using Safari.  Open Safari, then go to Develop -> [Your Name]’s Macbook -> select available index.html file.  The Developer Tools load in a new window.  Click on Console tab to view info/errors.

Modifying the Custom Plugin and Testing It

Should additional functionality or changes be required of the customized plugin later on, follow these instructions:

Make your changes to the plugin files.  Beginning at [custom plugin] folder:

/src/ios folder: Contains the native Objective C code.

/www folder: Contains the web (JavaScript) interfaces that Cordova uses to create a “bridge” between native and web code.

Apply the changes to the app project that uses by custom plugin by first removing the old plugin code and re-copying in all changes.  (Note: there is a “link” flag option, but it doesn’t seem to work!)

Change directory into the project: cd app-project

Remove the old code: aemm plugin rm [plugin name]

Add the updated code (typically one level higher in folder structure): aemm plugin add ../[plugin name]

Build the app: aemm build ios

The new plugin code will be compiled.  Correct any errors.

Test/deploy using other instructions in this guide.

References

Using Cordova plug-ins in AEM Mobile: Tools to install (AEM Mobile Developer Tool) and commands to use in order to package the custom plugin into the App.

iOS Publishing Guide: Adobe’s complete overview of submitting to Apple App Store (certificate files, signing apps, publishing…).

Signing iOS and Android apps for AEM Mobile: How to use the AEM Mobile Signing Tool to sign an app, which permits it to be installed on a mobile device and/or uploaded to the Stores.