I just released version 1.0 of my iOS Smart App Banner plugin for WordPress. This plugin lets you put a smart app banner at the top of your post or page when an iOS device visits in mobile Safari. It’s a great tool for app promotion that makes it very easy for people to find & buy your app in the App Store.

The high-level requirements:

• A mobile app that you have control over
• An API you’re working on
• Users must be authenticated

As I am the app and API owner, I thought it best and easiest to use a two-legged OAuth implementation – username & password plus some secret keys (3-legged vs 2-legged explanation). This is what your users will expect when logging into your app & service. Before you can start, find an appropriate library for your web framework. There are plenty out there, so pick your poison. I’m familiar and develop relatively quickly with CakePHP, so I went with seddonmeida cakephp-oauth-server. I’ll spare you from too much code.

First, you’ll have to set up an OAuth client in the database. This is for your app and nobody else. Follow your library’s instructions; you’ll find out you can’t read values from the database because they should be hashed. Once you have it installed and are sure it’s working, you can start the setup. In the CakePHP plugin,

function some_open_oauth_action(){
    $client = $this->OAuth->Client->add('myapp://register'); //the URL isn't really important in this case
    print_r($client);
}

Save your client_id and client_secret in a safe place. You’ll need it in your app. Now, the fun part. You can test this in your browser, but it will work the same way in your app.

First, Grant the Token

In OAuth terms, we’re doing a password type grant with the client_id and client_secret.

https://domain.ext/oauth/token?grant_type=password&client_id={SOME20CHARACTERLONGID}&client_secret={some40characterlongsecretkey}&username={username}&password={password}

You’ll get JSON in return with a few important keys, namely access_token and refresh_token. They will serve as your ID badge for future requests. Keep them around. NB: access_token is used most, but refresh_token has a special place.

Request Something

Making a request for protected resources is easy. Assuming your back-end is set up properly, you should be able to run something like this with no problem:

https://domain.ext/oauth/userinfo?access_token={whateverAccessTokenYouWereGiven}

I know the above URL is at /oauth/, but that doesn’t mean your entire API has to be handled with your OAuth controller. In practice, you should include your OAuth library as a component of each appropriate controller wherever you’re accessing the API, or at least secured content.

Refreshing Your Token

A lot of services using OAuth aren’t going to expire your token. Seddonmeida’s implementation uses an expiration, but in practice doesn’t actually enforce it; that’s up to you. In the case you do have an expiring token, it’s best to refresh your user’s keys from time to time so they aren’t “logged out.” To get a fresh new token, access our OAuth token action and request a refresh_token grant type using the client_id, client_secret, and the refresh_token you received when first authenticating.

http://domain.ext/oauth/token?grant_type=refresh_token&refresh_token={youGotThisAtAuth}&client_id={some20charid}&client_secret={a40charstring}

A Note About HTTPS

Make these requests over HTTPS if you have any option at all. Otherwise, HTTP is sending your username and password over in cleartext, which we all know isn’t a great idea.

• Always use Emacs
• Make sure that key to the left of the “A” key was your control key, map it to control if it wasn’t already
• Make sure focus follows mouse set to enabled.

Caps Lock to Ctrl

Briefly, that control key thing. I hated it at first. Then I started using Emacs quite a bit and it made sense. It much better on your poor little pinky finger to press down without having to contort your hand. Old Solaris systems actually made that the hardware control key. Any other keyboard has to be remapped via software so “caps lock” wasn’t really caps lock. I highly recommend it, but people are soooo confused when they’re using my machine and the caps lock doesn’t work. Or control doesn’t work and makes all their text in capitals.

Focus Follows Mouse

I don’t know why I forget to do this one. The idea is that window focus (the act of becoming active) can be controlled by simply moving your mouse over the window rather than having to physically click on it and bring the window to the foreground. FFM is particularly handy because the window isn’t brought to the foreground, but is still takes input from the keyboard. I use this most often when working with the terminal – where often I only care most about the last several lines of output, and not all the clutter of text and OS UI above it. It leaves the main window that might be referencing right where it is.

On your Mac, open Terminal, and do this:

defaults write com.apple.terminal FocusFollowsMouse -string YES

Quit terminal. Re-open, and open a second terminal window (not tab). Hover your mouse over one of them and start typing. Now, hover your mouse over the other one and type. See what happens? If everything worked properly, the typing occurs in the window your mouse is hovered over. The only caveat is that it acts a little funny if the terminal is in the background to another app, but it still works. I found that sometimes you have to hover out & over another app then back to the other term window. Not a huge deal, I guess. Try it out. If you don’t like it, change the above command from … YES to … NO

It’s a time saver and convenience – especially useful on constrained displays. You might just fall in love. Now if only the whole OS would let me do that.

Hybrid, the Unlikely Union

