Mobile Development Part 1 - Hybrid App Authentication

Introduction

OCLC has been exposing services through REST interfaces for several years now as part of the Worldshare Platform project. Last year, work to support Oauth2 authentication was completed, making mobile applications possible. The product team identified a use case - a staff circulation app for our WMS customers called Digby that allows student workers to take a digital pull list with them into the stacks and use the device's camera to scan bar codes as items are pulled. The scanner is also useful for marking items as in-library use when reshelving.

In this blog post, we will show you how to create a hybrid PhoneGap application that authenticates and retrieves an access token that can be used to access OCLC services. This application will run on both iOS and Android devices. 

In this three part series, we show how you can build this functionality into your own mobile app using WMS API's. We will cover

• Part 1 - Setting up a Hybrid Mobile Framework and Authenticating (this blog)
• Part 2 - Bar Code Scanning
• Part 3 - Working with WMS API's.

WorldShare Management Services is OCLC's cloud-based library services platform.  WMS member libraries can take advantage of a rich set of API functionality to build mobile apps to access library collection and circulation data. The recently announced Digby™ Mobile App allows student workers to perform staff functions right from the stacks.

Why we Chose Hybrid Mobile App Development at OCLC

This telling chart from Business Insider shows that the smart phone market is dominated by Android devices, with iOS holding a solid 15% of the market since 2014. Anecdotally, we suspect that in the academic world, iPhone adoption is higher. Library mobile developers need to serve two operating systems - iOS and Android.

source: http://www.businessinsider.com/smartphone-market-share-android-ios-windows-blackberry-2016-8

To reduce development complexity we wish to build applications with just one code base, so we turn to hybrid apps.. PhoneGap is the premier open source hybrid app framework. It uses the Cordova API and has a rich library of plug ins. We can develop web apps that will run on any device and be available from the Apple App Store and Google Play Store. With the advent of graphics accelerators in modern mobile browsers, the difference in performance from native applications is improved compared to past years.

Description of our Stack

Our mobile applications look like standard Web Apps, with the Cordova Engine, PhoneGap Plugins and the WebView manager enabling them to run in either iOS or Android Operating Systems. Ajax calls to services enable the business functionality. 

There are some differences from standard Web Apps that you should be aware of:

PhoneGap Plugins - Wiring Javascript to the Mobile Device Hardware and O/S

Our sample app makes use of just two PhoneGap plugins (see the config.xml file):

The InAppBrowser Plugin allows us to open a browser window to handle the Oauth2 authentication flow. The Console Plugin allows javascript console.log output to be viewed from the XCode and Android Studio consoles when running apps from there.

Enable Cross Site Requests and Configure the Viewport

One important difference between a web app and a PhoneGap app is that you can make Cross Origin AJAX Requests in javascript in a PhoneGap app because the mobile device acts as a local server. In a standard Web App, only CORS requests are allowed for Cross Origin Requests. We set the security policy as a meta tag to permit this.

Enabling UTF-8 and configuring the ViewPort for mobile-sized screens is also part of the header setup.

Working with the Cordova API in the Web App

The www folder contains the web app that will run on all three platforms. Here are the first two levels of folders:

www
├── css
│   └── index.css <--- styling for the app
├── img
│   └── logo.png <--- default PhoneGap logo.png
├── index.html <--- execution of the PhoneGap app starts here!
├── js
│   ├── app <--- folder that contains javascript files
│   ├── app.js <--- the entry point for the javascript.
│   ├── config.js <--- Oauth2 authentication values. config.js is created by copying over config-example.js
│   ├── libs <--- libs is added by the bower-install dependency when the build is run
│   └── require.js <--- configure the javascript dependencies that can be loaded by require.js
├── redirect.html
└── res <--- folder containing the default PhoneGap icon and screen were used.
├── icon
└── screen

We include the cordova.js API in the index.html file using a script tag to permit the webapp to access the PhoneGap functionality.

What is the difference between Cordova and PhoneGap? PhoneGap is a distribution of the Cordova API that is built upon it. So you will see that at a low level, we use the Cordova API throughout PhoneGap apps.

In the www/js/app.js file, use the deviceReady event made available by cordova.js to kick off javascript execution of the app. First we bind an event listener to the document:

document.addEventListener("deviceready", this.onDeviceReady, false);

then we can use that event to kick off the app in the www/js/app.js file:

