by Derek Lu

Derek Lu

Table of contents

Created

14 September 2013

Prerequisite knowledge
Experience working with the Adobe Digital Publishing Suite (DPS), HTML and JavaScript is required. In addition, familiarity with the DPS Reading API is useful.
 
User level: Intermediate
Documentation:
Reading API
 
Sample files
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
Note: If you have questions about this article, use the tutorial feedback link at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
With release 28 of DPS (September 2013), customers can leverage the camera and camera roll on an iOS device to deliver richer experiences to their readers by allowing them to customize articles by adding their own picture. This applies to both iPads and iPhones. Camera and camera roll access is done via a JavaScript API and can be used in an HTML article or web overlays within an article.
There are many ways the camera and camera roll can be leveraged. The purpose of this article is to help you understand how to implement this capability and to help you understand some of the possibilities of what you can do with this new functionality.
Some of the ways you could leverage the camera and camera roll include,
  • Allow a user to use their own image for the cover of an issue.
  • Allow a user to see how they would look in an outfit by placing an image of themselves within the outfit.
  • Allow a user to personalize a humorous card by inserting a headshot onto the body of another object such as a unicorn.
It’s important to remember that this capability is accessed via a JavaScript API, which means your content will need to be in either an HTML article or web overlay within an article.
In this article I’ll cover the first use case. The other use cases would use the same implementation but different graphics to change the context.
 

 
API Overview

The main functionality of the camera API allows you to:
  1. Allow the user to take a picture and have it in the context of an optional graphic supplied by you. This graphic can be a transparent PNG that allows you to overlay your image on top of the user’s picture.
  2. Allow the user to select an image from the camera roll and have it in the context of an optional graphic supplied by you. This graphic can be a transparent PNG that allows you to overlay your image on top of the camera roll image.
  3. Save the images above to the camera roll.
  4. Set the images above for an html article or webview overlay so it can be retrieved when viewing the page at a later time.
The API consists of two service objects, cameraService and profileImageService. These objects are automatically instantiated and accessed using adobeDPS.cameraService and adobeDPS.profileImageService. The cameraService is used to take a picture with the camera or select an image from the camera roll. The profileImageService is used to retrieve the image or save the image for the html article or web overlay. Each photo that is taken is unique to the html article or web view overlay from which it originated. This means if there are two webviews in an article they can both use the camera API and have different images saved.
The cameraService contains two methods, initializePermissions() and getPicture(successCallback, errorCallback, options).
If the user is accessing the camera roll for the first time they will see a dialog asking for permission. This dialog is only displayed once. If the user does not allow access but would like to at another time they will need to go to Settings > Privacy > Photos and turn permissions on.
 
Figure 1: Dialog asking for permission to access the camera roll
Figure 1: Dialog asking for permission to access the camera roll
 
