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:

Login or Signup with MASV.
Do one of these:
- Create a new Portal to upload to.
- You can also use an existing Portal.

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 Transfer Agent, there is no need to finalize the package 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`.

addFiles

Upload a collection of MasvFiles

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

Param	Type	Description
files	array	An array of MasvFiles

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

start

Start the upload

uploader.start();

pause

Pause the upload

uploader.pause();

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 has to retry a request, usually due to a network issue