As of version 2.0, Letterboxd for iOS adds x-callback-url support.
Following the x-callback-url specification, the scheme for Letterboxd iOS is:
letterboxd://x-callback-url/[action]?[action parameters]&[x-callback parameters]
-
query (optional STRING) The search query.
-
type (optional STRING) One of
film,member,list,review,contributor(cast & crew) orall. Defaults toall.
- name (optional STRING) The name of the film. The value is used as a search query, and the correct result will need to be manually confirmed before continuing.
Add a new log entry (diary entry or review) for a film.
-
name (optional STRING) The name of the film. The value is used as a search query, and the correct result will need to be manually confirmed before continuing.
-
date (optional STRING) ISO8601-formatted date that you watched the film, i.e.
YYYY-MM-DD. If absent, no diary date will be set. -
rewatch (optional BOOLEAN) Indicates that this viewing is a rewatch (as opposed to a first-time watch). Only valid if
dateis specified. -
tags (optional STRING) Comma-separated list of tags.
-
review (optional STRING) A review of the film. The text can include these HTML tags:
<strong> <em> <b> <i> <a href=""> <blockquote> -
containsSpoilers (optional BOOLEAN) Indicates that the review text contains spoilers. Only valid if
reviewis specified. -
rating (optional DOUBLE) A rating from 0.5 to 5, at 0.5 intervals. 0 is interpreted as no rating.
-
like (optional BOOLEAN) Indicates that your relationship to the film should be updated to show that you liked the film.
-
shareOnFacebook(optional BOOLEAN)DEPRECATEDEnables sharing of the review to Facebook. Only valid ifreviewis specified and you have also linked a Facebook account to your profile in Settings.
Note: For Boolean parameters, use true or false as parameter values, e.g. rewatch=true
This is optional but recommended for better user experience
x-callback-url defines several parameters with specific purposes, all of which are optional. These parameters should be passed as query parameters in the URL using the format key1=value1&key2=value2. All values should be URL-encoded strings.
-
x-success : URL to open upon completion of the requested action. If absent, the user will remain in the Letterboxd app once the action is successfully completed.
-
x-cancel : URL to open if the requested action is cancelled by the user. If absent, the user will remain in the Letterboxd app if the action is cancelled.
-
x-error : URL to open if the requested action generates an error or fails to complete. In such case, the Letterboxd app will report the failure to the user, and return to the source app. If absent, the user will remain in the Letterboxd app.
Some example uses of the URL scheme in action.
Drafts actions
— Search Letterboxd
Search the selected text in the Letterboxd app. Supported values for the type parameter are film, member, list, review, contributor (cast & crew) or all.
— Add Film to Watchlist Opens the Letterboxd app and uses the selected text to search for a film to add to your Watchlist. Following confirmation of the correct title, the film is added to your Watchlist and you are returned to the Drafts app.
— Log Film with Review Converts Markdown text to HTML, then opens the Letterboxd app and performs a search using the title of the note as the film name. Following confirmation of the correct film, a new review is populated.
Apple Shortcuts (was Workflow)
As of iOS 12, our native app supports a few simple Shortcuts (search, log a film, add to watchlist) which get donated to the system as you perform them. The workflows below employ the older x-callback-url approach from the Workflow app and are for more advanced use:
— Log Film
— Add multiple Films to Watchlist
— Log Review from input (compatible with Apple Watch!)
If you find any faults or wish to suggest improvements, please open an Issue.