If you will be allowing the user to access the camera roll, after the API is initialized via adobeDPS.initializationComplete, adobeDPS.cameraService.initializePermissions() should be called to display the permission dialog. If initializePermissions() is not called the dialog will display the first time getPicture() is called when accessing the camera roll. However, there is currently a bug in which the html article or web overlay refreshes if the permissions dialog is displayed as a result of a call to getPicture(). Rather than displaying the camera roll after a person clicks “OK”, the html article or web overlay is refreshed and the user has to click getPicture() again.
To take a picture with the camera or select an image from the camera roll you use adobeDPS.cameraService.getPicture(successCallback, errorCallback, options). There is currently a limitation in which after the picture is taken, the preview does not contain the overlay, however, the saved image will contain the overlay. If a picture was taken with the camera or selected from the camera roll, the successCallback will be triggered and passed the URL to the image. If there was an error the errorCallback will be triggered and passed two arguments, errorCode and errorMessage. The last parameter is a generic object that contains options for configuring the picture selection. The following is a list of the available properties and their values.
  1. pictureSourceType: adobeDPS.cameraService.PictureSourceType.CAMERA, adobeDPS.cameraService.PictureSourceType.SAVEDPHOTOALBUM, adobeDPS.cameraService.PictureSourceType.PHOTOLIBRARY. Whether to take a picture with the camera, from the camera roll or from a selection of photo streams. If this value is not provided a user dialog is displayed asking whether to open the photo library or camera.
  2. cameraDirection: adobeDPS.cameraService.CameraDirection.BACK, adobeDPS.cameraService.CameraDirection.FRONT. Used only when the camera is selected as a pictureSourceType.
  3. saveToPhotoAlbum: true, false. If true the selected image is saved to the photo album. The default is true.
  4. portraitOverlayImage: a path relative to the HTML file to the portrait overlay image.
  5. landscapeOverlayImage: a path relative to the HTML file to the landscape overlay image.
  6. popOverOptions: a generic object with properties x, y, width, height, popOverArrowDirection. Valid values for popOverArrowDirection are adobeDPS.cameraService.PopoverArrowDirection.ARROW_ANY, adobeDPS.cameraService.PopoverArrowDirection.ARROW_UP, adobeDPS.cameraService.PopoverArrowDirection.ARROW_DOWN, adobeDPS.cameraService.PopoverArrowDirection.ARROW_LEFT, adobeDPS.cameraService.PopoverArrowDirection.ARROW_RIGHT. Indicates where the camera roll selection popover should be displayed, the width/height and the arrow direction. Used only when accessing the camera roll. The x, y coordinates are relative to the containing webview.
  7. Overlay images should be PNGs. When an overly image is provided, the resulting picture’s dimensions will be the same as the dimensions of the overlay image. The images are merged to fit to the aspect ratio. When only one overlay image is provided, the camera overlay is locked to that orientation. If the image is taken in the other orientation, the resulting image is rotated and fit to aspect ratio.
    The profileImageService contains two methods, setImage(imagePath, successCallback) and getImage(successCallback, errorCallback). It allows the storage of an image for each html article or web overlay.
    To save an image for an html article or web overlay that was taken from the camera or camera roll, you must call adobeDPS.profileImageService.setImage(imagePath, successCallback). The imagePath is the path that was passed to the successCallback of adobeDPS.cameraService.getPicture().
    To retrieve an image that was previously set for an html article or web overlay, you must call adobeDPS.profileImageService.getImage(successCallback, errorCallback). If successful, the successCallback will be triggered and passed the URL to the image. If there was an error the errorCallback will be triggered and passed two arguments, errorCode and errorMessage. If an image was not previously saved the error callback will be triggered with “No profile Image present”.
    Since the camera API is accessible from a folio it is part of the reading API. This differs from the store/library API which is accessible from a custom slot. In order to enable the reading API, HTML articles and web overlays must have the Allow Access to Entitlement Information checkbox selected. The checkbox is available from Folio Producer at the article level for an HTML article and from the Web Content overlay panel. It is very important to select this checkbox. If something is not working, you should first check to make sure this checkbox is selected.
 
Figure 2: Checkbox that allows access to the Reading API from a folio
Figure 2: Checkbox that allows access to the Reading API from a folio
 

 
Sample Walkthrough

The sample files with this article demonstrate how to allow a user to insert their own image as the cover of a magazine. To see the sample files in action, download the zip and create an html article. Since this is an HTML article you will need to open Folio Producer and check “allow access to entitlement information” from the folio detail view. The following screen shots demonstrate the example files.
 
Figure 03: The view users see before a picture is taken or selected.
Figure 03: The view users see before a picture is taken or selected.
 
 
Figure 04: The dialog to select the camera or camera roll.
Figure 04: The dialog to select the camera or camera roll.
 
 
This dialog is triggered on line 60 using
adobeDPS.cameraService.getPicture(getPicture_successHandler, getPicture_errorHandler, options);
Figure 05: The view to take a picture. The button to take the picture is on the right in the middle. To switch cameras, users can click the camera icon in the lower right.
Figure 05: The view to take a picture. The button to take the picture is on the right in the middle. To switch cameras, users can click the camera icon in the lower right.
 
Figure 06: The view to select from the camera roll.
Figure 06: The view to select from the camera roll.
 
 
The coordinates and dimensions of this popover are set beginning on line 54
popOverOptions: {x: 380, y: 700, popOverArrowDirection: adobeDPS.cameraService.PopoverArrowDirection.ARROW_DOWN}.
 
Figure 07: The image in the HTML article after selecting from the camera view.
Figure 07: The image in the HTML article after selecting from the camera view.
 
 
The image is set on line 80 using ("#user-image").attr("src", imagePath + "?r=" + Math.random());. A random number is appended to the end so the image is not retrieved from the cache.
 

 
Where to go from here

This article showed an example of how to use the camera API. For information on debugging HTML webviews check out Debugging a custom iOS storefront or library. For more information on DPS visit devnet.
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.