Getting started with the v2 Library and Store API

Enterprise customers of DPS can create custom stores or libraries using a JavaScript API that lets you duplicate e-commerce functionality found in the default library. By creating your own store or library, you can customize the UI to fit your needs. Custom stores and libraries are displayed in webviews and are implemented using HTML, CSS, and JavaScript. Since custom stores are implemented with these technologies, you are not limited by what the API provides. You can also do things such as display video, create a game, or cross-sell other items. This article will provide an overview of the API and provide steps on getting started with it.

There is also another API referred to as the reading API, available from within folios, that can be used to do things such as offer subscriptions from within a folio. The reading API has a subset of features offered by the library API. For example, you cannot purchase folios using the reading API. The API covered in this article is referred to as the library API.

Since the API is written in JavaScript, it is recommended that you know JavaScript, HTML, and CSS. For development, you can use any IDE you want. It is recommended to do as much testing as you can on the desktop before testing on the device. For the best animation results, developers should use CSS transitions and translate3d() so hardware acceleration kicks in automatically.

To use the API, you must have an enterprise account. Having an enterprise account will enable you to add custom tabs in App Builder, which are used to display your store or library view. Custom tabs can also be used to display content such as a FAQ, account settings, or a sign-on screen. To upload content to App Builder for your custom tab, you simply zip your files and add them to your custom tab.

For customers who previously used version 1 of the API, it is not possible to mix both versions of the API. You must use one or the other. The API is also only available from a custom tab or the entitlement banner. Unlike v1, which was injected into the page, v2 must be added using <script src="AdobeLibraryAPI.js"></script>. The script, included in the sample files, can either be included with your store files in the viewer or loaded from your server. Unlike v1, which opened <a> tags in a slide-up webview, as of this writing <a> tags open in the current window. So if you have any links that you would like to open in a new window, it is recommended to use an iframe as a workaround.

Typically, you work with the API through the use of one of the service objects. The available service objects are:

• adobeDPS.libraryService: Used to retrieve folios and to update the library.
• adobeDPS.authenticationService: Used for authentication.
• adobeDPS.deviceService: Used to get device information such as OS or network status.
• adobeDPS.receiptService: Used to retrieve receipts and get subscription information.
• adobeDPS.settingsService: Used to retrieve settings for the viewer.
• adobeDPS.analyticsService: Used to send custom analytics events.
• adobeDPS.configurationService: Used to retrieve application properties and to navigate between tabs.

Events are handled by assigning callbacks to signals. For example, folio.updatedSignal.add() takes a function as the parameter and is triggered when a property on a folio has been updated. Some API calls return transactions that have signal properties. For example, folio.purchase() returns a transaction so we can listen for the purchase to complete by using folio.purchase().completedSignal.addOnce().

To use the API, first download the sample files and save AdobeLibraryAPI.js to your store directory. Next, include it in your HTML page using <script src="AdobeLibraryAPI.js"></script>.
To get started using the API, keep these four things in mind:

1. Before calling any methods in the API you should make sure adobeDPS.initializationComplete is triggered. If you have a function called init() that you would like to call when the API is ready, you can trigger it by doing adobeDPS.initializationComplete.addOnce(init, this). The first parameter is a reference to your function and the second parameter is the scope in which it should be referenced.
2. After the API is ready, you can access the folios from adobeDPS.libraryService.folioMap, which is of type DocumentMap. The folios are stored in an associative array in a property named internal keyed by ID. To access the folios you would use adobeDPS.libraryService.folioMap.internal. You can also sort the folios on any of the folio properties. To sort by publicationDate descending you would use the following which returns an array of folios:

3. Sometimes adobeDPS.libraryService.folioMap is empty or does not have all of the folios at the initial launch of the app because the viewer has not gotten all of the folios from the server. Because of this, you should also listen for adobeDPS.libraryService.folioMap.addedSignal which is triggered when a new folio is discovered by the viewer. If you have a function called addFolio() that adds a folio to your UI, you could do something similar to the following, which loops through the added folios and adds them one at a time:

4. When working with Folio objects, you should always listen for folio.updatedSignal. This will be automatically triggered whenever a state of the folio changes. By adding a callback to this signal, folio.updatedSignal.add(this.updatedSignalHandler, this);, you can handle state changes such as if a folio is starting a download, changed to entitled or changed to installed. For example, if you call folio.download(), it will automatically trigger your callback for folio.updatedSignal where you can check to see if folio.state == adobeDPS.libraryService.folioStates.DOWNLOADING. If the folio is downloading, then you can update the UI to indicate download progress.

The sample files provided with this article serve as a bare-bones implementation of a custom store; see Figure 1.

As you can see from Figure 1, this sample implementation displays the folios as a grid and displays the buttons in bold. When a download is initiated, the download progress is displayed on the right. If a folio is downloaded onto the device, an Archive button will display.

After unzipping the files, if you look at index.html, you'll see it has an include for the API, jQuery, and main.js. The file, main.js, contains the JavaScript for the sample store and includes the starting points listed in the previous section.

1. Line 37 shows init() added as a callback for when the API is ready.
2. Line 8 shows a sort applied to adobeDPS.libraryService.folioMap.
3. Line 25 shows a callback for adobeDPS.libraryService.folioMap.addedSignal.
4. Line 65 shows a callback added to folio.updatedSignal.

Keep in mind that this implementation provides just the minimum and does not use all of the API. For example, it does not include subscriptions and it does not display folio preview images. The JavaScript is also kept in one file so it's easier to follow in this example.

To use the sample in your viewer, open App Builder and navigate to the Navigation Toolbar screen (see Figure 2). If you do not see any folios, verify that you have published public folios.

On this screen in App Builder, replace the default library by clicking "Use custom app library" and then navigate to the zipped sample files that you have downloaded by clicking the folder next to "Library HTML resources ZIP". Click through the rest of the screens and then test the IPA on your device.

Currently, to use v2 of the API, you must replace the default library with a custom library. If you do not, then v2 will not be available in your custom slots. However, if you want to use the default library and create a custom tab, please contact me for a workaround, delu -at- adobe.com.

When zipping your files for App Builder, be sure to zip at the file level rather than the enclosing folder. Also, don't name any folders or files "string" or "strings".

When testing your custom store on the device, it is recommended to load your files remotely from your store HTML page. The HTML will be uploaded in your ZIP file to App Builder, but the includes will be loaded remotely. For example, rather than using a relative path to your files, which would necessitate a new IPA build for each change, it is recommended that you use an absolute path to your server to load your JavaScript and CSS. This way, if you make a change to the JavaScript and CSS, you do not need to build a new IPA; rather, you can hard close the app and then restart to pick up the new files from the server.

When testing in-app purchases, you will want to make sure your user is logged out of the regular iTunes account; otherwise, the system dialogs, such as purchase, will not display.

In this article, you learned the basics of using the v2 Library/Store API for DPS. The following is a list of example templates that use the API.

• Creating an HTML implementation of the DPS default library
• Working with the combined library/store custom slot template using new DPS APIs
• Add separate library and store experiences with custom slot templates
• Using the iPhone library / store template with DPS projects
• Build a horizontal swipe storefront

To learn more about how to extend Adobe DPS to meet your business needs, watch the video of Klaasjan Tukker's MAX 2013 session, Extending and Integrating Digital Publishing Suite.