deviceReady: function() { // do stuff}

Cordova fires the deviceReady event when the iOS or Android device has loaded the application, opened a browser window (known as a WebView) and is ready to start executing the application. The complexity of managing this for each device is handled by the cordova.js API no matter what the device.

To learn more about working with the cordova.js API, start with these two documentation links:

• The config.xml file - https://cordova.apache.org/docs/en/latest/config_ref/index.html
• Events - https://cordova.apache.org/docs/en/latest/cordova/events/events.html

Install the Demo App and Run It

To help explain our approach, we placed a starter PhoneGap application on the OCLC Developer Network GitHub Account that authenticates against OCLC services and returns an access token.

Prepare the MacBook Pro for Mobile Hybrid Development

1. Install XCode from https://developer.apple.com/xcode/
2. Install Android Studio from https://developer.android.com/studio/index.html
3. Install Android SDK 7.1.1 (API Level 25), Tools, Platform-tools and Build-tools
   1. From the command line, type android
   2. Check the items to install
   3. Go to tools → Manage AVD's and set up an Android Virtual Device like this.

4. Install Node Version 7.8.0 or greater from https://nodejs.org/en/.
5. Install npm Version 4.2.0 or latest (should come with the node install above). For more about node, see https://www.npmjs.com/.
6. Add this to your Mac's ~/.bash_profile file:  export PATH=$PATH:$HOME/.node/bin
7. Make sure GIT is installed. See https://git-scm.com/.

Install the mobile-example-one sample PhoneGap app

We created a sample starter hybrid mobile app that includes OAuth2 authentication and retrieves an authorization token from OCLC for use against WMS services.

git clone https://github.com/OCLC-Developer-Network/mobile-example-one.git

Request a WSKey

WMS Libraries:

1. Log into OCLC WSKey Management
   1. If you don't have a WorldCat.org account, create one here
2. Select "Request a WSKey"
3. Under Environment, select "Production"
4. Under Services, select "Configuration Platform Service" AND "WMS Circulation API"
5. Be sure to include your OCLC Symbol and Registry ID
6. Fill in the other fields as appropriate.

Non-WMS Libraries:

1. Complete the Request a Sandbox WSKey form
2. Under Services, select "WMS Circulation API"
3. In the "What is the reason for this request?" text box, include the following note:
   1. "Sandbox WSKey for DevNet blog example mobile app"
4. Fill in the other fields as appropriate.

Configure your Authentication Parameters

After your WSKey is created, copy www/js/config-example.js to www/js/config.js and fill in the missing configuration items.

Build mobile-example-one

Change to the mobile-example-one directory and execute the node build script.

node run build

This is what the build script does.

Configure your IDE

There are a lot of opinions about IDE's. We use IntelliJ Idea with the PhoneGap / Cordova Plugin. We can run our apps directly from IntelliJ on Android and iOS emulators and devices, as well as in the browser.

A free alternative to IntelliJ is Eclipse. See https://www.chupamobile.com/tutorial-android/getting-started-with-phonegap-in-eclipse-for-android-281

or https://www.adobe.com/devnet/archive/html5/articles/getting-started-with-phonegap-in-eclipse-for-android.html.

Run the App

The phonegap command line tool will be available from the root of the project.

For documentation, see: http://docs.phonegap.com/references/phonegap-cli/

In the Browser

From the command line

phonegap run browser

For iOS

phonegap emulate ios <-- iOS emulator

phonegap run ios     <-- iOS device plugged into the MacBook Pro

For Android

phonegap emulate android <-- android emulator

phonegap run android     <-- android device plugged into the MacBook Pro

Mobile Authentication - OAuth2 Flow Explained

We use the user agent / mobile pattern flow to authenticate and obtain an access token.

See: http://www.oclc.org/developer/develop/authentication/access-tokens/user-agent-or-mobile-pattern.en.html

Below is an example of what happens when we authenticate against a Sandbox Institution (128807, OCPSB) against the production services using the sample application we provided. It is important to note that the authentication request must be handled in a separate browser (InAppBrowser) where the user authenticates with an id and password. The client_id key simply permits the authentication to occur. If the user authenticates successfully, the  InAppBrowser returns an authentication token to the redirect URI, which the app detects. The app then parses off the information after the "#" mark on the redirect URI to get the token and associated information.

In the sample app, this flow is managed by the www/js/app/authorize.js file. By using events made available from the InAppBrowser, we can monitor the flow and be ready to pick up the redirect URI (if authentication went successfully), or handle the cases where it fails or hangs.

This diagram shows the happy path flow for user authentication.

Conclusion

In this blog we covered the work of spinning up a hybrid app and working through the authentication flow. Once that task is complete, we will be ready to include a bar code scanner in our app (Blog 2) and then use the barcode data to retrieve books off a pull list (Blog 3).