Let’s get the definitions straight before we begin. A hybrid app is one of those mobile apps that uses a native web view to display HTML, CSS, and JS “web” apps. They’re only sort-of “web apps” because they are run locally, though they often pull data from online sources via AJAX requests. So, you have this HTML/CSS/JS app running inside of a natively-compiled stand-alone web browser of sorts on your phone. One such example is PhoneGap. Because the logic bits of the app are written using web technologies, you can often develop once and deploy on multiple platforms, so long as you’re using supported markup. You’re killing multiple birds with one stone.

Hybrid is the Bee’s Knees

As I mentioned above, hybrid technologies are great for developing cross-platform apps. Seriously – since iOS, Android, and even some Blackberry devices are both running Webkit most, if not all, your html, css, js is going to work remarkably similarly on both platforms. It’s pretty enticing. From your and your client’s perspective it’s a pretty easy sell. For one round of development you have the potential to hit many more users. It’s pretty cost-effective. Pretty soon you’re singing the praises of your decision and you’ve decided that from now on hybrid apps are the bee’s knees.

The Gateway Drug

I’m not going to lie – I immediately fell in love with the idea because my background was primarily web development. I can take my existing toolset and apply it just a little bit differently to come up with something like an iPhone app that I’m sure everyone would want to buy. I’m getting ahead of myself. If it wasn’t for tools like PhoneGap and jQTouch, it would have been much longer before I got into mobile development. Now there are libraries such as Sencha Touch and jQuery Mobile to aid development. It’s an exciting industry to be working in. It’s not that the web is old and tired, but mobile development is something new and exciting. I can’t wait to see where we’ll be in just a few years from now. It’s getting that good, that fast.

Native Apps, the OG Tech

So far I’ve been discussing the benefits, and singing the praises of developing hybrid apps. So what about native ones? Since I’m really only familiar with Cocoa Touch, I’ll write from the perspective of an iOS developer, though many of these points will apply to Android. There is something to be said about the quality and performance of native apps. Native apps are going to perform better than hybrid apps, no doubt about it. When you read that, you’ll probably first think about number crunching, but I encourage you to think about it from another perspective: responsiveness. I’m talking about the speed at which things happen on the screen when you need them to. Does the next view load and transition instantaneously? How about animations or actions attached to button presses? Hybrid frameworks have come a long way, but native still wins this race, hands-down. When your app responds immediately to touch events, that’s awesome for the users’s experience because that’s how apps should work.

I think there’s also a certain level of sophistication in native apps that can’t quite be reached by hybrid apps. You can do quite a bit (even impressive) things with html/css/js but it only goes so far. At some point you hit a wall. More on this later.

Sticking Points

About a year ago, I chose to switch from jQTouch to Sencha Touch for hybrid app development. Overall, the end results have been very pleasing, especially compared to pre-Sencha Touch days. This framework takes care of most of the heavy lifting, from UI to data management. In many ways Sencha Touch looks and feels very similar to a native app. It mimics many of the same user interface and behaviors as its native cousins on both iOS and Android. It really is the best-of-class frameworks for hybrid apps. Beware, however, that it’s not an entirely pleasant experience.

The Mobile Web Darling, Sencha Touch

I’ve run into too-many-to-count issues with Sencha Touch relating to tweaking the layout, screen rendering, and general UX problems (I never said it was perfect). I’ve discussed some of these with fellow developers. Typically I describe it this way – It’s not too bad to work with until something that should work out of the box, doesn’t. I’ve spent far too many hours trying to debug and fix some very basic problems. Case in point – rotating the device causes rendering errors. A good number of developers have also experienced some major Android incompatibilities, especially with the HTC Sense UI. Ever seen a text form field duplicate itself elsewhere on the screen when given focus? Work with Sencha on Android long enough and you’ll see what I mean. There’s no clear fix for that, nor is that mysterious field controllable by the DOM – it’s all at the OS level. How about crashing Android devices when you scroll the screen content too much? Just sayin’. I will give Sencha some credit, though. Touch works much better on Android than it did a year ago, and many of the most significant problems have been addressed. Also, customizing the UI isn’t too terrible. Most of the time.

The “Others”

I’ve read enough about others’ experiences with jQuery Mobile to know it’s not up to par like Sencha Touch is. I skipped over it a while ago, and don’t have immediate plans of working through another framework’s growing pains just yet. I guess this post isn’t quite fair enough to Sencha because it’s really the one I know most about. So let me reiterate – others have been saying Sencha Touch really is the best one out there. And truth be told – Sencha Touch can produce some really good apps.

The problem you’re going to run into with these “web” frameworks is going to convince your client and end users that the app is undetectably different than native apps. That means they should be just as fluid and work just as seamlessly as native apps. Most of the time I don’t see that parity. Animations can be jerky, the UI looks mostly native, but you can tell the difference. When it comes down to it, there are simply things you can’t do with web technologies that are pretty commonplace with native libraries. It’s not really JS’s fault, but DOM manipulations are expensive. The more DOM you’re manipulating, the more the responsiveness is going to suffer. Remember when this was a real problem on desktops several years ago? Well, it’s the same on mobile now. It’s frustrating.

