Sunday, September 6, 2015

Firebase as your app's backend


Firebase is a cloud based back-end as a service provider. It can be used as a very effective No SQL data-store. Your application can store JSON objects. Integration is made easy with variety of libraries provided by Firebase. For this blog I'm focusing on Web/JavaScript library.

As a developer it's quick to get started. No overhead of installation and setup. It's a cloud service, so don't have worry about setting-up servers. Firebase tools on your machine are provided as an NPM package. Install with following command, globally on your machine.

npm install firebase-tools -g

This makes it a good choice for independent mobile/web app developers. Signup and login to Firebase.
Create an app. Remeber your app has a URL. JSON Key/Value pairs are shown at that URL. You might chose to manually add/remove/modify data as well.

Synchronized:

As and when data is updated in the backend, JavaScript events are raised and the callbacks provided are invoked with updated data. Hence your app is in near synchronous state all the time. With this approach we write less code, retrieving data is made simpler. Down below I've mentioned couple of data retrieval options. Checkout more here.

Consider Two Tier Architecture

With JavaScript and browsers being more and more powerful, you don't have to look at mandatory middle tier. Firebase can act as your middle tier and data store. Security, validation and authentication features of Firebase do allow this kind of architecture. 

Get Started

by referencing Firebase library in your Web Page. You could use CDN location. Or by downloading Firebase bower or npm package. I chose bower (package manager).

bower install firebase

And reference of firebase.js in bower_components. There after

//create an object of Firebase
var ref = new Firebase('URL of your firebase app');

Save Data to Firebase:

// to set a primitive data value
ref.set('sample value')
ref.set(100);

// you may set a JSON object instead
ref.set({
field1: 1,
field2: {
  child1: 'value'
}});

//If you are storing a new object every time, use push (array) instead of set.
ref.push({
field1: 1,
field2: {
  child1: 'value'
}});

Retrieve data from Firebase:

As mentioned earlier, Firebase keeps data synchronized. Data is pushed to the browser as changes happen. JavaScript code need to have callback functions defined to update view as data is retrieved automatically.

//Look for changes to the data
ref.on('value', function(snapshot){
    console.log(snapshot.val());
});

// data added as a child node.
ref.on('child_added', function(snapshot){
    console.log(snapshot.val());
})


All data elements in Firebase are represented by URL. You can traverse through the nodes in the URL itself. For example, to reach child1 in above example, you could provide URL "http://yourapp.firebase.io/field2/child1" to the Firebase function.

or you could use ref.child('field1/child1')


Running your application:

You may use any Web-Server to serve HTML files on your machine. Serve is a good choice.

npm install serve -g

Run serve from at the root folder of your application.
Firebase also provides hosting service. Run

firebase init
(Link application to Firebase app in this step.)

firebase deploy
(Deploys to Firebase cloud service)

You can serve HTML files on the cloud now. URL is on App Card It will be your appname.firebasepp.com

This is an introductory blog. Do checkout Security, Authentication, OAuth and Offline features of Firebase.


Also, I've basic Firebase examples on my Github. Use this link to explore.

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;
        }
    }