VL Group

Rhymba v3.6 Documentation

Download Sessions

Download Sessions are at the core of download-based content delivery through the Rhymba Content API. Once you create your Download Session, you'll be able to deliver that content to your end users in a variety of ways. Let's dive right in.

Creating a Download Session

So, have you read about authenticating downloads through the Content API? Great! Then you're set to create a Download Session. You'll need the temporary request token created in that step. The method name you'll be calling is CreateDownloadSession. Once you've created your request token, you're ready to construct a request to our Content API for a Download Session.

  1. Make a GET request from your serverside environment to https://dispatch.mcnemanager.com/current/content.odata/CreateDownloadSession/, passing the following fields as query string parameters. We strongly recommend HTTPS, even though this call will likely be a server-to-server one. Required headers are in bold, but see the note below about "locked parameters":
Field Name Type Description Example
access_hint string The access_hint value returned from the creation of the request token.
access_req string The access_req value returned from the creation of the request token.
access_token string The access_token value returned from the creation of the request token, not your regular access token.
$format string Specify the format to return the data in. If this is missing or blank, atom will be used. json
albids integer[] Comma-delimited array of VL Groupalbum ids to be downloaded* 45346,34234,23145
codeid string Promotional code associated with this download, if any FreeTrackDownload1232
countryCode string 2-letter country where the download will take place US
ttlSeconds integer How long, in seconds, this download session should be available. Default is 24 hours (86,400 seconds). 86400
downloadLimit integer Number of download attempts allowed before this request becomes invalidated 3
mids integer[] Comma-delimited array of VL Groupmedia ids to be downloaded* 12133,44345
other string Other information tied to this download request that you want to protect against request tampering. See the note below about "locked parameters" for more details. This is also important if you plan on using our Download Manager Application and you want to use custom campaign banners. See our Rhymba Manager documentation here for more information about our Download Manager Application. cust_IP: 192.1.1.3, campaignId: 129
playlistId int Playlist ID from our Playlist API associated with this download, if any* my_songs
purchaseid string Purchase id associated with this download 14534632
test boolean Whether this download should be marked as a test in our system true or false
trackingid string Other tracking id for this download, if any unit_tests_Mar_3_2013_3
userid string Your identifier for the user receiving the download cust_name@gmail.com,cust2323
zip string ZIP code of customer receiving the download 11211
dirName string If using our lightweight Download Manager, the subdirectory that will be created in the OS default music folder when the user downloads. VendorName
plName string If using our lightweight Download Manager, the playlist name that will appear if users choose to import downloaded media into iTunes or Windows Media Player. My Awesome Playlist
expires string The fixed date of when the download session token expires.
maxUses int The maximum amount of times this download session token is able to be used in an attempted download.

* You can use either playlistId or albids/mids in a download session. You cannot provide a playlistId as well as mids or albids in the same download session call. If you provide media IDs and a playlist ID, the media from the supplied playlist will "override" the media content you request by ID.

  1. You'll get back a DownloadSessionToken object. We'll talk about how to use that download session token in the next few sections. The download session token contains the following fields:
Field Name Type Description Example
token string The download session token you should use in fulfilmment requests. 48F78023934E4C119ADE07879650A41F
url string Base url where the customer’s download request should be directed. https://dispatch.mcnemanager.com/current

Locked Parameters

Technically, almost all of the query string parameters — such as media IDs, ZIP code, and the like — in the GET request you issue to https://dispatch.mcnemanager.com/current/token.create are optional. Any parameters you include in the GET request are used to calculate the hashed temporary token you receive back; that means that if the end user tampers with the parameters (say, to attempt to download an additional album, or different tracks), the token won't work for them. On the flip side, that means that if any of this data is subject to change you should omit those parameters from the call to token.create.

Generally, you'll want to rely on the hashed temporary token, though, so you should populate any of the query string parameters that don't have a business or technical reason to change.

Example: if the download is going to be for an album and you omit the mids parameter rather than pass an empty array, your user will be able to pass in a list of media IDs and download them — even though that's not what you want — because the mids parameter wasn't used at all in calculating the hashed temporary security token. So be sure to include empty arrays for albids or mids if there are to be no downloads of that type of content.

Onward and Downloadward

So now you've got your download session token. It's finally time to start getting content to your users. You have several options linked above, starting with so-called "Naked" MP3s; so on to the delivery!

Retrieving Information About a Download Session

After a download session has been created, if you want to check its status within our system for customer service or informational purposes, you can call the GetDownloadSessionInformation method. To start, you'll need the typical API authentication token, but you'll also need the download session's token.

To get the download session information, make a GET request from your serverside environment to https://dispatch.mcnemanager.com/current/content.odata/GetDownloadSessionInformation/, passing along the token as a query string parameter called token. We strongly recommend HTTPS, even though this call will likely be a server-to-server one.

If the download session is located in our API for your login, the following information will be returned:

Field Name Type Description
token string The same download session token you used when calling this method.
successfulServes integer The number of times our system has successfully served out the download session.
failedServes integer The number of time our system has encountered an error that would caused files to not be served out.
resetAmount integer The amount of times you have called UpdateDownloadSession (see below) and given the maxUses a new value, effectively resetting the download session.
totalContentCount integer The total count of pieces of tracks contained in this download session. This expands album track counts, so if the download session contains an album with 15 tracks plus 3 "loose" tracks, the value of total_content_count will be 18.

Updating a Download Session

If you need to change something about a download session you've previously created, the UpdateDownloadSession method is the way to go. Just as when calling CreateDownloadSession, you'll need the temporary request token created during API authentication.

To update a download session, make a GET request from your serverside environment to https://dispatch.mcnemanager.com/current/content.odata/UpdateDownloadSession/, passing the following fields as query string parameters. We strongly recommend HTTPS, even though this call will likely be a server-to-server one. Required parameters are in bold:

Field Name Type Description
token string The token for the download session you wish to update.
ttlSeconds integer Update the TTL (time to live) for this download session token.
downloadLimit integer The maximum amount of times this download session can be downloaded by the user.
dirName string If using our lightweight Download Manager, updates the subdirectory that will be created in the OS default music folder when the user downloads.
plName string If using our lightweight Download Manager, updates the playlist name that will appear if users choose to import downloaded media into iTunes or Windows Media Player.
expires string Updates the fixed date of when the download session token expires.
maxUses int Updates the maximum amount of times this download session token is able to be used in an attempted download.