2-way app integration on the iPhone: How it works

Ryan — Tue, 06 Jan 2009 00:27:35 +0000

I’m really excited about the recently announced integration between our Credit Card Terminal app and PingySoft’s RingItUp Point of Sale app.

I suspect that other apps will want to provide similar integration. Just last week, Erica Sadun was talking about what she called “Bridging Functions” on Ars. That’s what I’m talking about here.

The URL Handler for Twitteriffic was the first thing Craig Hockenberry posted about after the NDA went away. Such URL handlers are a good sign that the community wants to expose app functionality in a reusable way, but they only solve half the problem since the user is stranded in the new app. Who wants to tap the home screen, find the original app, and navigate back to the right place?

Speaking of Twitteriffic, have you noticed how many iPhone apps have their own ad-hoc web browser built-in instead of using Safari? It’s because calling into Safari leaves the user stranded. We need an experience like playing a video from Safari. The video launches like a separate app, but there’s a Done button to return to what I was doing.

The basic idea, to quote my abstract algebra prof (sorry, Dr. Sherman!), is “Go somewhere; do something; come back.” The more apps that provide this kind of integration, the richer the iPhone platform will be.

Thankfully, since Apple has provided an underlying URL-based method for applications to communicate with each other, we can use existing techniques from the web space to accomplish our aim. Two apps can pass control between each other fairly easily when both are registered to handle a URL scheme in their Info.plist.

So here’s how the Credit Card Terminal / RingItUp integration works (video):

1. App A invokes a URL for App B, including a returnURL parameter that acts as a “continuation”

When you tap “Accept Credit Card Payment” in RingItUp, it crafts a URL for Credit Card Terminal. This is the familiar URL handler pattern that Craig talked about on his blog. You can specify various parameters on the query string and Credit Card Terminal will pre-fill those values.

The trick here is that RingItUp also includes a returnURL parameter so that Credit Card Terminal knows how to come back when the Credit Card Processing is done. The returnURL contains all the information RingItUp needs to bring the user back to the same place they started. In RingItUp’s case, this is as simple as including a record_id parameter. But you could imagine an arbitrarily complex “continuation” encoded in the URL.

→ com-innerfence-ccterminal://charge/1.0.0/?invoiceNumber=123&returnURL=my-return-url%3A%2F%2F%3Frecord_id%3D123

2. When App B is done, it invokes the returnURL from App A, including any additional info

When you tap “Return to RingItUp” in Credit Card Terminal, it invokes the returnURL from the request, tacks on some additional return parameters that indicate whether the charge was approved (the return parameters are prefixed with ifcc_ to avoid collisions).

→ my-return-url://?record_id=123&ifcc_responseType=declined

3. App A handles the returnURL, restoring the “continuation”

When RingItUp re-launches, it loads the correct record using the record_id parameter, then stores information about the credit transaction in the Notes field for that record.

I would be remiss if I failed to point out the security implications here. By registering to handle a URL scheme, an iPhone app becomes a de facto web app, subject to many of the nasty attacks that work on the web. Apps implementing this scheme must be careful to validate any parameters they get from the URL lest they be vulnerable to old friends like SQL injection. Another one to be careful of is unsolicited response attacks. The calling app should store a nonce value which it includes in the returnURL and reject any response with the incorrect nonce (similar to CSRF mitigation on the web).

Due to the security issues, as well as the sometimes tricky matter of properly encoding query string parameters, we’ve chosen to provide Objective-C classes for submitting the request and parsing the response when interacting with Credit Card Terminal. These are MIT Licensed, and we’d be very happy to see other app developers use them as templates for their own integration offerings.

What other apps would you like to see support 2-way integration? I’d love to see one of the twitter apps do it. That way I could expose the ability to send a quick tweet from my app without worrying about stranding the user and without writing against the twitter API directly. Which is a relief, because I certainly don’t want to be in the business of collecting people’s twitter passwords right now. :-)

Update: Of course, since iPhone apps are generally servicing one user, the easiest way to deal with the continuation problem is just to save what you need to NSUserDefaults.

Blog - Inner Fence » url handler

2-way app integration on the iPhone: How it works