HOWTO: write a non-web-based Indivo app

From Indivo

An Indivo X application is typically a Web application. In some cases, however, while the Indivo X app will always communicate with the backend Indivo X server using HTTP+oAuth, it may present a user interface via a different mechanism, i.e. an iPhone app. This page explains how to accomplish the oAuth authentication protocol in these scenarios.

We consider two possible use cases when the application presents a non-Web user interface.

• the device has a Web browser that can be launched from the non-Web Indivo app, i.e. an iPhone or Android phone.
• the device does not have a Web browser but still connects directly to the Internet, i.e. an Internet weight scale.

We set aside the use case of a device that doesn't directly connect to the Internet, since it will then have to connect to another device, i.e. a desktop computer, which will then play the role of the Web-enabled Indivo app.

[edit] Device with Web Browser

An Indivo app that runs outside of a Web browser but on a device where a Web browser can be launched can engage in most of the normal Indivo authorization protocol. In particular, the device will store a consumer key and secret and:

• request a request token
• launch a web browser to let the user authorize the request token
• exchange the request token for an access token, which it will store long-term

Since the device does not present a Web interface, it will be an Indivo app with the has_ui parameter set to False, meaning it will not show up in the list of actionable apps in the lefthand bar within the Indivo X web-based UI. However, since it has an access token, it can push data to the record and pull data from it like any other Indivo app, using HTTP+oAuth.

The key complication is the last step of the authentication exchange, where the web transaction needs to communicate the oauth_verifier value back to the application before it can exchange the request token for an access token. For this purpose, every Indivo app of this kind must have a web server that serves the post_auth callback URL. At that point, the web server can display, for the user, the value of the oauth_verifier which the user can then manually type into his non-Web-based Indivo app's UI. Or, on certain devices like the iPhone, the web server can actually pass the oauth_verifier back to the iPhone app by opening up a URL with the right protocol prefix that triggers the iPhone to open up the native Indivo app with the oauth_verifier as input.

Eventually, Indivo X will directly support the "type your verifier code manually" use case by displaying the verifier code itself and prompting the user to return to their application. This will remove the need for a native device application to have an always-running Web server. However, this feature is under development as of January 2010 and will not be ready until Indivo X Public Beta 1.

[edit] Device without a Web Browser

Devices without a web browser must be bridged by a web server, at least for the authentication portion. Specifically:

• the user follows device-specific instructions to go to the bridging web server, i.e. http://weight-scale-bridge.com
• the user authenticates properly, and follows device-specific instructions for binding the device to the bridging web server, i.e. by entering a secret code into the device, which then makes a request to the bridge server to confirm the authentication between device and its bridging web app.
• the user, on a desktop computer accessing the bridging web app, begins the normal Indivo oAuth process.
• upon completion, the bridging web app has the option of delivering its newly obtained credentials to the device, which can then make direct requests to Indivo, or continuing to bridge/proxy all requests between device and Indivo.