Skip to content

MASV Web Uploader

For browser-based integration where you want to upload files from your own web app to MASV, you can use the MASV Web Uploader. It simplifies file uploading by taking care of the complexities of dealing with the MASV API while giving you the flexibility of designing your own file picker and integration workflows.

Setting up

First, install the MASV Web Uploader in your project:

yarn add @masvio/uploader

Next, for this example your web app needs the sub-domain of a Portal:

  1. Login or Signup with MASV.
  2. Do one of these:

Remember to copy or save the Portal's sub-domain. For example, if the complete domain of your Portal is example1234.portal.massive.io, then your Portal's sub-domain is example1234.

This example uploads to a Portal, but you can also upload to a MASV Team.

Adding Web Uploader to your web app

Get your Portal's ID

This helper function requests a Portal's ID with the MASV API.

async function fetchPortalID(subdomain){
    const request = await fetch(
        `https://api.massive.app/v1/subdomains/portals/${subdomain}`
    );

    const { id } = await request.json();
    return id;
}

Create a package

This function creates a MASV package for a portal.

async function createPackage(portalID) {    
    const request = await fetch(`https://api.massive.app/v1/portals/${portalID}/packages`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
          name: "enter a package name here",
          sender: "enter your email here",
          description: "enter a package description here"
      }),
    });

    const { id, access_token } = await request.json();

    return { id, access_token };
}

Instantiate the Uploader

Remember to replace SUBDOMAIN with your Portal's sub-domain.

import { Uploader } from "@masvio/uploader";

const portalID = await fetchPortalID("SUBDOMAIN");
const {id, access_token} = await createPackage(portalID);

const uploader = new Uploader(id, access_token, 'https://api.massive.app');

Retrieve Files

An HTML input with the type attribute set to file will have a property titled files in the DOM.

<input type="file" id="fileInput" />

const fileInput = document.getElementById("fileInput");
let files = [];

fileInput.addEventListener("input", (event) => {
    for (let file of fileInput.files) {
        files.push({
            id: 'test ID',
            file,
            path: '',
        });
    }
});

Add the Files

These files will be added to the package you created earlier. Once the first file has been processed, it will immediately begin uploading. 

uploader.addFiles(...files);

Note

Unlike the MASV API and MASV Agent, there is no need to start or finalize the upload explicitly with the Web Uploader.

API Reference

Constructor

new Uploader(packageID, packageToken, apiURL)
Param Type Description
packageID string 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 string The authorized JWT token for the package, also obtained at the time of package creation.
apiURL string The base URL of the MASV API. For production, this should be https://api.massive.app.

Methods

addFiles

Upload one or multiple MasvFiles

uploader.addFiles({
    id,
    file,
    path,
});

An array of files can be uploaded using the rest syntax

const files = [/** Files Go Here */];

upload.addFiles(...files);
Param Type Description
file MasvFile A decorated File object
MasvFile
Param Type Description
id string An ID for the upload
file File The Javascript File object representing the file on your local system
path string The path of the file to retain folder structure on the other side

pause

Pause the upload

uploader.pause();

start

Start the upload. Required only if the uploader was paused manually.

uploader.start();

cancel

Cancel the upload

uploader.cancel();

finalize

Finalize the upload 

uploader.finalize();

getPerformanceStats

Get statistics about the uploaders performance

uploader.getPerformanceStats();

terminate

Terminate the uploader and all it's workers

uploader.terminate();

Events

Listen to a specific event

uploader.on(Uploader.UploaderEvents.Progress, (event) => {
    console.log(event);
});

Delegate a listener for all events

const handlers = {
    [Uploader.UploaderEvents.Progress]: (e) => {
        console.log(e);
    },
    [Uploader.UploaderEvents.Finished]: (e) => {
        console.log(e);
    },
}

uploader.on('emit', (event) => {
    if (event.name in handlers) {
        handlers[event.name](event);
    }
});

Event Payloads

Property Type Description
event string One of the possible event names listed below
time number A unix timestamp at the time the event was fired
target object The module of the uploader that fired the original event
data object An object representing data relevant to the event

Uploader Events

Name String Description
Created uploader:create The uploader is first initialized
Start upload:start The uploader begins uploading data, either at the beginning of the upload, or after a pause
FileQueued upload:file_queued A file is queued for upload
Progress upload:progress Data is successfully sent
Chunk upload:chunk A chunk of a file has finished uploading
File upload:file All of a files chunks have finished uploading
Finalize upload:finalize The uploader has finalized a file upload
Error upload:error Any error from the upload requests
Finished upload:finish The uploader has finished uploading all of the files
Abort upload:abort An upload is aborted, usually by pausing the uploader
Retry upload:retry The uploader must retry a request, usually due to a network issue
File Unreadable upload:file_unreadable The browser is unable to read one of the files in the package
Stalled upload:stalled No upload progress has been reported in at least 1 minute