Skip to content


iCab Mobile 6.0 supports x-callback-url

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
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 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

Posted in iPhone & iPod Touch, Programming.

Tagged with , , , .


7 Responses

Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.

  1. TychoQuad says

    Thanks for these! Should be very useful for setting up complex browser based actions using Launch Center Pro!

  2. Gareth says

    Hello, I’ve got a bookmarklet working which sends a link, the current page, to Drafts, performs an action, and then returns me to iCab; but when I’m returned to iCab I’m in a new tab which has opened beside the tab I was in before; and so I’m wondering, is the way to have it work that when I’m returned to iCab I’m in the tab I was in originally?

    This is the bookmarklet:

    javascript:window.location=’drafts://x-callback-url/create?text=’+encodeURIComponent(document.title+’%5Cn’)+encodeURIComponent(location.href)+’&action=+clippings&x-success=icabmobile://’;

    Thanks for an help. And your app, iCab, is fantastic. I found it yesterday and I’m hooked (Chrome has been deleted; Safari is relegated to the last page).

  3. Alexander Alexander says

    @Gareth
    Please check the additional “iCab Mobile” settings you can find in the “Settings” App of the device. Here there is an option “Apps open URLs in Tabs” which needs to be switched off.
    This options decides if web pages opened by other Apps will open a new Tab.

  4. Gareth says

    Alexander, thanks so much for the response. Working as I want it to work, now.

  5. Luca DB says

    Hi and thanks for your great browser.
    Is it possible to add a bookmark in Safari (iPad) to open the current site in iCab?
    So everytime an app invokes safari, I tap the bookmark on the bookmark bar and then switch to iCab.
    Thanks for your reply,
    Luca

  6. Kris Dages says

    Is it possible to add a search engine name (and/or, preferably, a shortcut phrase) to the search command?

  7. Alexander Alexander says

    @Kris Dages
    Thanks for the suggestion. I’ll put this on my to-do list.



Some HTML is OK

or, reply to this post via trackback.