As of version 6.0, iCab Mobile 6.0 supports the x-callback-url protocol. This protocol is a simple way Apps can communicate by simply 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 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] | 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 | |
| fullscreen | Launches iCab in fullscreen mode | ||
| normalmode | Launches iCab in normal mode | ||
| open | url=[url] | destination=currentTab destination=backgroundTab destination=newTab
fullscreen=yes |
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 download manager. The referrer can be set as well, in case a web page only allows the download if it was initiated from a certain web page. |
If you want to support iCab Mobile from within for App and you would like to have some additional actions, please let me know.
Finally here are some examples of how these URLs look like for different tasks:
Launch iCab and show the quickstarter page in a new Tab:
x-icabmobile://x-callback-url/open?url=quickstarter:&destination=newTab
Launch iCab and show the iCab-Mobile web page in fullscreen mode in the current Tabs:
x-icabmobile://x-callback-url/open?url=http://www.icab-mobile.de/&destination=currentTab&fullscreen=yes
Adding a bookmark of the iCab Mobile web page and then immediately returning to your own App:
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
Your own App must have registered the URL scheme “yourapp” (in the Info.plist file) and would be called with the url “yourapp://success-handler” when the bookmark could be added successfully, otherwise your app would be called with the URL “yourapp://error-hander”.
Starting a search in iCab Mobile:
x-icabmobile://x-callback-url/search