Upload Widget: Methods

Displays the widget and waits for the user to select their file(s), and then returns the result.

Signature

function open(configuration?: UploadWidgetConfig): Promise<Array<UploadWidgetResult>>

Parameters

See: Configuration

Result promise

See: Result

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.
uploader.open({ maxFileCount: 1 });

Gets the URL for an uploaded file (takes a filePath and returns a URL).

We recommend saving filePath values instead of fileUrl values to your database, as this allows you to change other parts of the URL in future (such as the URL's domain name — if you upgrade to a custom domain — or the "file transformation" part of the URL).

Signature

function url(filePath: string, urlParams?: { auth?: boolean; transformation?: string; }): string

Result

"https://upcdn.io/abc1234/thumbnail/uploads/example.jpg"

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.
const fileUrl  = uploader.url("/uploads/example.jpg", { transformation: "thumbnail" });
//    fileUrl  = "https://upcdn.io/abc1234/thumbnail/uploads/example.jpg"

Call this method once at the start of your application — after the user has been authenticated — if the user needs to download private files.

This will start a cookie-based auth session to allow users to download private files directly via the URL. For example, if your webpage contains <img> elements that reference private image files, you can use beginAuthSession to allow these images to render in the current browser tab, while keeping them inaccessible to unauthorized users.

Internally, the method works by periodically requesting JWT access tokens from your API, which are then stored in an Upload CDN cookie to allow downloads of the files granted by the JWT.

Signature

function beginAuthSession(authUrl: string, authHeaders: () => Promise<Record<string, string>>): Promise<void>

Prerequisites

Implement a backend API endpoint that generates a public/private key JWT, with its payload structured as an UploadJwt, and its public key certificate added to your JWT Certificates.

See: Authorization

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.
uploader.beginAuthSession(
  "https://your-api-domain.example.com/auth",
  async () => ({
    Authorization: "SomeAuthorizationHeaderRequiredByYourApi"
  })
);

Ends an authorized browser session, preventing the user from downloading further private files.

Signature

function endAuthSession(): Promise<void>

Prerequisites

Can only be called after a successful call to beginAuthSession.

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.

// User signs in:
uploader.beginAuthSession(
  "https://your-api-domain.example.com/auth",
  async () => ({
    Authorization: "SomeAuthorizationHeaderRequiredByYourApi"
  })
);

// User downloads files:
// ...

// User signs out:
uploader.endAuthSession();