Reminder - Digital Publishing Suite (DPS) will End of Life on August 31st, 2019.
by Derek Lu
Table of contents
15 March 2013
User level: Intermediate
Original publication date: 04/02/2012
Modified: 03/15/2013 (Change log)
authenticationService.login(). Using the API, you can access APIs that allow you to duplicate e-commerce functionality found in the default library and customize it to fit your project design. This article will get you started on using a template that has been created to enable users to swipe horizontally through pages and to view a folio preview when they tap a cover.
The store template offers a number of features publishers can leverage to enrich the user experience. Figures 1-4 show how these features look in the template.
Figure 1. Users can swipe horizontally to navigate within a section or click a tab to navigate to a different section. Folios in this section, called "Magazines" in this template, are populated from the API. Pricing information is obtained through the store APIs, which in turn access iTunesConnect for prices.
Figure 2. The Apps section lets publishers cross-sell items available in the app store. Pricing and all other metadata comes from a publisher-hosted XML feed. This section name can be modified as desired.
Figure 3. The Specials section displays folios that are specially offered and not part of the regular publishing schedule. Folios in this section are populated from the API.
Figure 4. If users click a cover, a scrollable preview of the folio is displayed. Previews are flat images created by the publisher and fetched at runtime via an HTTP request.
In order to make use of this store template you must have folios which are published as public. This store uses the API to populate the Magazines and Specials tab and uses a different XML file, apps.xml, to populate the apps tab. Folio covers are also served from the fulfillment server. All other images are hosted on your server.
In this template, the second tab is labeled "Apps," and the example depicts how publishers could cross-sell other apps that they might have in the iTunes App Store or Google Play marketplace. This tab could be renamed and repurposed for any other use, such as for selling physical goods. For example, it could be renamed "Shop," and you could swap out the links in the apps.xml file for URLs that point to goods on an e-commerce site.
If you unzip the horizontal_swipe_store.zip file, you will see the file structure displayed in Figure 5.
Figure 5. Top-level file structure of horizontal_swipe_store.zip
When setting up your store, there are two locations for files. One set of files will be embedded with your viewer by uploading a ZIP file to Viewer Builder. For a description of files that are uploaded to your server, see step 5 below. For a list of files that are zipped for Viewer Builder, see step 6 below.
The "images" folder contains the images used by this template. They should not be included in your store ZIP file, but should be uploaded to your server.
Figure 6. Requests across two different domains.
Here are the key files in the package:
- *AdobeLibraryAPI.js—The file that contains the library and store APIs.
- apps.xml—used to specify which apps should appear in the apps tab
- *backbone-min.js—open source application framework
- build.xml—Ant script used to aggregate the JS files in src into store.js.
- *jquery-1.7.2.min.js—JQuery library
- *offline.gif—displayed when the device is offline
- *offline.css—used when the device is offline
- store_dev.html—used for development on the desktop
- store_disabled.jpg, store_off.jpg, store_on.jpg—sample icon files for the store tab
- store.css—styles for the store, loaded remotely
- *store.html—used for production on the device or final testing on the desktop
Note: Files above with "*"should be included in the store Zip file for Viewer Builder.
To make use of this template with your own content, complete the following steps:
- Modify apps.xml so it is pointing to your apps (or other items you want in that tab)
- Modify src/view/main.js, then run build.xml to create a new store.js.
- Modify store.html so it is pointing at your web server.
- Create preview images of your folios.
- Upload files to your web server.
- Upload files to Viewer Builder.
The following sections explain these steps in more detail.
This XML file creates the list of app thumbnails in the Apps tab.
Each app node represents the data required to display one application. If you have more than one page of apps in the viewer, new pages will be automatically created. If you would like to market something other than an app, you can change the
appStoreUrlnode to link to something else. For example, you could link directly to your e-commerce page that is selling a hat.
This modification is only necessary if you would like to test your account on the desktop. Since the API file is not available on the desktop, this XML feed is used to display the folios.
On line 8, modify FULFILLMENT_URL so the
accountIdparameter matches your accountId. For information on finding your accountId, see the "Connecting to fulfillment" section in the Adobe article Building a custom storefront. Once you have your accountId, you will modify the value after http://edge.adobe-dcfs.com/ddp/issueServer/issues?accountId=.
On line 11, modify APPS_URL so the value matches the URL for where you will be hosting apps.xml.
On line 14, modify IMAGE_PATH_URL so the value matches the path to where your images will be hosted.
On line 17, modify PREVIEW_DIR if the subdirectory for your preview images will be different. This path is a subdirectory of IMAGE_PATH_URL. The preview images are the images that are visible when a user clicks a thumbnail.
In Eclipse, open build.xml in the Ant panel and run the concat target (see Figure 7).
Figure 7. Ant panel with build.xml
If you do not have Eclipse, you can alternatively modify the values specified above in store.js beginning on line 2979.
On line 10, change the
srcattribute so it is pointing at the location for where you will be hosting store.js.
On line 13, change the
hrefattribute so it is pointing at the location for where you will be hosting store.css.
Preview images are displayed when a user taps a thumbnail, as was shown in Figure 4. Preview images should not be wider than 567px nor longer than 3600px. Beyond 3600px, iOS will make the image appear scaled. Preview images should be named with the format <product-id>.jpg. So if your product ID is jan2012, then the filename for the preview should be jan2012.jpg. Images should then be uploaded to IMAGE_PATH_URL + PREVIEW_DIR. In the example files, this translates to http://lighthouse.adobe.com/dps/horizontal_swipe_store/images/previews/.
When your file modifications and images are ready, upload your images, apps.xml, store.css, and store.js to the URLs specified in step 2. Keep in mind that the image paths in store.css are relative to store.css, so the images should be in a folder named "images" on the same level as store.css. The file structure on your server should look similar to Figure 8.
Figure 8. File structure on the web server
To upload your files to Viewer Builder, you must first zip the following files:
Once your files are zipped, open Viewer Builder and navigate to the Navigation Toolbar section. For more information on Viewer Builder, see the Viewer Builder tutorial video. In the Navigation Toolbar section, there is a "+" icon in the lower-middle right of the screen which will allow you to add a custom slot (see Figure 9). Navigate to the zip file you created above for the store. Set the Lock Orientation menu to Portrait. Enable the Hide Title Bar and Auto Launch options. In the Label field enter Cover. This field is required but not used in this example. If you don't have any custom icons, you can use the provided store_disabled.jpg, store_off.jpg and store_on.jpg images.
Figure 9. The Navigation Toolbar section from Viewer Builder
- Bug fixes in sample file.
- Changed FULFILLMENT_URL so it uses a proxy.
- Updated to v2 of library/store API.