Facebook Single Sign-On for AIR iOS Apps

With AIR 3 on the door many developers are willing to build their Mobile Applications with Adobe AIR Runtime. I need not mention separately that Social Networking remains one the biggest use cases for mobile applications which means nothing but integration with Facebook.So, today we have a great library(SWC) build for Facebook API that can be used with any Actionscript based application it can be a Web app running in browser or a desktop application built with AIR or A mobile application on Android/iOS/Playbook. One swc serves all. This can be found here.
But this article addresses a very specific problem. Facebook has provided a feature for Mobile Devices called "Single Sign-On".
A quote from Facebook developer page which best describes what this feature is all about.

One of the most compelling features of the iOS SDK is Single-Sign-On (SSO). SSO lets users sign into your app using their Facebook identity. If they are already signed into the Facebook iOS app on their device they do not have to even type a username and password. Further, because they are signing to your app with their Facebook identity, you can get permission from the user to access to their profile information and social graph.

Just to explain better. If I have 10 Facebook applications on my iPhone I will need to enter my credential in each app as and when I use them. SSO solves this problem for once and for all. You need to provide your credentials only once in the "Facebook" application (Facebook app by Facebook) and all other applications will come to Facebook app for authorizations.It also has a fallback mechanism, if the end user doesn't have "Facebook" app installed we can use Safari browser to serve the same purpose.
Ok. So lets start coding!! but before we actually start lets summarize the 5 easy steps involved and we will walk through each step.

1. Define Custom URL for your application
2. Set-up and use a simple native extension, which can tell us if a particular URI can be opened.
3. Implement the Authorize method in Actionscript
4. Handle the INVOKE EVENT of the application and Pass on the access_token and expiry_date to the Actionscript API for Facebook.
5. Make Facebook API Calls with Actionscript API.

The basic mechanism by which this feature works on iOS is using Custom URI. On iOS any application can register a custom URI type that a perticular application wants to handle. For eg. If I have an application called "Image Viewer" I might want to tell iOS to pass any URI that start with img://... should be passed on to my application so that the application can be used to open an Image. Same is the case with facebook. If you want to try out. go to Safari browser on iOS and in address bar type "fbauth://" and say go. You can see that "Facebook" application opens up.

1. So lets start and define one such URI for our application. It doesn't matter what IDE you are using to develop your app. So according to your directory structure and IDE locate the application descriptor xml of your AIR iOS app. and add the following XML chunk as a direct child of top level Application tag.

   <iPhone>
           <InfoAdditions><![CDATA[
      <key>UIDeviceFamily</key>
      <array>
       <string>1</string>
       <string>2</string>
      </array>
      <key>CFBundleURLTypes</key>
      <array>
       <dict>
        <key>CFBundleURLSchemes</key>
        <array>
         <string>fbYOUR_APP_ID</string>
        </array>
       </dict>
      </array>
     ]]></InfoAdditions>
           <requestedDisplayResolution>high</requestedDisplayResolution>
       </iPhone>
   

   The above chunk will tell iOS that whenever any application on device wants to open a url of the form fbYOUR_APP_ID://... iOS should open your application to handle that URL. Similar to saying that whenever we open url that starts with http:// it is opened with safari. The facebook app will use fbYOUR_APP_ID:// url to open our application back on successful login and pass all the required data along with this URL which our application can use.
   you can test this right away. just create an ipa install it on your device and then in safari try typing fbYOUR_APP_ID:// and hit go. It should launch your application.
