How to Make Your App Linkable via X-Callback-Url (For App Developers)

Developers of third-party apps who want to make their apps linkable via automation without using AppleScript can do so by supporting some very simple x-callback-url APIs.

x-callback-url is a specification for interapp communication. It allows apps to define methods with parameters by way of URLs.

The specification is available at x-callback-url.com. It was “written by Greg Pierce, of Agile Tortoise. Ideas, contributions and comments have been provided by many — including encouragement early on by Marco Arment, Justin Williams and others.”

If you are not yet familiar with the x-callback-url specification, then please read it. That will make the following very easy to understand. You’ll notice from the x-callback-url website that many Mac apps implement some x-callback-url’s.

To make your app linkable, you will define two x-callback-url’s of your own. One for getting the address and title of the currently selected or open item, the other for creating a new item in your app.

Please keep in mind that it’s up to you to define the specific API, i.e., the specific URL name, and the specific names of parameters. You can have extra parameters that are not mentioned below. You don’t need to know Hookmark’s API. Nor do you need to understand how Hookmark’s integration scripts work. You’ll be defining APIs that can be used by any app, not just Hookmark.

Once you have defined and implemented the x-callback-urls in your app, we at CogSci Apps Corp. will be able to make use of them in Hookmark. (Hookmark Pro customers will also be able to write their own integration scripts to make Hookmark work with your app.)

1. URL to return the Name and Address of the current item

Please provide a URL that takes at least one input URL for the x-success case with at least two parameters:

  • name of the currently selected item (example key title or name)
  • URL of the currently selected item (example key url) in your app’s native scheme
  • file:// URL of the item, if the file is meaningfully available to the user via Finder

Optionally (ideally), it would also accept an x-error URL in accordance with the 1.0 DRAFT Spec | x-callback-url specification.

Example 1: Agile Tortoise defines a Drafts /getCurrentDraft URL scheme as follows:

Return the information about the current draft loaded in the editor. To use, you must include an x-success callback URL. Drafts will call the x-success URL with uuid, url, title, and content parameters with values related to the current draft. Mostly useful to access a link to the current draft from outside the app.

  • Arguments
    • none
  • Examples
    • drafts://x-callback-url/getCurrentDraft?x-success=[callbackurl]

If you examine Hookmark’s script for Drafts you will see how Hookmark uses it, which is something like this:

set hookCbURL to "hook://x-callback-url/setCurrentNode"

set draftsURLtoGetNameAndAddress to "drafts://x-callback-url/getCurrentDraft?" & "&x-success=" & hookCbURL

set getNameAndAddressScript to "open '" & draftsURLtoGetNameAndAddress & "'"

do shell script getNameAndAddressScript
return hookCbURL

But that need not concern you. It is possible to implement x-callback-url for linking without Hookmark. (Some developers have done it without even having a Mac.)

Example 2: Luki Labs defines a Craft app /getCurrentPageInfo? URL scheme which Hookmark uses. Check out Hookmark’s Script Editor to see our use of it.

2. URL to add a new item in your app

If your app allows users to create new items (e.g., new notes, tasks or documents), then please provide an x-callback-url for doing this. It should accept the following parameter:

  • The new item title, given by Hookmark (or other app that uses your x-callback-url). You’ll create a new item with this title. See <encodedTitle> in the example below.

Optionally, it may also accept:

  • Content. Your app would insert this content in the new item. Hookmark likes to place a linkback (in Markdown or RTF), for instance, inside the items it creates.
  • Tag names.
  • Any other parameters you want. It’s your API after all.

It should return:

  • The new item’s title (because you might not have accepted the precise title you were asked).
  • The new item’s URL native to your app.
  • If available, the file:// URL (path) of the new item.

It may also return additional parameters, which Hookmark might ignore. (If they’re relevant we’ll try to use them sensibly).

Example 1: Luki Labs defines a Craft app /getCurrentPageInfo? URL scheme which Hookmark uses.

Their example:

craftdocs://createdocument?spaceId=zsomborf&title=hello&content=this%20is%20content&folderId=

possible values in result from the latter: blockld; spaceld; link.

In case you’re curious, check out Hookmark’s Script Editor to see our use of it. Here’s what that might look like:

craftdocs://createdocument?title=<encodedTitle>&x-success=<hookCbURL>&x-error=<hookCbURLError>

  • <encodedTitle> is from Hookmark, used by Craft to create a new doc.
  • <hookCbURL> is our callback. You don’t actually need to know this, but just FYI we do the following before passing this parameter to that callback URL:

set hookCbURL to "hook://x-callback-url/link-to-new"
set hookCbURL to hookCbURL & "%3FurlKey%3Dlink"  & "%26src%3D" & encodedSrc & "%26title%3D" & encodedTitle

In a nutshell

So, in a nutshell, by providing the first x-callback-url (URL to return the Name and Address of the current item), you will enable Hookmark to discover the name and URL of the currently selected or open item in your app.

By providing the second one, you will enable Hookmark to:

  1. create an item in your app with a given name;
  2. know what the URL of the currently selected item is; and
  3. optionally write some information in the newly created item.

Each method will in turn allow Hookmark to create “hooks”, bidirectional links between information in your app and information that is potentially elsewhere.

Questions?

If you have any questions along the way, please feel free to contact us.

Then please let us know… 😊

Once you’ve implemented the x-callback-url, please contact us to let us know. We’ll be happy to have a look to add integration to Hookmark. If you could provide a coupon code for your app for a developer and QA here that would be grand. You can even share your new API on the Hookmark Forum (automation category). The community will be delighted to discover another linkable app. Many automators participate in our forum who might even jump in and share an integration script that can be used inside Hookmark’s Integration Scripts preferences panel.