Prerequisite knowledge
 
  • This article assumes that the user has a basic understanding of AEM and Digital Assets Management (DAM), as well as experience building Adobe AIR Apps for iOS and DPS Enterprise apps.
User level: All
 
Required Adobe products (retail)
 
Additional products (third-party/labs/open source)
 
Sample files
 
By downloading software from the Adobe website you agree to the terms of our license agreement. Please read it before downloading.
 

 
NoteIf you have questions about this article, use the DPS forum. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 
Introduction

While using DPS for sales enablement in corporate publishing,  a common requirement is to distribute documents such as sales and marketing collateral along with interactive DPS folios. The Companion App is an iPad viewer app that downloads, caches, and displays assets such as PDF and PPT files from a CMS file storage system (in this case, an AEM DAM). The viewer is a Stage WebView that displays the asset. The users may also choose to view the asset using other applications registered to the OS via the AIR Native Extensions (ANE). The Companion app is launched using a custom URL scheme and can be configured to be paired with a custom storefront in a DPS app for seamless navigation between the apps.
 
This article will provide information on:
 
  1. Customizing and Building the Companion App
  2. Invoking the Companion App
  3. Launching the app from a demo page

 
Customizing and building the Companion App

The Companion app needs to be packaged into an IPA archive, so that it can be deployed to an iPad.  This app requires the Adobe AIR 4.0 SDK, the link for which is available in the Resources section.
 
This guide provides step by step instructions on how to build the application.  Adobe Flash Builder 4.7 is used to build the application with the provided source.
 
 
Setting up Flash Builder 4.7
  1. Download Adobe AIR 4.0 SDK from:
    http://helpx.adobe.com/air/kb/archived-air-sdk-version.html
  2. Install Adobe 4.0 SDK.  For detailed instructions, see the Resources section.
  3. Import the project "AirDownloader" into Flash Builder from companion_source.zip.
    File > Import > General > Existing Projects into Workspace
  4. Set the AIR SDK:
    Open Project Properties from Package Explorer.
    • Under "Flex Compiler," choose "Configure SDK".
    • Add a new SDK definition pointing to your newly installed Air 4.0 SDK, and give it an easily identifiable name and apply changes:
  5. Example - C:\Program Files\Adobe\Flash Builder 4.7\sdks\4.6.0 (4.0)\
     
  6. Set up the ANE:
    • Open Project Properties from Package Explorer and under Flex Build Path, select the Native Extensions tab.
    • If there is an invalid ANE path, remove it and add new ANE file pointing to SalesCollateralDownloaderAne.ane, included in this package.
Example - C:\Companion\SalesCollateralDownloaderAne\SalesCollateralDownloaderAne.ane
 

 
Building and deploying the app

Building:
 
  1. In Flash Builder, select Project > Export Release Build.
  2. Uncheck Google Android if checked, and make sure Apple iOS is selected in target platforms.
  3. Export as: Signed packages for each target platform. Select Next.
  4. Under Deployment Tab:
    • Export application with captive runtime
  5. Under Digital Signature:
    • Find your Developer Certificate and your Developer Certificate Password
    • Select your provisioning profile
  6. Under Native Extensions:
    • Select the AIR ANE which has been added and check off package (If there is still an invalid ANE, it will be removed after building).
  7. Click Finish to build.
  8. With the packaged IPA file, the app can be deployed to the device via iTunes.
 
Customizing the Companion App
The Companion App has several fields that can be modified for different applications.
 
Custom URL: The app has a custom URL scheme that can be changed as per the user’s requirement. Default value is: toolkitcompanion://
 
With the Companion App installed, navigating to a URL with this URL scheme will invoke the app.  This can be customized in SalesCollateralDownloader-app.xml.
 
<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>toolkitcompanion</string> </array> <key>CFBundleURLName</key> <string>com.adobe.readiness.toolkit.companion-enterprise</string> </dict> </array>
Modify SalesCollateralDownloader.mxml file with changes incorporated in SalesCollateralDownloader-app.xml.
 
static private var SALES_COLLATERAL_CUSTOM_URL:String = “toolkitcompanion://"; private var NO_INTERNET_CONNECTION:String = "Error occurred, check your internet connection."; private var URL_ARGUMENT_INDEX:int = 0;
The previous two values for the custom URL must match for the app to work properly.
 
Paired App URL: To return to the custom storefront that invokes the Companion App, the URL scheme for the custom storefront must be configured. This can be done in FileViewer.as and the property: VIEWER_CUSTOM_URL.
 
public class FileViewer extends View { static private var VIEWER_CUSTOM_URL:String = "readinesstoolkit://"; static private var NEEDS_RELOAD_EXTENSIONS:Array = ["jpg", "jpeg", "gif", "png", "bmp", "tif", "tiff"]; private var file:File; .. }
 
ANE
An AIR Native extension has been provided for the Companion app. It allows users to share or open the asset using the native “App Chooser” for iOS (Figure.1).  The source is found in the folder SalesCollateralDownloaderAne and also in a compiled .ane file (that is used in this tutorial).  The ANE can be modified but this will not be covered in this article.  For more information on ANEs, see the Resources section.
 
Figure 1. Companion App ANE
Figure 1. Companion App ANE
 
 
 
Using another CMS with the Companion App
The Companion app is set up by default to be used with an AEM DAM.  However, it can also be modified to be compatible with other CMS.  For an AEM DAM, if the asset is public, the only requirement to invoke the app to display the asset is the path in the DAM. You can find more information on invoking Companion App in the next section.
 