2. Now, lets move to the next problem. What if the user doesn't happen to have the Facebook application installed? To understand the problem in more detail, Just the way our app registers for a custom URI, The facebook app also registers for a custom URI scheme "fbauth://..." essentially this is how we will transfer control to facebook app for authrization, By opening a fbauth:// based URI, but if the end user does not have facebook app installed on his device there will eventually be none who understands the meaning of fbauth://. What do we do then? In such case we fall back to safari browser and use that for authorization. Currently in AIR we do not have in way of knowing if the iOS device has an application which can handle a particular URI scheme hence we need to a write a small native extension which provides a function called canOpenUrl(string) . This tutorial will not focus on how do we write native extensions you can get the one I have written from here and follow the steps to use it in your project.
   
   • Add the following XML chunk in your application descriptor as a child of top level application tag.

     <extensions>
         <extensionID>com.sbhave.openUrl</extensionID>
     </extensions>
     

     This will tell ADT that your application uses a native extension.Identified by the given extensionID. Note that Native extension is a new feature added in AIR 3. You must use AIR 3 SDK in order to use native extensions.
   • In order to get the Actionscript functions(which actually call the native obj-c code) recognized by your AIR iOS application. You need to externally link to the swc(Provided in zip). To this in Flash Builder go to project properties ->Flex Build path and Add the SWC. Once added double click on linkage type and make it "external" this step is very necessary.If you are using Flash Develop provide the swc path in external-library parameter
   •  Ok, good to go. Now the only thing to keep in mind that the currently released Flash Builder is not aware of packaging an application which uses Native extension and hence you need to package the application from command-line (help) and at the very end provide a new AIR 3 switch -extdir <Path to folder where .ane file is kept.>
   • We will use the functionality provided by this ANE in next steps. For now everything is set-up.
3. Now we will implement the authorize method which does all the work of authentication. I will first share the code and then try to explain what it actually does.

   protected function authorize(appId:String,extPerm:Array,forceBrowser:Boolean=false)
   {
    var url:String = "fbauth://authorize";
    var isFbAppAvailable:Boolean = URLUtils.instance.canOpenUrl(url);
    var ops:URLVariables = new URLVariables();
    ops["client_id"] = appId;
    ops["type"] = "user_agent";
    ops["redirect_uri"] = "fbconnect://success";
    ops["display"] = "touch";
    ops["sdk"] = "ios";
    if(extPerm != null && extPerm.length > 0)
     ops["scope"] = extPerm.join(",");
    if(!isFbAppAvailable || forceBrowser){
     url = "https://m.facebook.com/dialog/oauth";
     ops["redirect_uri"] = "fb"+appId+"://authorize";
    }
    var req:URLRequest = new URLRequest(url);
    req.data = ops;
    req.method = URLRequestMethod.GET;
    navigateToURL(req);
   }
   

   This is a very simple method which just sets the data and constructs the url. navigateToUrl actually tries to open the Url which indeed opens the application which has registered to handle the particular type of url scheme. This function expects two parameters. first one is the application ID that you get when you first create your application on facebook developer portal. extParams is a string array which enlists the permissions required by you application.The last parameter allows you to force the use of browser and avoid using the native FB app for authentication. We will see its use in next step when we handle the invoke event. an example call is shown below.(Please read step 4 before you actually write the following call in your code. You may want to check the LSO. See the sample code at the end of tutorial.)

   authorize(APP_ID,["read_stream"]);
   

   You can call this whenever you want the user to authenticate and authorize your application.For various permissions that you can specify see this . It is assumed for the sake of simplicity that APP_ID is the global level constant in your application which set to your facebook application ID.
