Introduction

Aspera Connect Client allows you to develop a native feel to your web applications while utilizing the Aspera file-transfer capabilities.  Through the JavaScript API you can offer a seamless user experience from initial installation of the plugin to use of the web application.

You can learn more about Connect Client and how to integrate it into your own web application we invite you to view the Intro to Connect Video.

Connect Client's JavaScript API allows you to control the look and feel as well as the workflow of your web applications allowing the end user to easily initiate transfers, view progress of transfers, and control their transfers.  It also allows you to fine tune your user's experience by allowing event handling and seamless integration with the Connect Plugin.  

You are able to utilize the Connect Plugin's native dialogs or hide it to offer your user a natural experience in your web applications.

The Connect Client API is easy to setup and this guide is designed to help get you started.  To begin, browse the guide in the Components section to learn how to integrate fasp into your own web applications.

Note: Connect Client 2.7 (Aspera Web) is no longer supported.

 


Components

Getting Started

Connect Client offers many components to help you utilize Aspera file-transfer capabilities into your own web applications.  This guide will show you the basic of how Connect Client works and how you can utilize it in your own application.  The Connect Client JavaScript API allows you to build a fully branded and custom web application using your preferred framework, CMS or backend language.  The JavaScript handles connecting the user to the plugin which allows for the use of Aspera file-transfer.

 


Files

You can easily add Connect Client to your existing web application or website.  In order to get started, it is important to understand the different files that make up Connect Client.

A typical Connect Client setup has the following files:

Connect Files

Depending on whether you are using Connect 3.6 or 3.5 and earlier will define what Connect files you will need to link to your application.  If you are using Connect 3.6 you will need to link asperaweb-4.js and connectinstaller-4.js (location in the v4 directory of your hosting location).  If you are using connect 3.5 and earlier you will need to include asperaweb-2.js, connectversion.js and connectinstaller-2.js.

application.js

This JavaScript file is where all of your application's needed code goes, you can also use your own JavaScript file if you would rather not separate the Aspera JavaScript from your website JavaScript.  Using the Components and Sample Code options on the left you will notice different application.js examples depending on what your application is doing.  This is the main file that handles starting transfers and interacting with the DOM for transfer statuses. Depending on your preferred frameworks you can use any tools within here to update the DOM (for example jQuery).

application.html

Throughout the examples we use a plain HTML page for showing how to utilize the tool.  However, you can easily add the parts you need to a CMS or into any web application.  The HTML examples show the frontend markup that the user sees; for DOM manipulations you will want to add IDs and Classes to your elements to target them from your application.js file.  You can customize and utilize any frontend framework or template that you wish.

CSS Files

You can use any CSS files that you wish.  Since you can utilize your own class and ID names for your elements you can name them anyway you like to avoid conflict.  The Connect Client API is designed to make integrating into your own application easy and you can use your current stylesheets or create new ones for the Connect elements you wish to utilize.

 


File Download

Downloading files to the client using Connect Client can easily be setup.  In your application.js file you need to include the handler for downloading files.

This handler can be attached to fileControls and can accept numerous conditions to customize the experience for your end user.  You can attach this to a button or link to trigger the download as needed for your application. An example of this handler is below.  The connectSetting can be added to handle how the Connect Plugin behaves for the user.

 

 


File Upload

Uploading files from the client using Connect Client can easily be integrated into your website.  In your application.js file you simply need to include the handler for uploading files.

This handler can be attached to fileControls and can accept numerous conditions to customize the experience for your end user.  You can attach this to a button or link to trigger the upload file selection dialog as needed for your application.  When a user triggers the event to start the upload process, the asperaWeb.showSelectFileDialog should be called with a success call to the fileControls.uploadFiles that you define. It is important to note that for security, the showSelectFileDialog must be used.  The connectSetting can be added to handle how the Connect Plugin behaves for the user.

An example of this handler is below. 

 

 


 


File Filters in Selection and Save Dialogs

File filters are used in file selection/save dialogs and allow the client to show only filtered files based on an extensions defined by the application or set by the user. These functions are:

  • AW.Connect#showSaveFileDialog(callbacks[, options])
  • AW.Connect#showSelectFileDialog(callbacks[, options])

The example below will open a file selection dialog with only files with .txt and .png file extensions shown.

 

 


File preview

