This web page is for wise app-developers: those who would like their customers to be able to link the data of their app to anything they want.
Background information
Hookmark works with apps that have persistent documents, resources, or contexts that can be saved and opened or restored.
Hookmark works “out of the box” with many apps, using Hookmark’s default integration scripts to communicate with the app. For other apps, we create custom integration scripts. We just need the app to support the requirements that are summarized in the next section.
API Requirements
Hookmark merely needs your app to provide an API to do the following.
Please note: Hookmark does not specify the specific API for you. You just need to publish and implement an API that meets the requirements below. The API could be via x-callback-url, AppleScript / JavaScript, a command line interface or something else that is generally available.
Using your API, Hookmark or its enthusiastic automation community will create software integration scripts that enable users, via Hookmark, to link the data of your apps with your API.
We just need:
- An API to get the URL or ID of the current resource. This API could also return the name of the resource.
- An API to get the name of the current resource. This could be the overloaded into the previous API.
- A means of opening a resource, given a URL or ID.
- A way of creating a new resource in your app, given a particular name — for apps that enable creation of items. Ideally, you also enable us to add content to the new item (in case the user would like a linkback to be inserted into the document, for instance). You would provide the URL of the new item in return, or error information.
1. Getting the current item’s URL(s) or identifier
Hookmark needs a method to get the URL(s) (address(s)) or ID of the current item. Depending on your app, “current item” (aka, “current resource”) may mean different things, such as the currently open document or object, or the currently selected item (object or file) in a list.
- If your app, like BBEdit, transacts directly with files, and the files can be accessed directly via the Finder, then you should provide a method that returns the pathname, even if your app also has its own URL scheme.
- If your app, like OmniFocus, provides its own URL scheme for items (e.g. omnifocus:///), then provide a method to get the URL of the currently selected or open item.
- If your app has its own ID mechanism but (like Apple Mail) does not have a URL scheme, then at least provide a method that returns the ID of the current item. See opening items below.
The URL or ID must uniquely identify the resource; and it should be persistent. After the user renames or moves the resource, the URL or ID should still work.
If the resources of your app have two different addresses (typically: a file path and a proprietary URL), then please provide two different methods, one for each type of address. That will allow functions like Reveal File in Finder to work; and it will give users and CogSci Apps some flexibility in designing integration scripts and automations for your app.
1.1 file:// URI’s
If your app defines its own URL scheme for addressing items within it, then the basic get address script will return this URL. Even in this case, if your app’s resources are also regular files that the user can access via Finder, we ask that you provide an API for getting the file:// URL of the item. This will allow Hookmark to implement Reveal File in Finder. It will also allow Hookmark users to get hook://file/ URLs for your app’s resources.
1.2 Deep PDF linking
If yours is a PDF app, then it is very helpful to provide an API for getting the currently presented or selected page, and the top x and y coordinates of the selection (if any). The API should also specify the output parameter for the case where there is no selection. For instance, the x coordinate might be -1 in that case.
This information can be combined with the overall get address method. Or a separate API may be provided for it.
If your app manages its own URLs, it is important to document your URL format so that apps like Hookmark can tell that two URLs refer to the same document, except that one URL has one set of in-file addresses, whereas the other refers to the same document but with different or no in-file parameters.
For examples of deep-linking PDF APIs, see Deep PDF Links Take You Right Where You Need to Focus.
Douglas Englebart referred to this as “in-file addressability”.
1.3 Deep links in other apps
If your app represents data hierarchically, you may provide an API for other forms of deep linking. Ideally, for document-style apps, your URL scheme distinguishes the document from the address within the document (as web URLs typically do, with the # symbol indicating an in-page link). Please clearly document your URL scheme and API.
2. Getting the current item’s name
You should also provide a method to get the name of the current item, as defined above.
3. Opening the resource based on its address or ID
Obviously, it must be possible to open or restore the resource with the URL or identifier your app returned, per above. If your app already has an existing URL scheme and the URL can just be opened, then you don’t need to do anything more.
If your app uses IDs rather than URLs or pathnames, then you may simply provide a method or x-callback-url to open the item given the ID.
3.1 Opening deep links
If your app supports deep links, then please provide an API for accessing the page and x/y coordinates on that page. This could be a separate method to scroll to the particular page number and x/y coordinates on that page, or it could be built-into the URL or method for opening the entire document.
4. Creating new items
If your application supports the creation of new items and those items are files exposed in Finder, then CogSci Apps (and other developers) can automatically create new documents as long as we have a copy of a blank template and we know its filename extension(s). No API is required for such an app.
If your application supports the creation of other types of items, then please provide an API for creating new items. The API should normally accept a name as an input parameter. It should return the name of the created item, following the addressing guidelines above, and optionally the name of the item (in case your app has modified the name due to some of its rules).
By returning the address of the new item, it will be possible for users to enjoy the tremendous benefits of the Hook to New function, where in one go, Hookmark creates a new item and bidirectionally hooks it to a contextual item, while also bookmarking and potentially tagging both items.
You get extra points if your API also enables automation to:
- Insert hypertext in the new item. Hookmark would then optionally insert a hyperlink back to the source directly into the new item (as it does for Apple Notes, Craft and Drafts, for example) or in the new item’s note field (as it does for OmniFocus).
- Apply a tag to the new item (as Hookmark can optionally do with DEVONthink, Finder files and OmniFocus, for example).
Additional notes about URLs
If your software exposes the same data via a local app and via a web browser, it is important to ensure that third-party software can translate the URL received in the context of the app to the URL received in the context of a web browser. For instance, if an app’s URLs look like yourAppName://documentID and the web URLs look like https://yourWebsite/documentID, then Hookmark’s integration script can be written to detect that anything linked to the former is also linked to the latter.
Using universal links provides this for free.
It is important, therefore, for your web interface to expose — in the address bar — the URL of the current item. If the data is hierarchical, this should be reflected in the URL scheme or via an API, such that software can gauge the containment hierarchy. This will support deep-linking.
General API guidelines
Like any good API, yours should document any specific usage, parameter or condition restrictions. Please also document possible error conditions and their meaning. For instance, your “getAddress” API should have an error condition for the case where no item is currently open or selected. That information (e.g. an error code) can then be passed on (translated) by Hookmark to the user.
Examples
For examples of how other apps have been integrated with Hookmark, and how Hookmark integration happens, you can peruse the integration scripts in Hookmark itself. We recommend looking in particular at Hookmark’s integration with Craft (x-callback-url), Drafts (x-callback-url and AppleScript), OmniFocus (AppleScript) and BBEdit (AppleScript).
We like showcasing great apps that integrate well with Hookmark, in our release notes, emails to customers, on our blog, on the Hookmark forum, on social media and elsewhere.
Please don’t hesitate to contact us (hook@cogsciapps.com) if you have any questions. You can also ask questions directly on the Hookmark Forum to get our community talking about using your app with Hookmark.
x-callback-url
Hookmark is not fussy. It can work with AppleScript, shell commands and other local automation interfaces.
x-callback-url is an excellent and popular specification for inter-app communication. Hookmark uses it with several Mac apps, such as Drafts and Craft. An advantage of using x-callback-url rather than AppleScript is that it is also available on iOS.
Please see our web page on How to Make Your App Linkable via X-Callback-Url (For App Developers).
What’s a Linkable App and Why Does Linkability Matter?
That question is addressed here.
By making your app linkable, you will be in the company of other great Linkable Mac App developers, and be better positioned to compete with them.
In this day and age, consumers purchase many apps, and they need to be able to link their apps’ data to other apps. Otherwise, they will choose your competitor, whose app is linkable. And who would blame them?
Revisions
- 2022-03-25 with a link to the new x-callback-url help page.
- 2022-03-29. clarifications.