(I) Download Service to a Web Browser - JavaScript
Overview:
There are 5 basic steps to integrate the Download service to a Web Browser using JavaScript and start using DNA to deliver content through the DNA peer network:
- Check that the existing distribution infrastructure conforms to the Basic DNA Integration Requirements
- Access the DNA JavaScript file at http://btdna.bittorrent.com/btdna.js or host it somewhere on your website
- Load the DNA JavaScript file on each page that links to content to be DNA-enabled
-
a) Use the DNA JavaScript API to modify the URLs of each piece of content to be DNA-enabled
-OR-
1. Check Basic DNA Integration Requirements
Integration of the DNA service relies on some basic requirements from your existing distribution infrastructure.
You can check whether your content servers meet these requirements by using the DNA URL Requirements Tester Tool. The Tester tool is a simple text box into which you can type the fully qualified URL of a piece of your content on one of your content servers. It will return advice on whether servers conform to ideal DNA requirements. In cases where your distribution infrastructure does not conform to these requirements, the Tester Tool will provide an error message as to the issue, and the infrastructure should be reconfigured accordingly. For a list of potential error messages and corresponding solutions see DNA URL Requirements Tester Tool. For any additional assistance use BitTorrent DNA support.
The following is the list of requirements for your distribution infrastructure to conform to ideal DNA requirements:
Web-servers:
- You must have access to web servers and have permissions to host a DNA JavaScript file to be provided by BitTorrent Inc.
- You must have permissions to adjust HTML on your website to load the DNA JavaScript file on each relevant page and be able to modify content URLs on the page to invoke functions that the DNA JavaScript file provides.
Content-servers and Content:
- Your content servers must support “range requests” and should support “persistent” or “keep-alive” connections of at least 2 seconds duration.
- You must have exclusive use of the domain or domains from which the content is served.
- You must know the fully qualified URL or URLs for each piece of content to be DNA-enabled.
- The fully qualified URL or URLs for each piece of content must be persistent over time.
- The actual files to which the fully qualified URL or URLs point must remain unchanged over time.
- Content servers must not require any form of authentication to enable downloads. BitTorrent DNA only supports HTTP (HTTPS is not yet supported).
- All popular content servers are supported with the exception of Microsoft IIS v5.1 (which does not support range requests).
2. Access or Host the DNA JavaScript file
The DNA JavaScript file btdna.js (provided by BitTorrent, Inc.) is an important part of the DNA service. It detects whether DNA is present on the end-user’s computer, and if so it automatically rewrites the URL of the DNA-enabled content so that the DNA service is used rather than just the HTTP infrastructure. The latest version of the DNA JavaScript file is always hosted at:
http://btdna.bittorrent.com/btdna.jsThe DNA JavaScript file can be remotely invoked at this location or alternatively it can be hosted anywhere else accessible from within the host website infrastructure.
If you choose to host a copy of the btdna.js file yourself you must be prepared to update it to keep up with any updates to the btdna.js software.
3. Load the DNA JavaScript file
Each HTML page containing objects to be accelerated by DNA must load the JavaScript file btdna.js. This should be loaded from inside the HTML header. For example:
<head>
<script type="text/javascript" src="http://btdna.bittorrent.com/btdna.js"></script>
</head>The DNA JavaScript file is used to check for the presence of DNA on an end-user’s computer when that end user is looking at a page which is DNA enabled. In case DNA is present, the DNA JavaScript file will automatically rewrite the URL to communicate with the DNA client using the DNA Proxy API. (More details about the DNA Proxy API are described in the integration guide “Advanced Integration” section). In case DNA is not present on an end-user’s computer there are no changes made and the end-user will be able to get the content as usual.
4a. Use the DNA JavaScript API within the HTML on the page
At it’s most basic level, the BitTorrent DNA service is controlled through the DNA Proxy API by passing specially-formed URLs (which conform to the DNA Proxy API) to the DNA port on localhost. The DNA Javascript API handles all the administrative details of forming URLs and passing them into the DNA Proxy API, combining everything into a single, function call, btdna().
Specify the Download (min_rate_data) Service:
DNA is invoked for a piece of content on a page by modifying the URL which points to the actual content – the modification is performed automatically by enclosing the URL inside a function call to btdna.js and including some parameters. The simplest modification is as follows:
btdna({url:'http://my/own/file', service:'min_rate_data'})This will detect the presence of DNA on the end user’s computer and will return a rewritten URL which uses DNA to access the content using the DNA Download (‘min rate data’) service. If DNA is not available the URL will not be rewritten and the end-user will get the content directly from the server as normal.
(NOTE: in case the service: parameter is not specified, DNA will default to download the file using the standard DNA Download service unless the MIME type or file extension suggests that it is a stream-able file, in which case the DNA Streaming service will be used.)
Specify the Quality of Service (qos) Parameter for the Download Service:
For the DNA Download service the qos: parameter should be set. Quality of service is defined as the minimum acceptable download speed for downloads in bytes-per-second.
(NOTE – this is not bits per second – there are 8 bits for every byte, and 1024 bytes in a kilobyte etc.).
Setting the qos: parameter is achieved as follows:
btdna({url:'http://my/own/url', qos:50000, service:’min_rate_data’})This rewrites the given URL, setting qos to a positive whole integer value, in this case 50,000.
Setting a quality of service of 1 byte-per-second will result in the maximum possible bytes being pulled from the peer network. DNA will pull everything it can from the peer network and will only pull from the HTTP server to ensure that it can maintain a minimum data rate of (in this case) 1 byte-per-second. In this scenario, if there are no peers available, the download may take a long time. This may not matter if the end-user is not expected to be actively watching a download (e.g. in the case of background downloads.)
Setting a quality of service at a higher value (e.g. 100,000 bytes-per-second (i.e. 800 kilobits-per-second)) will cause DNA to pull everything it can from the peer network but fall back on the HTTP server if necessary to maintain a minimum data rate of 100,000 bytes-per-second. This type of setting may be important if the end-user is expected to be actively watching a download (e.g. in the case of foreground or user-visible downloads).
Setting a quality of service at 0 is a special setting which is essentially the same as setting it to an infinitely large amount. The behavior of DNA in this scenario is to pull data from the server and from peers as quickly as possible in unison. In practice the “offload” (peer-network-delivered bytes) will usually be lower in this scenario although DNA will always retain a small amount of bandwidth for attempting to obtain data from the peer network. In cases where peers can deliver faster than a server, those peers will be preferred over the server.
In the case that no quality of service value is specified, DNA will apply a qos value of 0 (which will eliminate any expected impact to the end-user experience but may sacrifice the level of offload).
Combine multiple HTTP sources of the same file (e.g. multiple CDNs):
In cases where the same content is available from several different sources (e.g. more than one server or CDN), the different URLs that point to that piece of content should be associated together as follows:
btdna({url:['http://my/own/object', 'http://another/url/for/the/same/object']})This will rewrite the given URLs joining them in an equivalence class.
(NOTE: in DNA Downloads service each client will only make one http connection, so if more than one origin URL is specified then one of them is randomly chosen to fulfill the request.)
Additional DNA JavaScript API Parameters:
Additional DNA parameters can be passed using the JavaScript API to tune the service. Any DNA parameter (a full list is presented in the Advanced Integration section) may be passed to the Javascript API in the manner described, and multiple parameters may be passed at once, so long as they are separated by commas.
Working demos with example code can be seen at the following locations:
| DNA Download Integration: Example Code using btdna.js |
|---|
| http://www.bittorrent.com/dna/integtest |
4b. (alternate method) Add class="btdna" to <a> tags within the HTML on the page
As an alternative to using the JavaScript function call btdna(), another option is to add the attribute class="btdna" to <a> tags. In the case that DNA is present, the DNA JavaScript file will automatically rewrite, in all <a> tags where class="btdna", the target URL (defined by href attribute) to communicate with the DNA client using the DNA Proxy API. In the case that DNA is not present on an end-user’s computer there are no changes made and the end-user will be able to get the content as usual.
Given this method does not allow setting of additional JavaScript parameters such as service: or qos: , DNA will use the default settings for all such parameters. Specifically it will download the file using a qosvalue of 0, and using the standard DNA Download service unless the MIME type or file extension suggests that it is a stream-able file, in which case the DNA Streaming service will be used.
