X-Callback-URL
iCab Mobile supports the x-callback-url protocol. This protocol is a simple way Apps can communicate by sending URLs to each other. These URLs have a well-defined format with a command and parameters. The protocol is very flexible, but nevertheless very simple and easy to use.
In iCab Mobile the x-callback-url protocol can be used for the following tasks.
Adding Bookmarks
An Apps can add a bookmark in the iCab Mobile bookmarks list. iCab will create a special folder for all the bookmarks which are received from other Apps this way, so the user will always see that these bookmarks came from other Apps
Adding Filters
An App can add a new filter to the filter manager. iCab will again create a special Filters group for filters that came from another App, so you can find them easily.
Adding Search Engines
An App can add a new search engine to the list of search engines, in case it does not yet exist.
Adding a page to the Reading List
An App can add a page to the reading list of iCab Mobile.
Start a Download
An App can initiate a download within iCab Mobile. So if an App does not provide a download manager itself, it can use iCab for this.
Start a Search
An App can launch iCab Mobile and immediately open the search window, so the user can directly enter a search term.
Open a Web Page
An App can open a web page in iCab Mobile. This is nothing special, because this was already possible before. What’s new is that the page can control if the new page is opened in a new foreground tab, a background tab or the current tab. It can also control wether the page opens in fullscreen or normal mode.
Start iCab Mobile
Starting iCab Mobile in normal mode or in fullscreen mode.
Though it is clear that most Apps won’t support any of these tasks, some Apps can probably do some great stuff with this new feature. I’m thinking about Apps like Launch Center Pro which already supports many of these actions.
If you want to support one or more of the above tasks of iCab Mobile in your own App, you only need to send iCab Mobile a properly formatted URL which conforms to the x-callback-url protocol specification. Such an URL looks like this:
[scheme]://x-callback-url/[action]?[x-callback-parameters]&[action parameters]
For iCab Mobile, the [scheme] should be “x-icabmobile”, though also the scheme “icabmobile” will work. The [x-callback-parameters] needs to be set up according to the requirements of your App. These parameters control if iCab Mobile will return to your App after it has processed the command or if iCab stays the active application. [action] describes the command that is executed in iCab Mobile and [action parameters] define the parameters for this command. All values for the parameters should be URL encoded strings. All parameters are key value pairs and concatenated by “&” in the URL in the usual way. At the end of this article you’ll find some concrete examples for these URLs:
x-icabmobile://x-callback-url/addBookmark?x-success=yourapp://success-handler&x-error=yourapp://error-hander&url=http://www.icab-mobile.de/&title=iCab%20Mobile%20Homepage
For more information, please see the official x-callback-url protocol specification
The [action] and [action parameters] you can use in iCab Mobile are the following:
Action Required parameters Optional parameters Description
addBookmark url=[url] title=[title] Adds a bookmark with the given URL and title to the Bookmarks of iCab Mobile
addFilter url=[filter-url]
Should use wildcards “*”, “?” and “[abc]” to make the url filter valid for more than a single page type=off
type=block
type=load Creates a new filter. Without the type parameter, iCab defaults to “block”
addSearchEngine url=[url]
Should include the string “%@” where the search term needs to be added title=[title] Adds a new search engine to the list of search engines
addReadingList url=[url] title=[title] Adds the page with the given URL and title to the Reading list
search searchTerm=[searchTerm]
searchEngine=[searchEngine] Launches iCab and opens the search window, so the user can directly start entering a search term, if the search term is given, the search is started immediately. The searchEngine parameter lets you select the search engine whih should be used for the search. The first search engine whose name contains the text from the "searchEngine" parameter and which is included in the search engines list of iCab Mobile will be used for the search. If no matching search engine is found, the default one is used.
fullscreen Launches iCab in fullscreen mode
normalmode Launches iCab in normal mode
open url=[url] destination=currentTab
destination=backgroundTab
destination=newTab
fullscreen=yes
fullscreen=no
Opens the page in the given destination and enters the fullscreen mode when requested. The URL “quickstarter:” can be used to open the Quickstarter page
download url=[url] filename=[filename]
referrer=[url]
Starts the download of the file at URL and uses the filename to save it in the