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.
- 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":
|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: 220.127.116.11, 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 email@example.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.
- 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:
|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|
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:
|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:
|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.|