ZIP Downloads
What if your users have several MP3 files? Downloading each one individually, click-by-click, would be an annoyance. Imagine if they buy 10 albums — that could be hundreds of tracks!
Fortunately, the Rhymba Content APIs also provide a ZIP download option, and we're going to show you how to use it. It's only marginally more complicated than the "naked" MP3s, but it provides so much more feedback...
The Basics of ZIP Downloads
Using the download session token previously created, you simply construct a URL like so: https://dispatch.mcnemanager.com/current/dls/DownloadSessionToken/filename.zip.
- First off, the base URL is https://dispatch.mcnemanager.com/current/dls/. This invokes the ZIP download process.
- Next, you need to specify the DownloadSessionToken that you previously generated.
- Finally, you can specify the name of the ZIP file that is created & served; /download.zip is generic and valid, but you can get more detailed such as /YourStoreName-8-13-2013.zip or anything that's more descriptive for your customers. It should be url-encoded and less than 128 ASCII characters, and we recommend that it end in the extension “.zip”.
You can then serve that link to the user's browser, or even send it via email. The user simply clicks the link (or is redirected to it). The file is compressed so the customer’s file system should prompt them to unpack it on download completion, or they can double-click it. But that's just the basics.
What's Happening Behind-the-Scenes
Once a ZIP URL is hit, our content servers download the relevant content from our CDN and pack them up into the ZIP file. While the basic ZIP file process is just fine & dandy, maybe you want to provide visual feedback to your users as the process goes on. Fortunately, the ZIP download API also provides a progress URL that you can poll to give you the information you need to do just that.
Advanced ZIP Download Usage
You can check the progress of the ZIP file packaging process by hitting the following URL: https://dispatch.mcnemanager.com/current/dlsprogress/DownloadSessionToken.json, replacing DownloadSessionToken with the relevant download session token previously generated. You can also pass a callback query string parameter like ?callback=functionName if you'd like to receive the data back in JSONP format (which is recommended).
This URL will give you various status messages, and you can poll it every few seconds so that you can display feedback to your end users.
The ZIP File Lifecycle & the JSON it Returns
The Beginning of the Process
{
"status": "no progress",
"message": null,
"downloaded": 0,
"totalitems": 0,
"token": null,
"items": null
}Packaging Has Begun
{
"status": "started",
"message": null,
"downloaded": 1,
"totalitems": 3,
"token": "DownloadSessionToken",
"items": [
{
"status": "ready",
"type": "audio",
"id": 10547690,
"filename": "5 - The Lumineers - The Lumineers - Ho Hey.mp3",
"message": "ready for download"
},
{
"status": "packing",
"type":"audio",
"id": 12320362,
"filename": "10 - AWOLNATION - Megalithic Symphony - LP - Sail.mp3",
"message": "packing file into zip package"
}
]
}Track Packaging Is Complete; Downloading Album Art
{
"status": "started",
"message": null,
"downloaded": 2,
"totalitems": 3,
"token": "DownloadSessionToken",
"items": [
{
"status": "ready",
"type": "audio",
"id": 10547690,
"filename": "5 - The Lumineers - The Lumineers - Ho Hey.mp3",
"message": "ready for download"
},
{
"status": "ready",
"type":"audio",
"id": 12320362,
"filename": "10 - AWOLNATION - Megalithic Symphony - LP - Sail.mp3",
"message": "ready for download"
},
{
"status": "retrieving",
"type": "art",
"id": 0,
"filename": null,
"message": "retrieving album art"
}
]
}The ZIP File Is Going to Be Served
{
"status": "complete",
"message": null,
"downloaded": 2,
"totalitems": 3,
"token": "DownloadSessionToken",
"items": [
{
"status": "ready",
"type": "audio",
"id": 10547690,
"filename": "5 - The Lumineers - The Lumineers - Ho Hey.mp3",
"message": "ready for download"
},
{
"status": "ready",
"type":"audio",
"id": 12320362,
"filename": "10 - AWOLNATION - Megalithic Symphony - LP - Sail.mp3",
"message": "ready for download"
},
{
"status": "ready",
"type": "art",
"id": 0,
"filename": null,
"message": "ready for download"
}
]
}Looking at that JSON, by now you should find most of the fields self-explanatory. The various status values are as follows; please note that some can apply both to the overall ZIP file process as well as the individual tracks:
- packing: The ZIP file is being packed/compressed.
- started: The process has begun.
- complete: The process has finished.
- no progress: There is nothing to report on this item/ZIP quite yet.
- error: Something went wrong with this item or the ZIP file.
- ready: The item has been downloaded and is ready to be packed.
- serving: If your polling catches this in-action, this is when the ZIP file is being served to the user's browser.
- retrieving: The content is being downloaded from our CDN.
- connecting: Status is beginning, or the backend download process is being negotiated.
Using what's returned from these progress URLs, you could literally build a user interface that shows your customers the progress of each individual track in their order as it winds its way through the ZIP file process, maybe even with a progress bar. It allows for a great user experience!