Custom store example with authentication calls

In this article, you will learn how to use the example files that replace the default library so that you can view the utility of the authentication calls. The sample files in this article contain an HTML implementation of the library and store API integrated with your Entitlement Server. The template uses APIs that allow you to duplicate entitlement functionality found in the default library and customize it to fit your project. The sample works on both iOS and Android platforms.

Begin by downloading the sample files that are provided at the beginning of this article. The sample contains the HTML implementation and replaces the default library. You can use them as a separate tab of custom store in the iOS application and instead of the default library on Android. The figures below show the various views of the library.

Using the template

To use the provided template you must have already setup your Entitlement Server. The template uses the new library and store APIs to use the authentication calls. All other features are packaged with your viewer.

Download and decompress the sample files folder to see the contents.

Development considerations

During development, Adobe recommends that you first build and test your content on the desktop using Safari. This allows 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:

• authentication.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 with your own content, simply complete the following steps:

1. Modify index.html.
2. Change the test user name and password.
3. Upload files to App Builder.

The following sections describe each of these steps in more detail.

Modifying index.html 

To modify index.html, use the following steps.

1. Go to the login variable and change the test user name and password with some credentials that work for your Entitlement Server
2. If you want to use the code only under iOS, you can change the undefined parameter with null. However, this null parameter doesn't work in Android apps and the user isn't logged in.

Expected behavior

1. After you install the app, you will see screen similar with Figure 1 on Android and Figure 2 on iOS
2. You have two options either to log in using the default display box and entering manually the credentials or to log in with hard-coded values (NOTE: It's necessary to change the hard-coded values in the index.html file).
3. After you log in with one of the methods, you will see a screen similar with Figure 3 where the successful message, the user name and the token is displayed.
4. Now you have only one option: to Log out. After you click the button, it will appear a screen similar with Figure 4.

APIs used in this example

Here are the API calls used in this example:

1. adobeDPS.authenticationService.login() - Starts a login transaction and has three string parameters: user name, password, and authToken. Requires that isUserAuthenticated is false.
2. adobeDPS.authenticationService.userAuthenticationChangedSignal.addOnce() - Signal to indicate that the user's authentication state has changed.
3. 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.
4. adobeDPS.authenticationService.logout() - Starts a logout transaction on this Folio. Requires that isUserAuthenticated be true.
5. adobeDPS.authenticationService.isUserAuthenticated - Boolean variable that shows whether a user is currently authenticated. It returns true, if the user is authenticated.
6. adobeDPS.authenticationService.authService.userName - String variable that returns the user name of that user. It is null if the user is logged out.
7. adobeDPS.authenticationService.authService.token - String variable that returns the authToken associated with that user. It is null if the user is logged out.
   

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 explaining how to use the authentication calls:

• Authentication Service in Library and Store API
• Direct Entitlement API v2
  

Change log

07/11/2014

• Sample files were updated.