Prerequisite knowledge
Experience working with the Adobe Digital Publishing Suite is required. This article also assumes that you have used the authentication calls from the Library and Store API to log in to the Entitlement Server, on both Android and iOS platforms. To modify the files, experience with HTML, CSS, and JavaScript is recommended.

User level: Intermediate

Original publication date: 25/11/2014

Modified: 25/11/2014

Required products:

  • InDesign (Download trial)
  • Digital Publishing Suite, Enterprise Edition

Other required products:

  • Mac OS X — Used to view the template on the desktop with Safari.

Documentation
Direct entitlement starter kit

Your Direct Entitlement Service

Creating an HTML implementation of the DPS default library

Sample files
AuthwLibraryUpdate.zip

By downloading software from the Adobe website you agree to the terms of our license agreement. Read it before downloading.

In this article, you learn some of the differences that are between the Android and the iOS platforms and which can be seen as well in DPS. The sample files in this article contain an HTML implementation of the workarounds and which can be made so that the scenarios become similar on both platforms. The templates use APIs that allow you to duplicate functionalities found in the default library and customize it to fit your project.

Differences Overview

If the authentication calls are made directly from the custom storefront, using Javascript code and the available authentication APIs, there is a difference between the way the Viewer reacts on iOS versus Android. On iOS, the updateLibrary function is called automatically after the user is logged in. However, on Android, this function is called in the JavaScript code, so that the library is refreshed, after the user is logged in.

NOTE: The example below is using the Entitlement Server V2.

First Folio Free

This option can be set for every account from the Account Administration tool of the Digital Publishing Suite.

Figure 5. First Folio Free option

Feature not supported on Android

Being enabled, this feature entitles the most recently published retail folio to first-time users of an app. That way, when users download the app from the App Store, the most current issue can start downloading, providing a better initial experience for some publications. However at this stage, the First Folio Free is not a supported feature on Android. While the Android AppBuilder allows the First Folio Free to be selected, you should leave this option disabled. This is because of the fact that on Android platform, every time you install or un-install an application the sessionId changes. It is known that's one of the most important differences between iOS and Android platforms.

The call that shows that this option was selected or not is the one presented below. This is a POST method to subscriber.adobepublish.com which response contains the entitled productId corresponding to the folio.

Figure 6. First Folio Free call

Authentication calls

Here are some screenshots of the calls that are captured in Charles during the login process:

Figure 1. iOS Charles calls.
Figure 2. Android Charles calls.

The viewer logs in to Third-Party Entitlement Server making the SignInWithCredentials call to get the auth token and sends it to Adobe entitlement service. In this example, the entitlement server URL is https://dps.tukker.org.

The call that sends it to Adobe server is the second one in the iOS screenshot and the third one on Android. It accesses the address https://subscriber.adobepublish.com and the URL contains the integratorId and the accountId. Its response should create a unique ticket which is used further. Now, the device is marked as logged in.

The call to the http://edge.adobe-dcfs.com extracts the list of the productId that are created in the database for that specific account. It contains the accountId, sessionId, viewerVersion, and other details.

The last call from the Figure 1. is the one that differs on iOS than Android. That call is the one that update the library for the new logged in user. The response of this call contains the list of productIds that the user is entitled to. This is the call that needs to be done manually on Android and that is included in the sample code attached.

Development considerations

During development, Adobe recommends that you first build and test your content on the desktop using Safari. This will allow you to adjust the user interface (UI) without having to generate a new viewer to see each change. When testing on your desktop, the API file is not available, so the viewer loads the data from the Adobe fulfillment XML feed.

While testing on the desktop, ensure that you remove the include for AdobeLibraryAPI.js in the index.html file — otherwise you can't view the files in the desktop browser. When testing on the desktop, if nothing displays, open the debugger to check whether there are file paths that cannot be resolved. For more details on how to use the debugger, have a look on these two articles: Debugging a custom iOS storefront or library and Remote Debugging on Android with Chrome

The following list contains descriptions of the key files in the template:

  • AuthwLibraryUpdate.zip – The file that is uploaded to App Builder. It is included as an example. This file can be uploaded to App Builder as-is for testing purposes.
  • AdobeLibraryAPI.js – The file that contains the library and store APIs.
  • index.html — The HTML file used to display the content.
  • jquery.js — The jQuery library.

Modifying the sample for your Digital Publishing Suite projects

To use of this template, simply upload the .zip file to your Android App Builder and make sure that you have already correctly setup your Entitlement Server including your own integratorId that is added to the Adobe database.

Figure 3. Initial screen
Figure 4. List of folios after login

Here is what the custom code does:

  1. After you install the app, you will see screen similar with Figure 3.
  2. Click the Login button and the custom Dialog box appears.
  3. After you insert some login credentials that works, the user is prompted with a welcome message and with the list of folios (Figure 4).
  4. Now you have only one option: to Log out.

Here are the API calls used in this example:

  • adobeDPS.authenticationService.login() - Starts a login transaction and has three string parameters: user name, password, and authToken. Requires that isUserAuthenticated is false.
  • adobeDPS.authenticationService.userAuthenticationChangedSignal.addOnce() - Signal to indicate that the user's authentication state has changed.
  • adobeDPS.authenticationService.displaySignIn() - Asks the authentication service to present the native sign-in UI. If currently authenticating or already signed in, UI is not shown.
  • adobeDPS.authenticationService.logout() - Starts a logout transaction on this Folio. Requires that isUserAuthenticated be true.
  • adobeDPS.authenticationService.isUserAuthenticated - Boolean variable that shows whether a user is currently authenticated. It returns true, if the user is authenticated.
  • adobeDPS.authenticationService.authService.userName - String variable that returns the user name of that user. It is null if the user is logged out.
  • adobeDPS.libraryService.updateLibrary() - Starts a library update transaction. This is the line of code that calls https://subscriber.adobepublish.com for the list of entitled products
  • adobeDPS.libraryService.folioMap() - Object that contains the list of folios by id

Where to go from here

In this article, you learned how to modify and add a custom library/store that contains the all the authentication calls. Also, you know how to use them so that you customize your own custom store. If you would like more information on the JavaScript libraries used, check out the documentation for Backbone, jQuery, and Underscore. See additional articles and videos available for Digital Publishing Suite on the Adobe Developer Connection.

There are also the following articles that can be ver useful:

Change log

25/11/2014

  • Sample files were updated.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy