Developers
Open Song
Not only can you use the onsong:// URL scheme to import content into OnSong, but you can also use it to view specific songs in your library. Since this is a URL scheme, it will result in opening OnSong and bringing it to the foreground if it's not already being viewed. If you are viewing OnSong using a split screen or other multitasking configuration on an iPad, it will remain this way. That makes URL open actions ideal for use if your app is running in portion of the iPad screen.
Requirements
The Open Song URL API is only available in OnSong 2020.8 and higher. You can join our beta team to get pre-release versions of OnSong for testing. Since the onsong:// URL scheme is used on every version of OnSong, you'll want to ensure you only have the beta version installed to avoid conflict with other versions of the app.
Checking Installation
Of course to use any of these API calls, you'll need to ensure the user has OnSong installed on their device. To do this, add onsong as a registered URL scheme. Without this, your app will not be able to open OnSong scheme. However this does not apply to web-based apps.
Once registered, you can use the [UIApplication canOpenURL:] method to determine if the URL can be opened. If that returns false, then the OnSong app is not installed and you can present an appropriate user interface to have the user install OnSong. For instance, through an affiliate link. You can request to become an affiliate partner with OnSong by emailing us.
View Song
The most simple action is to open a song. OnSong can do this by either searching by song title, or by song identifier. This uses the base action path and the song querystring parameter. To open the song Be Still, we'd use this:
onsong://open/songs?song=be-still
Alternately, we could pass a known unique identifier for the song querystring parameter like so:
onsong://open/songs/?song=85F0CE06-7414-4FFB-BFF0-14D3507A1AA7
View Collection
Collections in OnSong include books but also the standard collections like All Songs and Unbound Songs. You can load the All Songs collection into the song viewer using the collection querystring parameter like this:
onsong://open/songs/?collection=all-songs
Alternately, you can load the contents of a book in the same way:
onsong://open/songs/?collection=christmas-songs
View Set
Sets in OnSong are used to perform songs for a specific gig. URL actions let you either load an existing set, or create new ones. We will start by simply viewing the current set like this:
onsong://open/songs/?set=current-set
Navigation
Of course loading a set is incredibly helpful, but what if we want to navigate through the set? Using the index querystring parameter, we can move through the currently viewed songs whether they are in a collection or set.
To move to the first song, we can use the first value:
onsong://open/songs?index=first
Or just as easily go to the last song in the song viewer:
onsong://open/songs?index=last
Or where ever we can just go to the next song in the song viewer:
onsong://open/songs?index=next
Or go back to the previous one:
onsong://open/songs?index=previous
Or go to any song using its numeric index, the first song being at index zero. To go to the second song in the set, we'd use:
onsong://open/songs?index=1
Pulling Songs
This is where things get slightly crazy, or as developers would say more "powerful". We can use this same API to load multiple songs into the viewer by repeating the song querystring parameter. We can then take those songs and load them into the current set, or create a new set.
To view multiple songs and not save it, we just use the song parameter multiple times in the order we want them to appear, including an optional index parameter if we don't want to start at the beginning of the set:
onsong://open/songs/?song=be-still&song=beautiful-life&song=changes&index=1
To add these songs to the currently viewed set, we pass the set parameter with the name of the set we want to create:
onsong://open/songs/?song=be-still&song=beautiful-life&song=changes&set=New+Set
Or we can load it into the current set using the current value for the set parameter:
onsong://open/songs/?song=be-still&song=beautiful-life&song=changes&set=current
Of course we can also use a name to load the song into a named set, or use the set's unique identifier if it is known. Here we add a known song into a known set at the fourth position:
onsong//open/songs/?song=85F0CE06-7414-4FFB-BFF0-14D3507A1AA7&index=3&set=8DD5B78C-205A-4F6E-AD09-63711F372BD3
Exporting Songs
But how would you know the unique identifiers to call in an individual's library? The OnSong URL Action API gives you an export function. To export values, you let the API know what to export (song, set, collection) and then where to send that data. For instance:
onsong://export/songs?collection=current&returnURL=http%3A%2F%2Fmywebsite%2Ecom%2Freceive%3Fdata%3D
In the above example, OnSong will take the currently loaded collection in the song viewer, create a list of song content, and generate Base64 encoded data, appending it to the provided returnURL parameter. In this case, we've used http://mywebsite.com/receive?data= so the data will be sent to the end of that URL. Of course you could just as easily make this a URL scheme that opens your app and passes the song list as well.
While the data is encoded for easy transmission, once decoded the list format is a very simple tab-delimited list. The properties that are listed are contained in the first row, with each song appearing to preceding rows delimited by a newline character. This means you can split the content by newline, then by tabs, using the first line to describe the data in each of the columns.
We can also specify the properties that we want to export. By default, OnSong will export the songs's ID, title and artist. However we could also export the key, transposed key, capo and more like this.
