Sacred Music – Deep Linking API

The sacredmusic:// URI scheme allows you to link into the Sacred Music app, in a similar way that a link with https:// 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 sacredmusic:// links can be sent by email or posted on web pages. Here are some examples of URI schemes:

In order for sacredmusic:// links to work, the Sacred 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 Sacred 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.

Historical note: Sacred Music was previously called “LDS Music.” LDS Music 1.0.1 for iOS introduced the ldsmusic:// scheme (basic linking to songs, for linking from Gospel Library). In 1.4.0 (iOS), linking for collections and playlists was added, and 1.8.0 (iOS) introduced linking using Gospel Library content URIs. The ldsmusic:// scheme was added to LDS Music for Android in version 1.1.0. In April/May 2019, when the app was renamed to Sacred Music, the sacredmusic:// URI scheme was introduced. The sacredmusic:// URI scheme is preferred, though ldsmusic:// is still supported.

Opening the app

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

  • sacredmusic:// – Open the app without going anywhere.
  • sacredmusic://content – Open the app and go to the home screen.
  • sacredmusic://content?lang=por – Open the app and go to the home screen, with Portuguese content. More information about the language parameter can be found further down, under “Optional parameters.”

Going to a specific collection or song

The best way to link to a collection or song in Sacred Music 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:
sacredmusic://content + [collection URI] + ? + [optional parameters]

The formula for a song link is as follows:
sacredmusic://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 Sacred 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 Sacred Music for iOS, the parameters return_url and return_name were previously used to provide a return link to where you were before clicking the sacredmusic:// link. However, this feature was removed because iOS 9 and newer provide a built-in back link when you link from one app to another. In Android, the regular back button provides the same functionality. For historical reference, here are a few examples:

Creating a playlist (iOS only)

You can use the sacredmusic:// URI scheme to share or back up a playlist from Sacred Music for iOS. The easiest way to generate a playlist link is to create the playlist in Sacred Music, then use the Share options to share the link with yourself. Because playlists don't sync, 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 Sacred Music isn't installed or supported. While it's difficult to detect if an app 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 Sacred Music, be sure to invite your users to download the Sacred 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:

Unfortunately, not all websites and apps recognize custom URI schemes like sacredmusic://. For example, if you try to share a sacredmusic:// link on Facebook, it won't recognize it as a tappable link. Similarly, if you try to embed a sacredmusic:// link in a PDF, only some PDF readers will open the link as expected. To work around this, you can use a link that starts with https:// and redirects you to the app. Here are some examples: