Saturday, July 25, 2015

OAuth with Meetup and PhoneGap

Why?

Many sites like Facebook, Google, Meetup etc have APIs to allow third party applications perform actions on behalf of users.This integration provides powerful features and better user experience. Imagine ability to share a thought originally posted in your application to be shared on Facebook and Twitter automatically. Or comment on a meetup event from your mobile app.

OAuth allows third party apps securely access website or application on behalf of the user. User doesn't share user id password to third party application. Rather will authenticate with the original application. User will be prompted for set of features to authorize. If user authorizes successfully, the third party application could perform actions on behalf of the user.

 What?

In this blog, let's take a mobile app developed using Phone Gap authenticating with Meetup site. If user authenticates and authorizes the app, will access secure Meetup API on behalf of the user. Let's use C# for server side code. It could be a Web Site deployed on Cloud like Azure or a server within your premises.

In this blog we follow Server workflow where app authenticates with the website once. Unless user goes to Meetup site and resets access, app can continue to use the access provided. App is expected to securely store tokens on the server.

Note: 

Meetup OAuth allows user with an implicit flow where a third party app can authenticate user with Meetup site and use the resultant code to perform actions on behalf of the user. This is simple to use and App is not expected to store anything. The code will expire after a limited period of time. After that application need to authenticate again. Assuming the application is a web app in a browser, user is already logged into Meetup site on the machine, he/she won't see log-in prompt again. If not the user will get the login repeated.

This blog doesn't use this workflow, rather uses a more elaborate server workflow that doesn't involve user again as much as possible.


Following depicts server flow
Let's go through above steps 

Get access to use Meetup API (one-time)

To present Meetup login screen launch following Meetup URL. As mentioned above with OAuth user directly authenticates with the original site. No credentials are provided to the third party app.

'https://secure.meetup.com/oauth2/authorize?client_id=YOUR Key&response_type=code&redirect_uri=http://localhost/my_app'

App needs to register with Meetup at this link. Client Id in above URL is a key. This is how meetup identifies the third party apps.

In the same page you need to specify a redirect Url, once authenticated successfully Meetup redirects to this Url. In the example it's  http://localhost/my_app.  When redirected Meetup responds back with User Token in query string. 

In Phone Gap this could be achieved using InAppBrowser plugin. Install In App Browser with the following command

cordova plugin add org.apache.cordova.inappbrowser

In the Phone Gap app launch a new window (that uses InAppBrowser) to present Meetup login screen to the user.

var windowReferece = window.open('https://secure.meetup.com/oauth2/authorize?client_id=YOUR_Key&response_type=code&redirect_uri=http://localhost/my_app', '_blank', 'location=yes')

// As callback Url starts to load, handle the returned Url to get user token
windowReferece.addEventListener("loadstart",function(event){
if(event && event.url){
var replyUrl = event.url;

// extract token out of the Url
var token = replyUrl.substring(replyUrl.indexOf("code=")+5);
if(token.indexOf("&") >= 0){
token = token.substring(0,token.indexOf("&"));
}
                console.log(token);
}
});

Send given token to your API server, that handles rest of authentication and makes secure Meetup API calls. In this sample, I'm using C# server side code to further authenticate and get access tokens for secure meetup API calls.

Consider following code to get Access Token using User Token generated in the Phone Gap app,

            #region Create Request to get access token

// Client Id and secret are generated while registering with Meetup earlier at this link

                var requestContent =
    "client_id=Your client id&" + // 
    "client_secret=your client secret&" +
    "grant_type=authorization_code&" +
    "redirect_uri=http://localhost/my_app&" +
    "code=" + [[ user key obtained from Phone Gap app ]];
            WebRequest request = null;
            try
            {
                // Meetup OAuth API that gets access token
                request = WebRequest.Create("https://secure.meetup.com/oauth2/access");
                
                var requestBytes = Encoding.UTF8.GetBytes(requestContent);
                request.ContentType = "application/x-www-form-urlencoded";
                request.Method = "POST";
                request.ContentLength = requestBytes.Length;
                var requestStream = request.GetRequestStream();
                requestStream.Write(requestBytes, 0, requestBytes.Length);
                requestStream.Close();
            }
            catch (Exception exception)
            {
                Logger.LogError(exception);
                return string.Empty;
            }

            #endregion Create Request to get access token

            #region Make calls and handle response

            try
            {
                var response = request.GetResponse();
                var statusCode = ((HttpWebResponse)response).StatusCode; 

                 // Add checks based on status code.

                var responseStream = new StreamReader(response.GetResponseStream());

               // Response includes Access Token and Refresh Token. Store them (may be in DB) for Meetup API calls to use

                return responseStream.ReadToEnd();

            }
            catch (Exception exception)
            {
                Logger.LogError("Error while reading response obtained from OAUTH call. ", exception);
                return string.Empty;
            }

            #endregion Make calls and handle response

Make Secure Meetup API calls 

Above call returns Access Token, which could be used with any Meetup API that needs authentication. Consider following code

request = WebRequest.Create("https://api.meetup.com/2/member/self/");

// OAuth Access Token is passed along in request headers
                request.Headers.Add("Authorization", "Bearer " + ACCESS_TOKEN_OBTAINED_ABOVE);
                request.Method = "GET";
                
                var response = request.GetResponse();
                var statusCode = ((HttpWebResponse)response).StatusCode; 

                var responseStream = new StreamReader(response.GetResponseStream());
                var data = responseStream.ReadToEnd();

Remember, this access token is valid for 60 minutes only. After that request for access token again. Does that mean user need to be involved again? No. Use refresh token obtained in the first server side call to request for access token now on.

Following will be the request content to Meetup OAuth URL with refresh token

                var requestContent = "client_id=your client id&" +
                                     "client_secret=your client secret&" +
                                     "grant_type=refresh_token&" +
                                     "refresh_token=" + refreshToken;

That's it. Let's build some cool apps that integrate with Meetup.

For further reading and reference:
Meetup OAuth documentation
Phone Gap - Getting Started
What's Phone Gap - A basic explanation
Another way to do it - PhoneGap Plugin for OAuth
AngularJS Way - ng-cordova-oauth

Monday, June 22, 2015

AngularJS + Material Design = ngMaterial

Image Reference
 http://material-design.storage.googleapis.com/
Google’s Material Design is beautiful. A lot of work seem to have gone into building such a sophisticated UI design paradigm. Material Design aims to get UI elements close to real world objects like paper. They carefully observed light, shadows and various other aspects before coming up with design paradigm for Material. As a side note, it has some inspiration from Metro design but improved it further.

Material design understandably has lot of presence in Android. Many developers adopted design guidelines and built beautiful apps.

image ref: www.polymer-project.org
On the other hand web too is getting traction towards Material Design. Polymer’s paper elements look and perform smooth. AngularJS community is aiming to come up with UI elements that confine to Material design standards. Angular Material is an internal Google project in that direction.



How do I get started with Angular Material?


npm install angular-material
or
bower install angular-material

Angular Material has following dependencies. Include these scripts to get started.
i)                    AngularJs – of course
ii)                   ngAria – ARIA stands for Accessibility Rich Internet Applications, a W3C spec for assistive technologies.
iii)                 ngAnimate – For animations of UI elements and transitions.
iv)                 ngMaterial – All directives and services of Angular Material Library

Create your module for the app

<body ng-app=”ngMaterialSample”>
     <script>
// Angular Material module name is ngModule      angular.module(‘ngMaterialSample’, [‘ngMaterial’]);
     </script>
</body>

Responsive UI


Material design aims to fit all screensizes and devices. That’s


a huge spectrum from big screen TVs all the way to smart watches.
Angular Material depends on Flexbox CSS3 for consistent UI across screensizes, devices and responsive aspects of the UI. It is attribute driven.
Use layout=”row” or layout=”column” to arrange elements horizontally or vertically.
Following creates a Material Design style toolbar using ngMaterial directive. It has a Button and Title. Just so that they don’t wrap over to next row, it’s called-out to be a row.

<md-toolbar layout=”row” layout-padding>
<div class="md-toolbar-tools" layout="row" >
    <md-button >
        <ng-md-icon icon="menu" size="24" style="fill:white" layout="row" layout-align="center center"></ng-md-icon>
    </md-button>
</div>

<h2>Welcome to Angular Material</h2>
</md-toolbar>

Note: all ngMaterial directives start with md-. Following code snippet has another directive md-content which is like workspace of the page or widget in question.

<md-content layout-padding>
    <div>