Here’s one place hybrid apps tend to really fall behind – interacting with core OS services. HTML5 offers new support for basic features such as address book and some media-related tasks, geo location, etc, but only to a point. As you develop enough hybrid apps, you start to get the feel for things you can and can’t do. PhoneGap has done a great job of providing a good native API and a set of helpful plugins, but it does not solve every problem. New plugin needs still require a native programming to interface with your JS. It gets a bit sticky

Native Learning Curves

The learning curve kept me from iOS development initially. If your only prior experience was most web technologies, it’s understandable. There is a bit of a steep learning curve if most concepts core to Objective C are new to you, but be assured it’s not impossible. It just takes work, as it does with any new language and/or framework. My experience shows that once I started picking up the generalities, the specifics started to fall into place. It gets better. Seek the help of programming books and Stack Overflow. Study at sample projects (Apple and Google both provide them) and understand them.

Finally, Stand

If you’ve read this far, congratulate yourself. I’m not normally this long-winded. Or am I? Anyhow, where do I stand? Which is better? Both. Well. Sort of. I mean, I think if you have the chops for native development and the help of a good designer and UX colleague, do it. I believe that at this point of time, you are going to get the best results from developing native apps, especially on iOS. Hybrid apps, in my opinion, are going to be the most obvious choice when clients are wanting cross-platform apps on limited budgets. I don’t mean this to imply native apps are prohibitively expensive. Rather, hybrid apps do allow you to perform a bit of a shortcut by only having to write one codebase for multiple platforms. The question of whether or not the tradeoff is worth it. Do you feel you can create as quality of an experience with hybrid apps as with native? That’s for you to answer, and then to explain to your clients. You may be of the opinion that native apps are most ideal (that’s how I feel), however sometimes the decision isn’t yours – directly or indirectly.

I’ll probably get some flack for this. Remember, use the right tool. Sometimes that’s determined more by budget than technology. A client looking to develop a low-cost app for iOS, Android, and Blackberry will not get quite the same experience as if the same app were developed separately for each platform. Remember – you pay for cutting corners. Some people are OK with that.

To answer the post’s title question? Not yet. I think there’s still plenty of catching up to do, however I don’t have many hopes for full OS-level integration for web technologies (remember, the web is platform-agnostic).

This type of project is broken down into 3 parts: Upload & store geolocation data, find addresses near a given point, and display those locations either textually or on a map display. This quick tutorial will cover the first two parts.

Part 1, Getting Located

The goal of this part is to obtain and store latitude/longitude pairs for given addresses. I’m going to assume you can already get a list of addresses, whether for a spreadsheet/csv file, or other source. With a parsed address, you can obtain the lat/lng pairs from the Google Maps API. Just be forewarned that Google limits you to 2,500 requests per 24h period. That could be a problem for some applications, so you may need another provider like SimpleGeo.com

<?php
// Google maps API. rate limit to 2,500 reqs/24h
$url 		= 'http://maps.googleapis.com/maps/api/geocode/json';
$address	= urlencode($row['address']);
$city		= urlencode($row['city']);
$state		= urlencode($row['state']);
$zip 		=  $row['zip'];

$requestUrl = $url."?address=".($address.",".$city.",".$state.",".$zip). "&sensor=false";
// echo $requestUrl;

$crl = curl_init();
curl_setopt($crl, CURLOPT_HEADER, 0);
curl_setopt($crl, CURLOPT_RETURNTRANSFER, 1); 

// Set up the CURL request
curl_setopt($crl, CURLOPT_URL, $requestUrl); 

// Here we get the google result in JSON
$googJson = curl_exec($crl);

curl_close($crl);

$googArr = json_decode($googJson);
$status = $googArr->status;
$loc = $googArr->results[0]->geometry->location;
if( strtolower($status) == "ok" ){
	$tableData[count($tableData) - 1]['lat'] = $loc->lat;
	$tableData[count($tableData) - 1]['lng'] = $loc->lng;
} else {
	$tableData[count($tableData) - 1]['lat'] = 0.0;
	$tableData[count($tableData) - 1]['lng'] = 0.0;
}

//go on to save $tableData to your DB

?>

There are a couple key parts in there. First, you need to URL encode the address details. Second, the curl stuff is pretty standard – you can find similar versions all over the net. Third, the response data comes back as a JSON string, so you need to decode it into a PHP array to make it useful. My default value for lat/lng pairs is 0.0/0.0. There may be cases where Google doesn’t understand the address information or perhaps you’ve gone over your rate limit, so you have to accept more or less a throw-away response. The important thing is that you have your address coordinates saved (dare I say, cached) in your DB. You need this.