The Connect Client API offers the ability to read 64-bit encoded data (up to 50MB) from a file path. This feature allows developers to create and display a preview of a selected file, an example of this is seen below.

 

The following showPreview function demonstrates how to do use AW.Connect#readAsArrayBuffer(path):

 

 


Drag and Drop

Drag and Drop can enable your application to offer users a simplified method for uploading files.  Drag and Drop allows the user to simply drag a file from their operating system to the web application and the handlers will read in the needed data provided about the file to initiate the upload.

Since Connect Client 3.4.2 you can use multiple drop zones for file uploads and utilize the drop events 'dropex', 'dragenter', 'dragleave' to customize your user's experience by providing feedback of successful user actions.

An example of the JavaScript for handling Drag and Drop as well as utilizing the drop events is seen below.

 

JavaScript initSession Error

When using the Aspera Connect Javascript API  you may see an error that states the AWConnect initSession() function does not exist (typically manifested as p.initSession is not a function) the cause is likely because you are trying to instantiate and initialize the AWConnect object with Drag and Drop support within a hidden div. Most browsers do not allow plugins to be instantiated within a div that is hidden, because of this the container (div) that you specify for the plugin drop target must be visible on the screen. Some known workarounds include giving the div a 1x1px size to make it visible on the screen but too small to affect the layout.

 


Authentication

Authentication can be implemented to authenticate to a server.

Authentication is handled in the application.js file of your Connect Client application.

Required Files

Resources

 Customize Code

Source Code for HTML file (application.html)

 
 

Source Code for JavaScript file (application.js)

 
 

Code Generation

To generate the code on this page to your needs, please fill out the fields below.

Powered by ChronoForms - ChronoEngine.com

×

 


Transfer Controls

You can display active and completed transfers within the browser without having to use the GUI of the Connect plugin.

After calling the initSessions with the application ID (if null, all transfers are retrieved) you can call your own getTransferEvents function that will loop through all of the transfers that meet your conditions and can print them on the screen (or be handled by your own code).

An example of a basic setup in the application.js file is provided below.

 

 


Transfer Specifications (transferSpec)

transferSpec contains all of the specifications that you define for your transfer.  These specs are passed to the server which uses them for generating the return JSON that allows the action to take place.  Below are some examples of the most commonly used setups.  For a list of all possible values please see the API docs.

