Getting Started with the Web Uploader

The MASV Web Uploader SDK lets you embed high-speed file uploads directly in your web application. It handles chunking, retries, and progress tracking so you can focus on your integration workflow rather than the complexities of the MASV API.

This guide walks you through installation, Portal resolution, Package creation, uploader initialization, file selection, and upload execution.

Prerequisites

Before you begin, make sure you have:

A MASV account — sign up or log in
A Portal with a known subdomain (e.g., example1234 from example1234.portal.massive.io). Create a new Portal or use an existing one.
A web application with a JavaScript bundler (Webpack, Vite, etc.)

Installation

Install the MASV Web Uploader package:

npm install @masvio/uploader

Or with Yarn:

yarn add @masvio/uploader

Resolve the Portal ID

The Web Uploader sends files to a MASV Package, which belongs to a Portal. Use the Portal’s subdomain to look up its ID via the Portals API:

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

Create a Package

Create a Package on the Portal to hold the uploaded files:

async function createPackage(portalID) {
  const response = await fetch(
    `https://api.massive.app/v1/portals/${portalID}/packages`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "My Upload",
        sender: "[email protected]",
        description: "Files uploaded via Web Uploader",
      }),
    }
  );

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

The response provides a Package id and an access_token — both are required to initialize the uploader.

Initialize the Uploader

Import the Uploader class and create an instance with the Package credentials:

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

const portalID = await fetchPortalID("your-subdomain");
const { id, access_token } = await createPackage(portalID);

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

See the API Reference for full constructor details.

Select files

Use a standard HTML file input to let users pick files:

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

Collect the selected files into the format the uploader expects:

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

fileInput.addEventListener("input", () => {
  files = Array.from(fileInput.files).map((file, index) => ({
    id: `file-${index}`,
    file,
    path: "",
  }));
});

Each file object requires an id (a unique string), the file (a browser File object), and a path (used to preserve folder structure on the receiving end).

Upload the files

Pass the selected files to the uploader. Uploading begins immediately once the first file is processed:

uploader.addFiles(...files);

Listen for events

Track upload progress and completion by subscribing to events:

uploader.on(Uploader.UploaderEvents.Progress, (event) => {
  console.log("Upload progress:", event.data);
});

uploader.on(Uploader.UploaderEvents.Finished, (event) => {
  console.log("Upload complete:", event.data);
});

uploader.on(Uploader.UploaderEvents.Error, (event) => {
  console.error("Upload error:", event.data);
});

See the API Reference — Events for the full list of events and their payloads.

Complete example

Here’s a minimal end-to-end integration:

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

// 1. Resolve Portal
const portalID = await fetchPortalID("your-subdomain");

// 2. Create Package
const { id, access_token } = await createPackage(portalID);

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

// 4. Listen for events
uploader.on(Uploader.UploaderEvents.Progress, (event) => {
  console.log("Progress:", event.data);
});

uploader.on(Uploader.UploaderEvents.Finished, (event) => {
  console.log("Upload finished");
});

uploader.on(Uploader.UploaderEvents.Error, (event) => {
  console.error("Error:", event.data);
});

// 5. Add files (from a file input)
const fileInput = document.getElementById("fileInput");
fileInput.addEventListener("input", () => {
  const files = Array.from(fileInput.files).map((file, i) => ({
    id: `file-${i}`,
    file,
    path: "",
  }));
  uploader.addFiles(...files);
});

Next steps

API Reference — Full documentation of the constructor, methods, and events.
Upload with Web Uploader tutorial — A step-by-step Quick Start tutorial.
MASV API — Uploads — Understand the underlying upload lifecycle.
MASV API — Portals — Learn more about Portal configuration and management.