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.

 


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.

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 Hosting

 


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

×