Information for Developers to Make Their Apps Linkable (API Requirements for Compatibility with Hook)
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.
Hook works with apps that have persistent documents, resources, or contexts that can be saved and opened or restored.
Hook works “out of the box” with many apps, using Hook’s default integration scripts 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.
Hook merely needs your app to provide an API to do the following.
Using your API, Hook or its enthusiastic automation community will create software integration scripts that enable users, via Hook, 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
Hook 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 transacts directly with files and the files can be accessed directly via the Finder Finder, then you should provide a method that returns the pathname, even if your app also has its own URL scheme.
- If your app provides its own URL scheme for items, then provide a method to get the URL of the currently open item.
- If your app has its own ID mechanism but not URL scheme, then at least provide a method that returns the ID of the current item. See opening items, below
The ID and URL must uniquely identify the resource, and it should be persistent. If the resource is renamed or moved, it shouldn’t affect the identifier or break the URL.
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.
1.1 file:// URI’s
If your app defines its own URL scheme for addressing items within it, then the basic get address scheme 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 Hook to implement
Reveal File in Finder. It will also allow Hook 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 apps manage its own URLs, it is important to document your URL format such that apps like Hook 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 of PDF APIs, see Deep PDF Links Take You Right Where You Need to Focus – Hook.
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 a fragment). 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 parameters 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 on the 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 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 Hook 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. Hook 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 (e.g., as it does for OmniFocus).
- apply a tag to the new item (as Hook 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 apps URLs look like yourAppName://documentID and the webURLs look like https://yourWebsite/documentID, then Hook’s integration script can be written to detect that anything linked to the former is also linked to the latter.
Using universal links provide 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, your API should document any specific usage, parameter or condition restrictions. Please also document possible error conditions and their meaning. For instance , your “getAddress” API would have an error condition for the case where no item is currently open or selected. That information (error code) can then be passed on (translated) by Hook to the user.
For examples of how other apps have been integrated with Hook, and how Hook integration happens you can peruse the integration scripts in Hook itself. We recommend looking in particular at Hook’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 Hook, in our release notes, emails to customers, on our blog, on the Hook productivity forum, on social media and elsewhere.
Please don’t hesitate to contact us (email@example.com) if you have any questions. You can also ask questions directly on the Hook Productivity Forum to get our community talking about using your app with Hook.
Hook is not fussy. It can work with AppleScript, shell commands or other local automation interface.
x-callback-url is an excellent and popular specification for inter-app communication. Hook uses it with several Mac apps, such as Drafts and Craft. An advantage of using it 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 Apps, 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?
- 2022-03-25 with a link to the new x-callback-url help page_.
- 2022-03-29. clarifications.