Tucows Downloads Download Module API
Thank you for your interest in the Tucows Downloads affiliate program. You should already have read and agreed to the terms of the Tucows Downloads Affiliate Agreement and have been issued an affiliate ID by Tucows Downloads for use with this API. If you do not supply a valid affiliate ID when requesting the Tucows Downloads Download Module, you will not be given credit for downloads generated through your website.
The purpose of the Javascript API is to give you access to customize the Tucows Downloads Download Module for your website. Note that any customization must adhere to the affiliate agreement and that failure to do so may result in the termination of your account. For those that want to get up and running quickly, Tucows Downloads provides a module wizard that can be used to offer downloads on your site without any programming on your part. More advanced users can continue reading this document for information on customizing the download module.
Download Module Wizard
To get you up and running quickly, Tucows Downloads provides the following editor to generate a download module for your site. Simply update the attributes below to fit your needs and click the 'Generate Code' button. A Javascript will be generated in the box below that you can copy-and-paste onto your website. If you click on any of the color attributes, a color picker will be launched to assist you in selecting colors. The module to the right of the form (bottom for horizontal modules) will show you what the module will look like with the parameters that you've specified.
Advanced Scripting
The Tucows Download Module API requires that you first set some Javascript variables, define a callback function called tucows_affiliate_finish and finally invoke the module. A simple example follows:
<div id='downloads'></div>
…
<script language="JavaScript">
tucows_affiliate_id = "0123456789abcdef0123456789abcdef01234567";
tucows_affiliate_numdl = 3;
tucows_affiliate_keywords = "FTP SERVER";
tucows_affiliate_library = "Windows";
function tucows_affiliate_finish(resp)
{
if ( !resp.status )
{
document.getElementById('downloads').innerHTML="<font color=red>An error occurred: " + resp.error_message + "</font>";
}
else
{
var s='';
if (resp.dls.length >= 1)
{
s += '<img src="https://author.tucows.com/images/tucowslogo20.gif" style="border: 0; vertical-align: bottom; float: right">';
s += '<span class="t_head">Downloads by Tucows</span>';
s += '<table cellspacing="1">';
while ( i = nextDl() )
{
var a = '<a target="_blank" href="' + i.url + '" ' +
'onmouseout="window.status=\'\'; return true;" ' +
'onmouseover="window.status=\'go to ' + i.visible_url + '\'; return true;"' +
'style="color: #4397ec;">';
s += '<tr><td><div class="t_ad">' + a +
'<span class="t_title">' + i.title + '</span></a><br />' +
'<img src="' + i.rating_img + '" style="margin: 3px 0 0 0;"><br />' +
'<b>Category:</b> ' + i.category + '<br />' +
'<span class="t_desc" style="margin: 3px 0 3px 0;">' + i.description + '</span><br />' +
'<span class="t_url" style="color: #08f; font-size: 12px;">' + a + i.visible_url + '</a></span>' +
'</div></td></tr>';
}
s += '</table>';
}
document.getElementById('downloads').innerHTML = s;
}
return true;
</script>
<script language="JavaScript" src="https://author.tucows.com/dl/affiliate.js"></script>
The callback function in this example retrieves each download in the set, formats the desired fields in an appropriate manner for the site and then displays the download module inside of a DIV with the ID 'downloads'. In this way, the Javascript can be invoked at the bottom of the page and the download module can be displayed anywhere on the page. In the event of an error, the error is display in place of the download module. You could also choose to ignore errors and display nothing or alternate content in that case. You can also display the download module inline by substituting:
document.getElementById('downloads').innerHTML = s;
with
document.write(s);
The Request
Prior to requesting the download module, the following parameters can be used to customize the result set.
| Parameter Name | Required | Default | Description | Acceptable Values |
| tucows_affiliate_id | Yes | N/A | Affiliate ID | Supplied by Tucows |
| tucows_affiliate_test | No | Off | Used to test the download module | If > 0, test mode is on |
| tucows_affiliate_numdl | No | 5 | Number of downloads to retrieve | Number between 1-5 |
| tucows_affiliate_page | No | 1 | Page number* | Number between 1-3 |
| tucows_affiliate_keywords | No** | Page Title + Meta Keywords/Description | Keywords used to target downloads | See usage below |
| tucows_affiliate_library | No | Windows | Library to pull downloads from | One of Windows, Macintosh, Linux, PDA, Games or Themes |
| tucows_affiliate_maxdesc | No | 90 | Maximum number of characters for the description | Values < 25 are ignored |
* Page number can be used to build multiple download modules on a single page or to span a set of downloads over mutlipe pages. For example, say that 6 downloads are available relating to HTML editors. If you wanted to select the first 3 downloads for page one of an article about building websites and the next 3 for page 2 of the article, you'd specify page number 1 with a maxium of 3 downloads for page one of the article and page number 2 with a maximum of 3 downloads for page 2 of the article.
** While not required, keywords are recommended unless you supply a unique meta description or set of meta keywords (or at least descriptive titles) for every page that uses the download module. The keywords are given as a space delimited list of words and are used to target downloads. To require a match, '+' can be used to preceed the word. To exclude titles that match a word, '-' can be used to proceed the word. For example, to match titles that must match the word 'FTP', may match the word 'SERVER' and should not match the word 'SSH' the following keywords could be used: "+FTP SERVER -SSH".
The Response Object
As shown in the example above, the Javascript callback function that you create should expect one parameter, the Download Response Object. The Download Response Object is defined with the following attributes:
| Attribute | Description |
| status | After a request, 1 means success and 0 means an error occured. |
| error_message | If an error occurs, contains a description of the error |
| dls | Array of download objects.* |
* The dls attribute contains an array of download objects on success. This array can be accessed directly or the affiliate.js library provides the function nextDl() to retrieve them individually (see the example above).
The Download Object
The Response Object defines an array of download objects (refer to Response Object above). The download object is defined as follows:
| Attribute | Description |
| pos | The position of the current download in the list |
| title | The download title |
| category | The category from the library where this title can be found |
| license | The titles license (Freeware, Shareware, GPL, etc) |
| cost | The cost to purchase the title | popularity | The title's popularity on Tucows (0-100% or Newly Added) |
| description | A short description of the download (max 90 characters) |
| rating | Text version of the rating (3 Cow, 4 Cow, etc) |
| rating_img | A link to the graphical representation of the rating |
| url | Click-through URL for the download |
| visible_url | Shortened URL useful for display purposes |
For feature requests, comments and bug reports please contact developer@tucows.com.
