X-Callback-URL: URL specification for iOS interapp communication

URLs are one of those things about the web that we often take for granted. As developers, we can request resources and send users to other destinations just by knowing a location on the Internet.

The mobile landscape is a bit different. While most mobile applications speak Web, consuming REST-ful APIs and other web resources, quite often they’re little silos of vertical, site or brand-specific functionality. Did you know that for iOS developers Apple makes it possible to register your own URL scheme, as in this Gowalla example:

Launch with gowalla://
Open Paddington Station spot gowalla://spots/19264
Open pengwynn user 123 gowalla://users/pengwynn
Open Walt Disney World Resort trip gowalla://trips/24622

The list of known iOS applications supporting OpenURL is growing daily.

Beyond application launching

As handy as these custom iOS URL schemes are in launching other applications, mobile developer Greg Pierce wants to the community to extend the idea of custom URL schemes and adopt a standard for inter-app communication. X-Callback-URL is a draft specification for one-way and two-way communication between mobile apps on iOS and looks like this:

[scheme]://[host]/[version]/[action]?[x-callback parameters]&[action parameters]

Let’s look at a real world example from Greg’s popular Terminology, a language reference app for iPhone and iPad:

terminology://x-callback-url/1.0/lookup?text=a%20good%20deal

scheme: The app’s custom URL scheme, terminology in the above example
host: Callback URLs are identified by a host value of x-callback-url
version: The X-Callback-URL spec version, currently 1.0
action: The action to perform in the target app. In this case, Terminology will perform a lookup action.
x-callback parameters: Optional. Not used in this example
action parameters: The parameters to pass to the executing action, “a good deal” in this example

This approach provides a robust way to not only launch an app, but also request that the app handle an action, which may or may not have a UI associated with it.

Two-way communication

The real power of X-Callback-URLs lies in two-way inter-app communication. By using the x-callback parameters in the spec, we can ask the target app to call us back on our own URLs, even handling success and error scenarios. Sort of like custom HTTP headers, these callback parameters are identified with an x- namespace:

x-source : The friendly name of the source app calling the action. If the action in the target app requires user interface elements, it may be necessary to identify to the user the app requesting the action.
x-success : If the action in the target method is intended to return a result to the source app, the x-callback parameter should be included and provide a URL to open to return to the source app. On completion of the action, the target app will open this URL, possibly with additional parameters tacked on to return a result to the source app. If x-success is not provided, it is assumed that the user will stay in the target app on successful completion of the action.
x-error : URL to open if the requested action generates an error in the target app. This URL will be open with at least the parameters “errorCode=code&errorMessage=message. If x-error is not present, and a error occurs, it is assumed the target app will report the failure to the user and remain in the target app.

Here’s how you’d build a URL to allow your users to select some text in your app, choose a replacement in Terminology, and have to return back to your app.

terminology://x-callback-url/1.0/replace?text=white&x-source=MyAppName&x-success=myappurl://x-callback-url/1.0/returnAction

Greg has a great screencast that demonstrates the process end-to-end:

Be sure and check out the full documentation for all of Terminology’s callbacks on Greg’s site as well as implemenation examples on GitHub. If you decide to implement X-Callback-URL in your application, please add it to the directory so the community knows how to integrate with you.

[Source on GitHub] [Home page] [@xcallbackurl on Twitter] [Discuss on HackerNews]