Skip to content

MASV JavaScript Web Uploader

Getting Started

Include the uploader library in your page:

<script src="https://massive.app/lib/masv-uploader-beta.min.js"></script>

Create a new instance of it and pass the parameters :

const uploader = new MASV.Uploader(
    packageID, 
    packageToken, 
    apiURL,
);

Where:

  • pakageID is the ID of the package for which the files will be uploaded. This can be obtained by creating a portal package or a team package
  • packageToken is the authorized JWT token for the package, also obtained at time of package creation
  • apiURL is the base URL of MASV API, which should be https://api.massive.app for production

Usage

Initialization

After you instantiate the uploader object, you need to create a listener to handle various upload event callbacks.

uploader.setListener(listener)

Here's the listener's interface definition (in TypeScript, for clarity):

interface MasvListener {
    onProgress: (completed: number, total: number, speed: {
        instant: number;
        average: number;
        moving: number;
    }) =>  void;
    onFileComplete: (file: MasvFile) =>  void;
    onRetry: (reason: Error) =>  void;
    onComplete: () =>  void;
    onError: (err: Error) =>  void;
}

Where:

  • onProgress is called when upload progress occurs (bytes getting uploaded). It reports completed bytes so far, and total byte size of all files. The speed object determined the calculated upload speed in various forms (all in bits per second): instant for the instant speed since the last onProgress call, average speed is the rolling average of upload speed since the beginning of the upload and moving speed is the moving average of upload speed in the last 30 seconds.
  • onFileComplete is called whenever one of the supplied files finishes uploading, it indicates which file object was completed
  • onRetry is called when the uploader retries any request (for example a file chunk upload) due to an error that is deemed retriable by the uploader (for example, a network error or a 5xx server error)
  • onComplete is called when the upload is completed and the package have been finalized
  • onError is called when an unrecoverable error has occurred and the upload halted (for example, a 401 server error is considered unrecoverable)

Please note that the progress is not necessarily monotonic. As the uploader processes chunks, it reports the progress inclusive of chunks that are in flight. In the event of a retry due to a retriable error, it resets the progress to the previous value prior to uploading the chunk since chunks have to be uploaded entirely. It's up to you to handle this behaviour in the UI.

Uploading files

after you have setup the callback listener it's just a matter of passing the list of files you want to upload:

uploader.upload(files:MasvFile[])

Each MasvFile object must conform to the following interface (in TypeScript, for clarity):

interface  MasvFile {
    id: string;
    file: File; // JS File object, which can be obtained from a file input for example
    path: string;
}

Cancelling

Warning

A cancelled upload cannot be resumed.

An active upload can be cancelled by calling

uploader.terminate()