Example - toolkitcompanion://myDemoAEM.com/content/dam/assetName.png
 
Similarly, if another CMS is used and the asset is public, the only requirement to display the asset is its path.
 
On the other hand, if an asset is protected in the AEM DAM, in addition to the file path, a valid AEM login-token is required for access.
 
Example - toolkitcompanion://myDemoAEM.com/content/dam/assetName.png?token=logintoken
 
Likewise, if an asset is protected in another CMS, the correct credentials must be set or passed in order to gain access to the asset.
 

 
Invoking Companion App

The Companion App is invoked using the custom URL scheme of the app (Default value is: toolkitcompanion:// ).  It is up to the developer to decide how to call the URL and pass in the relevant parameters for invoking the app.  The Readiness Toolkit uses a collateral view, where pressing “Download” for a specific asset will launch the Companion App to display the corresponding asset.  Once an asset has been downloaded, it is cached in the Companion App’s application storage for quick access and will remain there until deleted, or flagged to be updated.
 
Figure 2. Readiness Toolkit Collateral View
Figure 2. Readiness Toolkit Collateral View
 
 
 
Input Parameters
Certain parameters need to parsed while invoking the Companion app to enable the app to perform different actions. These parameters can be edited in SalesCollateralDownloader.mxml under SalesCollateralDownloader::downloadUrl().
 
In SalesCollateralDownloader::downloadUrl(), there is a call to FileDownloader::requestFile() which is the method that makes the request to the server to download the file. These two functions can be modified to customize the app to be used with different CMS.
 
 
SalesCollateralDownloader::downloadUrl()
This function parses the URL that is passed into the Companion app when it is invoked. The parameters should be determined by how the asset is set up on the CMS.
 
path: The path on the CMS to the desired asset (in the demo, an AEM DAM). This is the path to asset and will not likely need any modifications.
 
Example - toolkitcompanion://mydemo.com/content/dam/assetName.png
 
action: The action to perform for the asset. Valid values are: update, delete, and deleteAll. If no action is specified, then it either downloads the file and displays or displays the cached version if it already exists. This parameter can be used to specify if an asset needs to be downloaded again due to an update.
 
token: The login token required for authorization to access the asset on the CMS (if the asset requires authorization; otherwise it is empty)
 
slot: The application slot from a DPS storefront (clicking on ‘back’ will take the user back to this slot)
 
folio: The folio viewed from a DPS storefront (clicking on “back” will take the user back to this folio)
 
An example invoke call for an asset that requires authentication to access would be:
 
toolkitcompanion://mydemo.com/content/dam/assetName.png?&token=loginTokenValue
 
After all the parameters are parsed, the app will call FileDownloader::requestFile() to download the asset from the CMS.
 
 
FileDownloader::requestFile()
This function takes the entered parameters and constructs a GET request to download the asset from the CMS. If the file has been viewed before, it will load from the application’s cache, unless it is set to update by the action parameter. For public content, no authorization headers or cookies need to be attached to the URL request. For protected content, an authorization header or cookie containing a login token for the CMS may need to be attached to the request to gain access to the asset. For example, protected assets on an AEM DAM require a login token added as a cookie to the URL request:
 
… urlRequest.method = URLRequestMethod.GET; urlRequest.contentType = 'application/json'; // Create authorization request header urlRequest.requestHeaders.push(new URLRequestHeader("Cookie", "login-token" + "=" + token + ";")); …
To use with protected content on other CMS, check to see what type of authorization is needed to gain access to the content and make the appropriate changes to the parameters and the URL request.
 

 
Demo Page

A Demo page has been included to show how the Companion App can be invoked. This demo page assumes that the Companion app is using the default URL scheme (toolkitcompanion://).
 
The demo page provides a link to several assets in the DAM. Clicking on the demo page will launch the Companion app which downloads and displays the asset. All the assets provided do not require authorization to view, so the CQ token is not added as a parameter when the app is invoked.
 
To set up the demo page, authoring and publishing instances of AEM are required.  Please refer to Resources section for more information.
 
Figure 3. Demo Page pointed to demo AEM server
Figure 3. Demo Page pointed to demo AEM server
 
To run the Demo page:
 
  1. Navigate to the package manager (http://<authorServerAddress>/crx/packmgr) of the AEM authoring instance. Upload and install companion_demo.zip.
  2. Once installed, replicate the package to the published instance.
  3. On an iPad with the Companion App installed, use Safari to navigate to: http://<publishedServerAddress>/content/demo.html
  4. Enter the published server address into the form. There are 3 different file types available; click Show to view the desired asset in the Companion App.
Figure 4. PDF Asset in Displayed in Companion App

Figure 4. PDF Asset in Displayed in Companion App
 
 
Where to go from here

The Companion App is a versatile tool that can be customized to suit different applications. This article explained on how the Companion App can be used to view assets in a DAM. The Companion App is most effective when paired with a custom storefront as it can navigate seamlessly between the apps. So, try integrating it with this method. For more information on custom storefronts, see the Resources section.
 
 
Resources
Visit www.ensemble.com to learn about how Ensemble can help you create, integrate, and customize DPS apps and more.
 
Adobe AIR 4.0 SDK
 
Overlay Adobe AIR SDK in Flash Builder
 
Setting up AEM server
 
Installing Authoring and Published AEM Instances
 
Additional Reading on AIR Native Extensions
 
Information on Developing Custom Storefronts
 
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.