Thursday, September 20, 2018

Thanks for the Surprise Integration with my Website, Apple!

Update: This post made the front page of Hacker News! Check out the discussion on HN.

Those of you who are avid readers of my Stack Overflow profile know that I am the creator of, a popular guitar chord and scale calculator website. I'm also a longtime fan of Apple products. So you can imagine my surprise and delight when I received this message in my inbox this week from a JGuitar user:

Is there a way to select a specific instrument (like ukulele) via the URL - so that I'd have a link that would take me right to chord search for that instrument?

I am starting to mess around with iOS's new shortcut function. They have a shortcut for searching chords on your website, but it defaults to guitar; I'd like to make a ukulele version of the shortcut.

Hold on a sec... Did Apple really integrate their new iOS shortcuts feature with my website? How is it possible I didn't know this was coming? No one from Apple reached out to me. I had eagerly upgraded my iPhone X to iOS 12 earlier that day but hadn't yet discovered "shortcuts". Naturally, I immediately wanted to see this in action.

After a little googling, I learned that in order to add shortcuts, you need to download the Shortcuts App from the Apple App Store.

After installing and launching the Shortcuts app, you're greeted to an empty Library screen. In order to use a shortcut, you need to either create one from scratch or select a pre-made shortcut from the gallery. I clicked on the Gallery icon, scrolled down to the "Tools for Making Music" section and saw the "Guitar Chord Finder" shortcut.

Could this be it? The description didn't mention I clicked on it. There were instructions for how to use the shortcut but still no mention of When I clicked "show actions" it revealed the "actions" that make up the shortcut and I could finally see the link in the URL section. Here are the complete actions that make up the Guitar Chord Finder Shortcut.

In a nutshell, the shortcut uses the user's input (a chord symbol) to construct a url to a chord search result page on and then looks for 200x200px chord diagram images on that page and shows them to the user. The rest of the web page isn't shown.

There are a couple of things I would have done differently in these shortcut actions. Firstly, I would have used an https url instead of http and secondly, I would have made it look for images with a width & height greater than 200px rather than equal to 200px. That would give me the flexibility to boost image resolution without breaking the shortcut. And boosting image resolution is an easy change for me since all the chord diagram images are dynamically generated on the fly and cached.

Now that I had found and understood the feature it was time to take it for a test drive. I added the Guitar Chord Finder Shortcut to my Library and played with it both within the Shortcuts App and via the voice command: "Hey Siri: Guitar Chord Finder". Both worked as expected.

I was also able to easily modify the shortcut to support ukulele as requested by my user. I just added ?instrument=Ukulele to the url field and replaced the image width rule with one that matches images with width greater than 100px.

To check if users are actually using this feature, I scanned my log files. Sure enough, the following user agent string started appearing thousands of times a day in's web server logs on 9/17/2018:

Shortcuts/700 CFNetwork/974.2.1 Darwin/18.0.0

I'm genuinely thrilled that someone at Apple deemed my chord calculator technology worthy of inclusion in the iOS shortcuts gallery. If anyone from Apple is reading this, please reach out using's contact form. We can work together to make this experience even better. I can provide high quality SVG images of all chord diagrams, support alternate tunings, instruments and more.