4. Till this point, If you can test you application, whenever you call the authorize method you will be redirected to the FB app or Safari depending on availability and the user can get himself authenticated there and once done he will be redirected to your app. Now lets see how we can handle the data we get from facebook. We do this with the help of INVOKE event given by AIR. Whenever the application is invoked as a result of custom URL. we get the link that triggered our app in InvokeEvent's arguments array. This is link is where we have all the data that we need. In order to do this. Add a handler for INVOKE event in your application, earlier is better but must be added before calling the authorize() method. Eg. is shown below.
   

   NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE,onInvoke);
   

   onInvoke is the function where we will process all the data received as a result of authentication.I will again repeat my habit of first scaring the reader with the code and then trying to explain.

   protected function onInvoke(e:InvokeEvent):void{
   
   var str:String = e.arguments[0];
   if(str && str.indexOf("fb"+APP_ID+"://") != -1 )
   {
    var vars:URLVariables = FacebookDataUtils.getURLVariables(e.arguments[0]);
    var accessToken:String = vars.access_token;
    if(!accessToken || accessToken == ""){
     var err:String = vars.error;
         
     if(err && err == "service_disabled_use_browser"){
      authorize(APP_ID,["read_stream"],true);
     }
         
     else if (err && err == "service_disabled"){
      // We cant use SSO at all use the old FacebookMobile.init() and FacebookMobile.login()
     }
      
     var errCode:String = vars.error_code;
     var userDidCancel:Boolean = !errCode && (!err || err == "access_denied"); 
         
     if(userDidCancel){
      // User cancelled the login and authentication
     } 
    }
        
    else{ // Login was successful
     var expiresIn:int = int(vars.expires_in);
         
     if(expiresIn != 0){ // Everything went just well
      var expDate:Date = new Date();
      expDate.seconds += expiresIn;
      FacebookMobile.init(APP_ID,startUsingApi,accessToken);
      
                           // Store FB details in LSO
             var diskCache:SharedObject = SharedObject.getLocal("diskCache");
      diskCache.data["token"] = accessToken;
      diskCache.data["expDate"] = expDate;
      diskCache.flush();
      diskCache.close();
      diskCache = null;
     }
    }
   }
   }
   

   Lets go through the code bit by bit In the first line we store the first argument in a variable. As there can be various other methods of opening(invoking) the app. This can very well be null. That's what we do in the if statement that follows. We also check that the first argument is actually the result of triggering our fbUrl. If you go back and see the step 1. URLSchemes are actually an array and hence your app can register for more than one url scheme. We do absolutely nothing if any of this tests fail
   As our ultimate goal is to hook up this authentication with Actionscript API for facebook.I can safely assume that you have already added a reference to the AS FB API swc file.FacebookDataUtils.getURLVariables is a function in the SWC that decodes the URL and return an object, using which we can access various parameters passed along with URL by making use of normal dor(.) operator.for eg. if I pass to the function a url like abcd.com?a=b&c=d I can access the data as result.a and result.c, and this is exactly how we will use vars.
   The very first this that we do is to try getting an access token this is the key for API. If this access token happens to be null or empty we have hit some problems. which we handle in the if block. Generally, if we dont get the token we get a variable called error which describes the error that may have occurred
   
   • service_disabled_use_browser: The SSO serve is disabled from FB app and hence we need to try with browser. This is where we use the third parameter of the authorize() which forces the use of browser.
   • service_disabled: SSO service is disabled completely we need to fall back to the old method of using SWC init and login methods.
   • The next few lines decides if user purposely canceled the process of authentication. and
   If we enter the else block we have made it and we have an access token every time we get the access token we also get with it an integer called expires_in these are the number seconds for which the token is valid. If we have a non zero value we have received a valid usable token. In such case we will call the FB API SWC's init method, but with the third parameter as we already have a valid access token now.
   But to make developers and end users' life even easier. We store the access token and expiryDate(Pay attention to how the expiryDate is generated from expiresIn value) to the local object. WHY? Reason being: What if user closes the app soon after authentication, and opens it back in just few ours? though he need not enter his credentials again (This is what SSO is all about), He will get a round trip to FB app(Showing that he has already authorized the application) and then back to your app. Instead what we can do is that in step 3. before we call the authorize method we can check the same local shared object and check if we already have a non-expired and valid access token. In such case we do not need to call authorize at all.
   
5. Now the last and most fun part that is to actually use the FB API to make calls and get the real data from facebook. In the earlier step we have passed a callback name called startUsingApi this will be the function that will get called when Facebook API completes the initialization. An example emplementation is shown below.

   protected function startUsingApi(session:Object, error:Object){
    var p:Object = new Object();
    p.limit = 0;
    FacebookMobile.api("/me",function(result:Object, fail:Object):void{
     if(null == fail){
      trace(result.name);
     }
    },p);
   }
   
   

   Just to trace the user's name.

That is all. Actually it doesn't seem so big when you actually do it. You can find the complete implementation here.