<!--
The directive “input container” expects two elements Label – the text that animates as you click and start typing in the text box and the text box it self. -->

        <md-input-container >
            <label>First Name</label>
            <input type="text"/>
        </md-input-container>

        <md-input-container >
            <label>MI</label>
            <input type="text"/>
        </md-input-container>

        <md-input-container >
            <label>Last Name</label>
            <input type="text"/>
        </md-input-container>
    </div>
</md-content>

Code above aligns all elements vertically. To make first name, middle initial and last name appear in one line add layout=’row’ on the div parent.

But on a smaller screen it gets congested. They need to be lay'ed out in one column. use layout-sm=’column’. "sm” being small, under 600px screen width. 





Following is the complete list of attributes you could use. They could be used with most/all of flexbox attributes.

-sm
Devices less than 600px wide.
-gt-sm
Devices greater than 600px wide.
-md
Devices between 600px and 960px wide..
-gt-md
Devices greater than 960px wide.
-lg
Devices between 960px and 1200px.
-gt-lg
Devices greater than 1200px wide.

 I’ve the following seed project to get started with Angular Material.

It uses various directives (md-tab, md-cards, md-grid, md-sidenav, md-toolbar etc.) and services ($mdMedia, $mdToast $mdBottomSheet).

Calling out $mdMedia service – helps figure screen dimensions by previously listed table. Consider following code,

// variable is true if screen is greater than medium
$scope.isVisibleOnCurrentScreenSize = $mdMedia("gt-md");

Little more about the seed project,


How do I get started with the Seed Project?


1. Clone seed project from here
2. Open command prompt at project location and perform npm install.
3. Run the project on any local web server.

Note: As you make changes to the project run browserify main.js o- app.js

Tech Stack


1. Angular Material


Angular Material Library. It makes it easy to develop Material design app using AngularJS. It depends on AngularJS, Angular Aria and Angular Animate. 

2. NPM


Node Package Manager - takes care of installing the library in question and all it's dependencies.

3. Common JS


Module loading within JavaScript made easy. NodeJS style of writing code. It works pretty well with NPM packages.

4. Browserify


Unlike node servers, browsers by default don't work with CommonJS. This makes it compatible. 



In conclusion, I’m excited about ngMaterial. At this point, one need to tread carefully as it’s still RC4 (at the time of writing this blog). But it’s promising for developing rich Material Design apps with AngularJS pretty soon.

Sunday, January 18, 2015

Push Notifications for Phone Gap App using GCM and Mobile Service

Push Notifications are part of our lives everyday. We get alerted about new emails, news updates, What's app, Facebook Twitter messages so on every hour (or every minute for some :D ). When an app is running, it could request for data and present it on the screen.Push Notifications alert user with information even when the app is NOT open. For example email alert appearing even when the email app is not running on the mobile device.

Windows Azure Mobile Services (integrated with Notification Hub) simplifies sending notifications to multiple mobile platforms, Android, iOS, Windows Phone 8 etc. In this blog, I'm writing about Android Notifications. Will be writing about other mobile platforms (using mobile services) in upcoming blogs.

Here is the agenda for this blog,
  1. GCM (Google Cloud Messaging)
  2. Azure Mobile Services for sending Push Notifications
  3. Phone Gap App registering and receiving notifications

GCM for Android:

For an app installed on your Android device, GCM can send messages over the internet even when the app is not open. It has the ability to queue messages when the device is offline and send it when connected (if message doesn't expire). These messages popup in the notification area. App can be launched when user taps on a notification.

Refer to the image depicting steps involved in sending push notification using GCM. This is one of the ways to use GCM. For the case I'm describing in the blog, with Azure Mobile service, this design fits.

In the five step process described in the image, i) each phone registering with GCM for notification will get a reg id. App will store Sender Id/Project number and send it in the request to get reg id. ii) Developer need to generate API key through Google Developer Console and use it while sending Push Notifications. This way GCM is sure sender of the message is owner of the app.

Azure Mobile Service

Azure Notification Hub allows sending Push Notification to cross platform devices and apps. Mobile Service is integrated with Notification Hub allowing easy notifications. It acts as the server in above architecture. It automates most part of action 4 i) Saving reg Ids, ii) Storing API key and verifying with GCM and iii) Provides easy API for sending notifications. It also provides ready made client libraries for making GCM calls and registration with notification hub.

Let's get the app ready!

  1. Setup in Google Developer Console.
  2. Setup Mobile Services 
  3. Add Push Notifications to Hybrid Mobile App.