Part 2, Finding Yourself

Now how are you supposed to find these stores that are near you, at this moment, without having to use a lame web form or other manual means? You’re going to use the Haversine, aka Great Circle  Formula. Don’t click that link unless you really want to be confused. Here’s the gist – the globe is a big sphere, and we know from high school and/or college trigonometry classes that you can figure out lengths and distances on geometric objects. Some guy long ago (whose name was not Haversine) sat down and figured this out for us. What we get as a result of running these maths is the distance between to points on earth, using lat/long pairs. The caveat is these are as the crow flies, not driving directions. What I’m going to show you below is some SQL you can use to find the N closest points within a given distance. This will work on MySQL, and I’m assuming other SQL-compliant DBs. YMMV.

// scale:  MILES - use 3959 ;  KM - use 6371 (mean radius of the earth)
$scale = 3959;
$sql = "SELECT name, address, city, state, zip,  ( "
. (int) $scale ." * acos( cos( radians(".(float) $loc['lat']
. ") ) * cos( radians( lat ) ) * cos( radians( lng ) - radians("
. (float) $loc['lng'].") ) + sin( radians(". (float) $loc['lat']
. ") ) * sin( radians( lat ) ) ) ) AS distance FROM "
. $tablename ." HAVING distance < ". (int) $distance 
. " ORDER BY distance LIMIT 0 , ". (int) $limit . ";";

(Thank Pavel Chuchuva on Stack Overflow for the SQL [answer here]). You only need a couple parameters to get this chugging along and giving you a list of distances, closest to farthest from the point you are feeding it. Along with your address information, you’re also provided a distance in miles (using 3959 for measurement in Km).

Now you can use these results to display distances to your users. Let Google be your guide for implementing Part 3.

Add this to your {MyApp}-prefix.pch file

#ifndef __OPTIMIZE__
#    define NSLog(…) NSLog(__VA_ARGS__)
#else
#    define NSLog(…) {}
#endif

The reasoning behind using __OPTIMIZE__ is that it’s set only on release builds of your app, not in debug versions. It’s very simple and allows you to use NSLog() instead of having to come up with your own version.

Silencing the output to XCode’s debugging console wasn’t immediately obvious. Overriding console.log() in JS by setting it to an empty function worked in the browser for development, but as soon as I loaded the app onto the actual simulator, we were back to square one. Enter the PhoneGap DebugConsole prototype. Override it.

Insert this anywhere after your phonegap.js file loads. It’ll keep things quiet as long as DEBUG = true…

if(DEBUG == true){
    DebugConsole.prototype.log = function(message, maxDepth) { }
    DebugConsole.prototype.warn = function(message, maxDepth) { }
    window.console = new DebugConsole();
}

There you have it

1) You want to create a new PG project, but you’re not seeing the XCode templates when you go through the new project menus. Check out Shazron’s blog @ Nitobi for a command-line script to get you a new project up and running. It’s not as sexy as the XCode template, but it will do.

2) You can’t compile your app for submission to Apple? That was a little more tricky to track down. See this thread on the Apple Dev Forums for a bit of an abstract view of what’s going on. I’ll save you the details. Follow these steps to XCode bliss.

1. Select the PhoneGapLib.xcodeproj entry in your files list:
2. Make sure the “All” tab is selected:
   
3. Look for the “Deployment” section and scroll down until you see the “Skip Install” parameter. Set Skip Install to YES:
   
4. EDIT: Make sure to verify your target device…
   Make sure you have the “iOS Device” option selected in the schemes drop-down:
   
5. Go over to the “Product > Archive” menu. XCode will do its compile magic. Open the Organizer to see the app and the listed archives when the compile is complete. At this point, make sure you are ready to upload the app to iTunes Connect. Bonus: we get to skip the Application Loader app from now on!
6. Select the archive and click the “Submit” button. XCode will ask for your credentials. Log in and select the appropriate app and distribution profile from the list. Submit. If all goes to plan, you’ll get a message of approval. Finished.

That was easy. Now you can navigate the XCode4 waters with PhoneGap.

On app initialization, add an event listener for Android’s back button, and the callback to handle it. PhoneGap takes care of the interface between Android and your app.

document.addEventListener("backbutton", backKeyDown, true); 
function backKeyDown() { 
     // Call my back key code here.
 	alert('go back!');
}

That’s enough to get you started, and it should be pretty apparent if it works or not.

How about history management? It will depend on the app and what makes sense, BUT you’ll probably want to create a history array, and pop off some value that directs the app each time you hit the hardware back button. Here’s another idea: change the destination of the back button depending on the view. I personally like the idea of the latter because apps built on Sencha Touch are going to have easy tie-ins through predefined listeners JS Objects that define screen elements like buttons.