For security reasons, source paths submitted to the Connect API for upload transfers (AW4.Connect#startTransfer) must be obtained either using the showSelectFileDialog/showSelectFolderDialogcalls or setDragDropTargets calls. That's the way to make sure that users are aware of the transfer happening between their host and the remote server.

Similarly, destination paths for downloads must follow the same approach if they are absolute paths (ie. if "use_absolute_destination_path" is set to true in connect_spec JSON).

Note: Aspera Connect does not have an overwrite boolean-type option (which would allow the user to change the overwrite policy), because each new transfer request overwrites the pre-existing files by default. However, you can back up existing files before they are overwritten; add the value, "save-before-overwrite": true to the JSON for the transferSpec before starting the transfer. See Download of Existing Files for additional details.

Download a File to the Default Directory

Download a file to the default directory set in the Connect Plugin settings (user defined in settings, or default from installer)

 

Download a File to a User Defined Directory

Download a file to the directory location that is chosen by the user. You can pass this value in after asking the user. To force the destination directory you also need to use the aspera_connect_settings and enable (true) use_absolute_destination_path. This setting is only used for download operations.

 

Download a File from a Remote Server which Authorizes Downloads by Token

Tokens are used to have an Aspera server authorize a transfer operation for a given user regarding a given path. The token has to be generated by either the Aspera server or by an entity that has the same knowledge as the Aspera server.

To help generate this token a tool is provided with the server. This tool (astokengen or astokengen.exe) is located in the /bin folder of the Aspera server's root directory. To use this tool you need to specify the following parameters: type (-d), user (-u), and path (-p). For example:

astokengen -u svcAspera -d -p c:/source/file.txt

The command should give you a token which you can place in transferSpec as "token":"value" where value is the value that the operation above generated. You can also have a token generation handled by a web service, which can return the token when you make an AJAX call to it and then you can use that token in your transferSpec.

 

Fallback to HTTP or HTTPS if SSH Fails

You can fallback to HTTP or HTTPS in the event that SSH fails. In order to enable this you must add http_fallback parameter and set it to true and define the port (default is 80 for HTTP). If you need to use HTTPS you should also enable the cipher parameter and set it to aes-128 and use your HTTPS port.  You will also need to enable this in the aspera.conf file on the server

 

An example of the setting used in aspera.conf is below. For more information please refer to the Aspera Server Documentation.

 

 


 


Connect 3.6

Connect 3.6

With Connect 3.6, there are new features available that you may want to consider taking advantage of. To utilize these new features Connect 3.6 includes a slightly modified version of the asperaweb JavaScript. Whereas the previous versions of the asperaweb JavaScript were named "asperaweb-2.js", the asperaweb JavaScript that includes the new features is in a file named "asperaweb-4.js". In Connect 3.6, web aplication developers have the option of using the older asperaweb-2.js API which maintains complete backwards compatability for existing applications.

NPAPI

The asperaweb-2.js API relies on plugin support for NPAPI plugins - used in Connect 3.5 and 3.6 for non Chrome browsers. The latest version of Google Chrome has eliminated default support for NPAPI. To that end, if you choose to continue to use the asperaweb-2.js API and not update your application(s), your Chrome users will need to proactively enable NPAPI support. Details on how to do this may be found in this Aspera support article. The differences between the asperaweb-2.js (Connect 3.5) and the asperaweb-4.js (Connect 3.6) API is outlined below. Even though the asperaweb-2.js API is backwards compatible with your existing Aspera Connect powered web applications, it is good practice to ensure that your current web application(s) still work with Connect 3.6 before upgrading your live environment.

Installation

Specifying and detecting the presence of Aspera Connect within your web application has been greatly simplified in the Connect 3.6. Installation of Connect for 3.6 is now done with a download and install in all cases. The Aspera Connect 3.6 API (asperaweb-4.js) provides a way for you to specify a minimum version of Connect and be notified of installed support asynchronously. The recommended way to ensure that an appropriate version of Connect is installed is included below in the following code snippet (Note that the results are now delivered through event notification.):

 

Connect 3.6.6 Changes

Changes have been made in Connect 3.6.6 to remove the insecure content warnings that were previously surfaced in most modern browsers. The Connect Client Plugin now communicates with the Connect client code via HTTPS instead of HTTP. Connect 3.6.6 is fully backward compatible and does not introduce any API changes. This update also includes support for Microsoft Edge, enhanced security measures to comply with Apple security best practices, and numerous bug fixes.  To see the full list of changes please refer to the Connect 3.6.6 Release Notes.

How to Update

If you reference the Aspera hosted version of Connect, your users will automatically be updated to Connect 3.6 once it is made public. Please reference the changes below for details.

If you are hosting your own copy of Connect and would like to take advantage of the latest asperaweb-4.js API features, you will need update your hosted files to reference the files located in the latest Connect 3.6 Server release. If self-hosting Aspera Connect, please see the note on CORS support in the Connect Server SDK section.

Maintaining Connect 3.5

If you do not wish to update to the latest version of Connect you will need to host your own version of Connect 3.5. If you do this, we recommend that you inform your Chrome users that they need to enable NPAPI plugin support as indicated above.

Drag and Drop

Drag and Drop can be implemented in your app using Connect 3.6.1. Connect 3.6.1 Drag and Drop utilized HTML5 drag and drop interactions to allow for simple implementation in your web app and is supported in all modern browsers. It is important to note that Internet Explorer 10 and up currently only support dragging of files and not directories. Internet Explorer 8 and 9 do not support Connect 3.6.1 Drag and Drop since they do not support HTML5. If you need to support these browsers you can utilize asperaweb-2.js drag and drop to work within Connect 3.6.1 SDK.

Below is an example of how to implement Drag and Drop using Connect 3.6.1:

 

Detecting User Events

Additional event types have been added to help developers ensure a great end user experience by detecting events related to the Connect Banner and changing the app appropriately. You can now detect when the Connect Banner has been removed or loaded allowing you to keep track if a user closes the banner without running Connect. This allows you to stop the pings for Connect or keep track that the user dismissed to avoid showing it again. To do this you can simply add a listener to the connectInstaller object to detect the event and perform the appropriate action.

The main new events include:

  • AW4.ConnectInstaller.EVENT.REFRESH_PAGE (IFRAME Refreshed)
  • AW4.ConnectInstaller.EVENT.IFRAME_REMOVED (IFRAME Dismissed)
  • AW4.ConnectInstaller.EVENT.IFRAME_LOADED (IFRAME loaded)
  • AW4.ConnectInstaller.EVENT.DOWNLOAD_CONNECT (Download/Update button clicked)

An example of detecting the IFRAME_REMOVED event is seen below

 

Stopping Connect Detection

When trying to launch Connect the browser will ping the local machine to see when Connect is available (waiting for a response). Once Connect is loaded and responds the application continues. However, if the user does not wish for Connect to run or does not have it installed you may want to stop your web app from pinging. You can use the stop() function on the AW4.Connect object to stop pinging the local machine (which throws a 404 every time there is no response). If you wish to start checking again you can simply call start() on the AW4.Connect object. It is important to note that you should not call start() unless you previously have called stop().

Required Changes

The following table shows the changes from Connect 3.5 to 3.6 that will need to be changed if currently being used in your application.

Function/Parameter Change
initSession Now Required
version Now Asynchronous
addEventListener [, ignoreOld] Not Supported
getAllTransfers Now Asynchronous
modifyTransfers Now Asynchronous
readAsArrayBuffer Now Asynchronous
removeTransfer Now Asynchronous
resumeTransfer Now Asynchronous
showSaveFileDialog ExtendedInfo is no longer in Options, returns ExtendedInfo in the dataTransfer object.
showSelectFileDialog ExtendedInfo is no longer in Options, returns ExtendedInfo in the dataTransfer object.
showSelectFolderDialog ExtendedInfo is no longer in Options, returns ExtendedInfo in the dataTransfer object.
stopTransfer Now Asynchronous
Drag and Drop Drag and Drop code needs to be updated using the example above

Comparison of Connect 3.6 and 3.5

The following table shows in details the main changes between Connect 3.5 and 3.6

Function 3.5 Parameter 3.6 Parameter
new AW.Connect()    
  connectLaunchWaitTimeoutMs connectLaunchWaitTimeoutMs
  containerId containerId
  dropAllowDirectories  
  dropAllowMultiple  
  dropMode  
  dropUploadUrl  
  height  
  width  
  id id
  image  
  imageCover  
    sdkLocation
    pollingTime
    minVersion
     
AW.Connect.EVENT    
AW.Connect.STATUS    
AW.Connect.TRANSFER_STATUS    
AW.Connect.DROP_MODE    
addEventListener type,  
  callback  
  [, ignoreOld]  
    type,
    callback
     
authenticate authSpec,  
  callbacks  
    authSpec,
    callbacks
getAllTransfers [iterationToken]  
    callbacks
    [, iterationToken]
getStatus ---  
initSession [applicationId]  
    [applicationId]
modifyTransfer transferId,  
  options  
    transferId,
    options,
    callbacks
readAsArrayBuffer path  
    options,
    callbacks
     
readChunkAsArrayBuffer --- options,
    callbacks
removeEventListener [type]  
  [, callback]  
    [type]
    [, listener]
     
removeTransfer transferId  
    transferId,
    callbacks
resumeTransfer transferId,  
  options  
    transferId,
    options,
    callbacks
setDropTargets selector ---
showAbout   callbacks
showDirectory transferId  
    transferId,
    callbacks
showPreferences   callbacks
showSaveFileDialog callbacks  
  [, options]  
    callbacks
    [, options]
showSelectFileDialog callbacks  
  [, options]  
    callbacks
    [, options]
showSelectFolderDialog callbacks  
  [, options]  
    callbacks
    [, options]
showTransferManager   callbacks
showTransferMonitor transferId  
    transferId,
    callbacks
startTransfer TransferSpec,  
  connectSpecs,  
  callbacks  
    TransferSpec,
    connectSpecs,
    callbacks
startTransfers transferSpecs,  
  callbacks  
    transferSpecs,
    callbacks
stopTransfer transferId  
    transferId,
    callbacks
version   callbacks

 


Connect Hosting

Connect Hosting

Depending on your needs, you can use the Aspera hosted versions to provide your users with the latest Connect SDK and Plugins, or you can host your own.  To host your own you will need to download the desired SDK version below.  Hosting your own versions allows you to fine tune every aspect of the user's experience and help satisfy company policy if applicable.  However, using the Aspera Hosted version is the easiest and quickest way, but if you need to host your own you can easily set it up using the guide below.

If you would like to use the Aspera Hosted version you can simply reference the following scripts in the header of your webpage.  The Aspera version is kept up to date with the most stable release of the SDK and plugins.

Connect 3.6 and Later

Connect 3.5 and Earlier

Download SDK

To get started you will need to download the SDK, this contains all of the files you will need to load on your web server.

Setup Web Server

Now that you have downloaded the SDK version of your choice you need to load it onto a web server; we recommend keeping it separate from your other servers. You can use any server setup and any directory, you just need to reference the JavaScript from your application.

Configure Correct cache-control Headers

To ensure that updates are recognized, your cache-control headers should be configured on your server.  This will allow clients to check whether or not files have been modified while still allowing you to take advantage of cache performance.  You can set this on a per directory basis if needed.

  • Cache-Control: private, must-revalidate
  • Expires: -1
  • Last-Modified: xxxxxxxxxxxxxxxx

Configure MIME Types

To ensure the browser plugin and Connect Installer files are served from your web server, you need to enable the following MIME types to be served from your server.

  • .crx - application/x-chrome-extension
  • .xpi - application/x-xpinstall
  • .jar - application/java-archive
  • .exe - application/octet-stream
  • .msi - application/octet-stream
  • .dmg - application/octet-stream
  • .sh - application/x-sh
  • .zip - application/zip
  • .cab - vnd.ms-cab-compressed

Deploy the SDK

Now that the server is ready, you can deploy the contents of the SDK you downloaded.  We recommend using a folder on your server like /connect/, however, it is up to you how to setup your server's hierarchy and as long as you reference it appropriately in your application it will be fine.  Unzip the archive and move the content to the directory on your web server you choose.  If using a file manager, be sure to check permissions and owner rights for allowing the files to be accessed via the www process.

Configure Web Applications

The server is ready to host your own version of Connect SDK. You now just need to ensure that any web applications you create point to this location.  If you started with one of our samples you can simply replace the "//d3gcli72yxqn2z.cloudfront.net/connect/" with "//yoursite.com/directory/". To reference your own files in your applications, just add the following to the header of your HTML page (replace with your address).

 

 


Sample Code

Upload

A barebones example of a simple upload using Aspera Connect.

Required Files

Live Demo

  Live Demo

Source Code for HTML file (application.html)

 

Source Code for JavaScript File (application.js)

 

 


Download

A barebones example of a simple download using Aspera Connect.

Required Files

Live Demo

  Live Demo

Source Code for HTML file (application.html)

 

Source Code for JavaScript File (application.js)

 

 


Pairs Download

A simple pairs download example. Connect 3.0+ required for client and Enterprise Server/Connect Server 3.1+ required for server.

Required Files

Live Demo

  Live Demo

Source Code for HTML file (application.html)

 

Source Code for JavaScript File (application.js)

 

 


Authentication

You can use basic authentication against an Aspera server to authenticate users to utilize your web application.

You can create a user interface to retrieve the server (or define in code), the user ID, and the password.  You can then use this data to create an authSpec to send to the server to check for authentication.  If authentication is successful the callback success function can handle your user interface to allow the user to complete the operation.  If the user is not authenticated or another error occurs you can define a callback function to display an error message and read data from the returned JSON which may provide insight to why the user was unable to be authenticated.

An example of a basic setup in the application.js file is provided below.

 

 


Transfer Control in Browser

Show active and completed downloads within the web browser. This example uses jQuery UI for graphical elements. This is not required.

Required Files

Live Demo

  Live Demo

Source Code for HTML file (application.html)

 

Source Code for JavaScript File (application.js)

 

 


All-in-One

A complete application that demonstrates installation, single and multi file upload, single and multi file download, progress rendering and transfer control.

This example makes use of jQuery to simplify some of the requests, however, this is not required.

Required Files

Live Demo

  Live Demo

Source Code for HTML file (application.html)

 

Source Code for JavaScript File (application.js)

 

 


General Reference

Transfer Spec Paths

Source Destination pairs are available in Connect Client 3.0+ and need Enterprise Server/Connect Server 3.1+ to work. This feature is not currently supported in HTTP fallback, in the event HTTP fallback is called the destination will be dropped. In general the paths specification follows this format:

 

Its important to note that when specifying a source/destination pair. That the set of these paths must either have a source and a destination or just a source. You cannot mix a path with a source and destination with paths that just contain sources and vice versea (see below for examples). If you require this you must use seperate transferSpecs. For example, the code below is valid:

[{ "source" : "file1", "destination" : "newfile1" },{ "source" : "file2", "destination" : "newfile2" }]

However, this is NOT valid:

[{ "source" : "file1", "destination" : "newfile1" },{ "source" : "file2" }]

Here are some valid cases for reference

Upload a single file into a destination directory

"destination_root": "/data","paths": [  {    "source": "file1"  }]"create_dir" : false|true

Upload a single file with a new name into a destination directory

"destination_root": "/data","paths": [{"source": "file1","destination" : "newfile1"}]

Upload a single directory into a destination directory

"destination_root": "/data","paths": [{"source": "dir1"}]

Upload a single directory with a different name into a destination directory

"destination_root": "/data","paths": [{"source": "dir1"},{"source": "newdir1"}]

Upload multiple files and directories into a destination directory

"destination_root": "/data","paths": [{"source": "dir1""destination" : "newdir1"}]

Upload multiple files with new names into a destination directory

"destination_root": "/data","paths": [{"source": "dir1"},{"source": "newdir1"}]

Download a single file into a destination directory

"destination_root": "/Desktop","paths": [{"source": "file1"}]"create_dir" : false|true

Download a single file with a new name into a destination directory

"destination_root": "/data/newfile1","paths": [{"source": "file1"}]

Download a single directory into a destination directory

"destination_root": "/data","paths": [{"source": "dir1"}]

Download a single directory with a different name into a destination directory

"destination_root": "/data/newdir1","paths": [{"source": "dir1"}]

Download multiple files and directories into a destination directory

"destination_root": "/data","paths": [{"source": "file1"},{"source": "dir1"}]

Download multiple files with new names into a destination directory

"destination_root": "/data","paths": [{"source": "file1""destination" : "newfile1"},...]

 


Transfer Statuses

The meanings of transfer statuses.

Status
Description
initiating
Transfer request accepted and transfer starting.
running
Transfer in progress.
retrying
Transfer restarting after encountering a retry-able error.
cancelled
Transfer stopped.
completed
Transfer completed.
failed
Transfer stopped after encountering a non retry-able error. Error code and error description are included when this status occurs.
queued
Transfer queued and will begin after running transfers have completed. Note that this status only occurs when the "Maximum concurrent transfers" setting is configured by the user.
removed
Transfer removed through the Connect UI.

 


Language Localization

As of Connect 3.0+, language localization is now supported.  Connect uses the user's Operating System language preferences and automatically changes the language accordingly.  As of this time there is no way to programmatically switch the language.

Language Localization Coverage

Language Connect Version Required
English 1.0+
French-France 3.0+
Spanish-Spain 3.0+
Chinese-Simplified 3.0+
Japanese 3.0+

 


Download Destination Location

Downloads can have their content's destination specified in the transfer_spec JSON using either of these:

"paths":[{"source":"sourcePath","destination":"destinationPath"}]
"paths":[{"source":"sourcePath","destination":"absoluteDestinationPath"}]

This download destination location is relative to the default download directory set by the user in the Connect Plugin preference (by default this is the Desktop)

For example, the code below will download the files 'tinyfile0001' and 'tinyfile0002' into a directory named 'temp' under the default download directory

 

The API also allows the ability to download contents to a destination outside of the default directory. In order to override the default path settings, the "use_absolute_destination_path" on the connect_spec JSON must be set to true. An example connect_spec is below:

var connect_spec = {  "allow_dialogs" : false,  "use_absolute_destination_path" : true};

To protect users against unauthorized access to their file system, this setting will require the user be prompted to choose the destination location. You can prompt the user for a destination using the API method AW.Connect.showSelectFolderDialog(callback[,options]). The path selected by the user can be used to set the destination_root in the transfer_spec JSON. NOTE: Using "use_absolute_destination_path" on the connect_spec JSON set to true without prompting the user for selecting the download destination will result in a transfer failure.

 


API Documentation

 


Video player

Video

×