Setup in Google Developer Console.

  1. Log into Google Developer Console http://console.developers.google.com
  2. Click Create New Project, provide Project Name and click Create.
  3. Make a note of Project Number, that is the Sender Id.
  4. Click on the project to get into details view.
  5. In the left navigation panel, select Credentials under API & Auth.
  6. Click Create New Key. In the popup window, select server key.
  7. Make note of generated API Key.
  8. Click on APIs under APIs and Auth and make sure Google Cloud Messaging for Android is "ON"

Setup Mobile Service:

Log into Windows Azure Management Portal.
Enable Push Notifications on Mobile Services for GCM.
  1. Select the Mobile Service providing Push Notification functionality.
  2. Click on Push tab.
  3. Under Google Cloud Messaging Settings, specify API Key noted from Google Developer Console.
Update script that triggers Push Notification
  1. Select Data tab and click on table that need to trigger Push Notification.
  2. Click on Script tab.
  3. Select appropriate action among Insert, Update, Delete or Read. And update following code. (read descriptions in the comments)
// add additional behavior to request.execute for Push Notification.
request.execute({
       success: function() {
           // template for the payload
           var pn= '{ "message" : "Sample push notification" }';
// push.send notifies all configured mobile platforms (iOS, Android, WP8) etc. Using push.gcm.send for GCM only.
// first parameter of send specifies all tags. 

           push.gcm.send(null, pn, {
               success: function(response){
                   console.log("Sent push:", response);
                   request.respond();
               },
               error: function (error) {
                   console.log("Failed to send PN", error);
                   request.respond(500, { error: pushResponse });
               }
            });
       }
   });

Enable Phone Gap mobile app to send Push Notifications:

Add push plugin-
cordova plugin add https://github.com/phonegap-build/PushPlugin.git

Device plugin
cordova plugins add https://github.com/apache/cordova-plugin-device.git

Note: include scripts for Mobile Service and Notifications Hub MobileServices.Web-1.2.5.js and NotificationHub.js. They are downloadable from Mobile Service HTML/JS template project.
// set up Push Notification as the app is launched and deviceReady event is fired

 var pushNotification = window.plugins.pushNotification;

// Mobile Client object is created at script file level.
 mobileClient = new WindowsAzure .MobileServiceClient("https://my.mobile.service.url/", "my-mobile-service-key");

  if(pushNotification){
// Phone Gap App and Mobile Service could be used for non Android platforms as well. So check this condition. Else conditions on other mobile platforms shall be added.
if ( device.platform == 'android' || device.platform == 'Android' ){
       pushNotification.register(
           app.successHandler, app.errorHandler,{ 
               "senderID": GCM_SENDER_ID, // it's the project number
               "ecb": "gcmCallback" // function to be called by GCM Service for completing registration.
              });
            } 
         }


GCM Callback below.
    function gcmCallback (e) {
     switch (e.event) {
//This function is called in two scenarios, while registering device with GCM and while receiving Push Notifications
     case 'registered':
          if (e.regid.length > 0) { // regId will be sent back to Notification Hub/ Mobile Service.
              if (mobileClient) {
// Client library for notification hub -that allows multi-platform Push Notifications. Of course, Here we are focusing on GCM/Android.
             var notificationHub= new NotificationHub(mobileClient);

 // Set template for data to be sent by Mobile Service
            var template = "{ \"rootObject\" :{\"message\":\"$(message)\"}}";

// Send regId to Notification Hub, so that mobile service uses it when sending Push Message.
             notificationHub.gcm.register(e.regid, null, "any-template-name", template).done(function () {
// This is my function for updating status on view. You can use console.log or any other method.
              app.updateStatus("Registered for new notifications, through Notification Hub");
                        }).fail(function (error) {
               app.updateStatus("error);
                        });
                    }
                }
                break;
// This is handling Push Message
            case 'message':
            // if app is open when notification arrives
                if (e.foreground)
// Perform target action when notification arrives. Again, this my function update view. You can handle it diferently.
                    app.updateStatus(e.payload.message);

                }
                break;

            case 'error':
                app.updateStatus('GCM error: ' + e.message);
                break;

            default:
                app.updateStatus('An unknown GCM event has occurred');
                break;
        }
    }

Tuesday, January 6, 2015

Windows Azure Mobile Services for Connected Mobile Apps

In previous blogs (1, 2 and 3) I've set context by exploring Phone Gap and Ionic Framework for Hybrid mobile app development. This blog is taking a little step forward by integrating a sample mobile app with a cloud service.

Most mobile apps need to be connected, use a centralized data store and services. Attached is a sample mobile app that maintains laundry list of items. Sample allows users to add items (let's say groceries) over a period of time, review the list, mark one or more purchased or delete some items. This sample app stores data on a cloud service instead of saving on phone.

Laundry List - Sample App Demo on browser emulator: 



Download sample project here - Link

Below is the tech stack chosen
  • Windows Azure mobile service to address data needs of the app.
  • Hybrid Mobile App using Ionic Framework

Why Windows Azure Mobile Services?

1. Ease of development.

Most services are entities and their CRUD operations. Using mobile services, an entity or a database table is created with in no time. In Windows Azure Management Portal select New, under Compute select Mobile Service click Create. Make your choices on the following screen. As you click Next, database selections need to be made and the new mobile service is created.
In Visual Studio Server Explorer under Azure section right click on the new mobile service and click create table. The Mobile Service is ready. Service for Create, Retrieve, Update and Delete operations on the database table is automatically created.
1. Create Mobile Service
2. Create Table


To design the table (associated with mobile service) with column names, data types etc., open the database in "SQL Server Object Explorer" in Visual Studio. Right click on the newly created table and click design. Use the designer window and define columns and other aspects of a database table.

2. Ready made code templates for mobile apps.

You can download boilerplate code for most mobile platforms, namely Android, iOS, Windows Phone and Phone Gap (Hybrid). This helps reduce setup time. In the code sample, I used "mobile services" JS file that takes care of communication with the mobile service. This file acts as a proxy to mobile service. This means developer can focus on mobile app UI development and use the ready made data service communication library.

3. Push Notifications across mobile platforms. 

Implement push notifications easily across platforms iOS, Android, Windows Phone.

4. Deploy your service to a near location of users.

The Mobile Service could be deployed closer to target users in the available geological locations provided by Windows Azure.

I will not dwell into "why Ionic framework" as it's described already in my previous blog.

Ionic App

1. To download Ionic Framework's tabs template run
ionic start laundryList tabs

2. Include library from Windows Azure Mobile Service. Download project from the Windows Azure portal for Phone Gap and copy the lib to Ionic project. At the time of writing this blog, I happen to have version 1.2.5 (MobileServices.Web-1.2.5.js)

3. Create a AngularJS Service to perform CRUD operations.

Initialize the service for communication with Azure Mobile Service,
//create mobile service client object
var client = new WindowsAzure.MobileServiceClient('https:/my-mobile-service.azure-mobile.net/', 'my-app-key');
// get reference of the laundry list table.
var laundryList = client.getTable('laundrylist');

Code to get a list of active laundry list items is below,
var deferred = $q.defer();
// Where clause here restricts results to active items.
var query = laundryList.where({ isAvailable: true, isPurchased: false });
// query.read is async 
   query.read().then(function(pLaundryList) {
        deferred.resolve(pLaundryList);            
   }, function(error){
       deferred.reject(error);
   });
// as this code is in one of the service functions, it returns a promise
return deferred.promise;

Code to get a list of completed laundry list items is below,
var deferred = $q.defer();
// where clause here restricts results to purchased items.
var query = laundryList.where({isPurchased: true });
       query.read().then(function(pLaundryList) {
            deferred.resolve(pLaundryList);            
        }, function(error){
        deferred.reject(error);
        });
return deferred.promise;

Code to create a new laundry list item
// It returns a promise (Async) depicting status of http call to the mobile service.
laundryList.insert(item)

/*
Sample JSON object for Laundry List here

{
title: 'value from text box',
isAvailable: true,
isPurchased:false,
details: '',
price: 0,
quantity: 0

}
*/

Code to mark a laundry list item complete is below. This is an update call.
// It returns a promise (Async)
// id is primary key on the table, server side.
// value being updated is isPurchased.
return laundryList.update({id: id, isPurchased: true});

Code to delete a laundry list item is below.
// It returns a promise (Async)
return laundryList.del({id: id});

Mobile Service Logs.

Last but not least; While debugging API calls, mobile service errors could be reviewed on Management Portal. This will help reduce heart burn by giving specific information on why a mobile service call failed. Refer to logs tab under the mobile service for similar information depicted in the screenshot.



Download complete code here - Link to sample app