LDS Music App: Deep Linking API

The ldsmusic:// URI scheme allows you to link into the LDS Music app, in a similar way that a link with http:// opens into your default web browser. Linking to a specific location in an app (instead of to a web page) is called deep linking. Properly-formed ldsmusic:// links can be sent by email or posted on web pages. Here are some examples of URI schemes:

In order for ldsmusic:// links to work, the LDS Music app has to be installed on the target device (Android or iOS), and whatever app you're linking from has to recognize it as a link so it's clickable. Also, deep links might not work as expected if there is more than one version of the LDS Music app installed at the same time (for example the released version and a beta version), because the device won't know which version of the app to open.

The ldsmusic:// protocol handlers were first introduced for LDS Music for iOS, 1.0.1 (November 2011, basic linking to songs to allow linking from Gospel Library), extended in 1.4.0 (April 2013, linking for collections and playlists), and improved in 1.8.0 (November 2016, allow linking to songs using Gospel Library URI format). They were later added to LDS Music for Android, 1.1.0 (March 2016, basic linking to songs and collections using Gospel Library URI format).

Opening the app

Here are some basic links that allow you to open the app without going to specific content:

Going to a specific collection or song

The best way to link to a collection or song in the LDS Music app is using the collection and song URI. Since November 2016, this method works on both iOS and Android, and it follows the same pattern as Gospel Library.

The formula for a collection link is as follows:
gospellibrary://content + [collection URI] + ? + [optional parameters]

The formula for a song link is as follows:
ldsmusic://content + [collection URI] + / + [song URI] + ? + [optional parameters]

Here are some examples of links to specific collections or songs:

While not required, it's a good idea to include a language parameter at the end if you want to link to a specific song in a specific language. If you don't specify a language, it will use the default language, which is the language of the device – which may cause an error if the song you want to link to doesn't exist in that language. Here are a few examples (more information about the language parameter can be found further down, under “Optional parameters”):

Older versions of LDS Music for iOS used "external IDs" to link to a collection or song, instead of collection and song URIs. While this method still works on iOS, it has been deprecated in favor of the URI system. A few examples are here for historical reference:

Optional parameters

The language parameter, lang, allows you to specify the language of the content you want to link to. In general, three-letter ISO 639-3 language codes are used. An exception is Chinese: "zho" is used for Traditional Chinese, and "zhs" is used for Simplified Chinese. Here are some examples using the language parameter:

In LDS Music for iOS, the parameters return_url and return_name can be used to provide a return link to where you were before clicking the ldsmusic:// link. Be sure to properly escape special characters in the parameter values. This feature is less useful since iOS 9, which provides a built-in back link when you link from one app to another. However, for historical reference, here are a few examples:

Creating a playlist (iOS only)

You can use the ldsmusic:// URI scheme to share or back up a playlist from LDS Music for iOS. The easiest way to generate a playlist link is to create the playlist in LDS Music, then use the Share options to share the link with yourself. Because playlists don't sync with, it's a good idea to share important playlists with yourself before updating or reinstalling the app, in case you need to recreate them. Playlist links use song external IDs. Here are a few examples:

JavaScript for linking from a web page

While deep links are useful in a mobile context, they become much less useful on devices where the LDS Music app isn't installed or supported. While it's difficult to detect if an app like LDS Music is installed on a user's device, it is relatively simple to detect if a user is using iOS or Android, and adapt accordingly.

If your app or web page has deep links into the LDS Music app, be sure to invite your users to download the LDS Music app, and provide an alternative experience for users who aren't using Android or iOS. Here are some examples of HTML links that work on Android or iOS, with varying experiences on a desktop computer: