User level: Intermediate
Original publication date: 25/11/2014
Other required products:
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.
NOTE: The example below is using the Entitlement Server V2.
This option can be set for every account from the Account Administration tool of the Digital Publishing Suite.
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.
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.
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.
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.
Here is what the custom code does:
- After you install the app, you will see screen similar with Figure 3.
- Click the Login button and the custom Dialog box appears.
- After you insert some login credentials that works, the user is prompted with a welcome message and with the list of folios (Figure 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
There are also the following articles that can be ver useful: