Blink URL Scheme and X-Callback-URL Documentation
Blink is a utility that makes it easy to create affiliate links to media in the iTunes Store, the iOS App Store, the Mac App Store and iBook store. The iTunes Affiliate program allows you to link to media in the iTunes stores and earn commissions from those links. After you are accepted into the iTunes affiliate program and receive an affiliate code, you can use Blink to automate the process of creating affiliate links. For more information on how affiliate links work and to sign up for the program, visit the iTunes affiliate program website and see this article I wrote on MacStories.net.
URL Scheme Support
Root Scheme - blink://
Blink provides workflow integration with other apps via the x-callback-url protocol. Using Blink's built in actions you can search for media and convert several types of iTunes media links into affiliate links that include your affiliate and campaign tokens.
Blink registers the "Blink://" URL scheme. Try typing "Blink://" into the mobile Safari address bar. If you have Blink installed, it should open.
But opening Blink is just the start. The Blink URL scheme can be used to search for media and copy a markdown-formatted or plain version of the resulting affiliate link and to convert several types of iTunes URLs to an affiliate URL. Using the x-callback-url protocol, you can invoke Blink from another app that supports the x-callback-url protocol and send the results to that or any other app that supports the x-callback-url protocol.
Search for Media With Blink:
Use Blink's URL scheme to quickly look up media on the App and iTunes stores and create an affiliate link that you can drop into any other app or document.
Actions and Parameters
- Action: search
- Parameter: q (required)
Note: search terms following "q=" must be separated by "+"
- Optional parameters: x-success
You can add the x-success parameter to your url to return a plain or markdown link to another app. Your x-success parameter must include a "[[link]]" placeholder for Blink to pass the link it generates to a destination app. For example sending:
from the iOS app Drafts by Agile Tortoise will search Blink for the game Monument Valley, automatically include any affiliate and campaign token you have saved in Blink's settings and give you the choice to copy a plain link, markdown link or to cancel the operation. In this example, if you choose to copy a plain link or markdown link, Blink would send the link back the Drafts where it would create a new note with the link. What you can do with a link via the x-success parameter will depend on the url scheme of the destination app. For instance, instead of creating a new note in Drafts containing the link generated by Blink, you could append the link to an existing note.
Convert Existing Links With Blink:
Convert Links: The iTunes affiliate program only works with store links formatted as follows:
Blink can convert the following short URLs to affiliate links:
- itunes.apple.com links whether or not they already include an affiliate and/or campaign token that is different than yours
Actions and Parameters
- Action: convert
- Parameter: URL (required)
- x-success (required)
- x-error (optional) Blink supports the x-error parameter. if you include a url after the "x-error=" parameter and an error occurs in Blink during link conversion, you will be taken to the url you specified in the x-error parameter. If you do not include the x-error parameter in your x-callback-url and an error occurs in Blink, an alert will be displayed in Blink notifying you of the error, but you will remain in Blink.
Link Types Supported
- appsto.re and itun.es short links:
The share button in the iOS versions of the iTunes Store, App Store and iBooks changed with the introduction of iOS 8. "Copy Link" now copies the title of the media and a custom short link. For example, using the share button on the App Store page for Monument Valley and then tapping "Copy Link" generates:
Monument Valley https://appsto.re/us/HaoAR.i
The trouble is, these short links are not supported by the iTunes affiliate program. Blink fixes that by detecting the end-point URL that is supported by the affiliate program and adding your affiliate credentials to it. If you choose to convert an appsto.re or itun.es link into a markdown, Blink will use the title as the text portion of the markdown link.
Overcast: Podcast Player by Overcast Radio, LLC https://appsto.re/us/jhe90.i
[Overcast: Podcast Player by Overcast Radio, LLC](https://itunes.apple.com/us/app/overcast-podcast-player/id888422857?mt=8&at=11lbfL&ct=Blink)
- appstore.com and itunes.com links:
Blink also supports conversion of itunes.com and appstore.com URLs, which likewise are not directly supported by the affiliate program. If more than one app, song or other supported media type matches the itunes.com or appstore.com URL that you send to Blink, you can choose one from the results and your affiliate credentials will be added to it.
- standard itunes.apple.com URLs:
In addition to converting short links, Blink can add your affiliate credentials to a standard link generated by iTunes regardless of whether affiliate and campaign tokens have already been appended to it. Thus,
https://itunes.apple.com/us/app/overcast-podcast-player/id888422857?mt=8 or https://itunes.apple.com/us/app/overcast-podcast-player/id888422857?mt=8&at=yourAffiliateToken&ct=yourCampaignToken
Using Blink with Callback URL Actions:
Some apps like the upcoming Drafts 5 support special callback url actions which make it simpler to chain multiple url scheme actions together. To take advantage of this improved workflow, omit the `[[blink]]` tag from the x-success URL passed to Blink. After generating a link, instead of looking for the `[[blink]]` tag Blink will automatically add a parameter called `result` to the x-success URL containing your affiliate link. Apps like Drafts that support the `result` parameter can be used to streamline existing actions.
Note that actions using the existing `[[blink]]` tag method still work and continue to be supported.
A Note About App Bundles:
The Blink URL scheme can convert app bundles URLs but without the bundle titles because app bundles are not supported by the iTunes Search API.