File Sharing

In addition to messages and signals, PubNub also allows users to upload and share files.

The most common scenarios where you may need to share files are in social apps to share images or in medical apps to share medical records. You can upload and share videos, images, or documents of up to 5 MB in size each.

Configuration​

To use File Sharing, you must have it enabled and configured on a chosen app's keyset in the Admin Portal.

Public Admin Portal demo

Want to browse through the Admin Portal without creating an account? Explore it through the Public Demo that shows examples of most PubNub features for transport and logistics use case.

By default, Admin Portal prompts you to enable File Sharing on every new keyset (unless you select Choose later for Region during keyset creation).

All testing keysets have US East and 7 days selected as the default storage region and retention time for which your app's files will remain in storage before being deleted.

File Sharing in Admin Portal

OptionDescription
Bucket Region
Geographical region where your file data is stored and managed.

Consider aligning the file retention period with the retention you set for Message Persistence to store messages and files for the same period of time.
Retention
How long you'd like to save your files for. For free accounts, you can set it to 1 day or 7 days. Limits are higher for paid accounts.

Send Files​

Sending a file is a lot like publishing a message; you must specify the channel on which to send the file and provide the actual file. You can also optionally include some text to use as a caption for the file.

You can also encrypt files using AES-256 Encryption. To send such files, you must either have a cipher key defined in your initial client configuration or specify the cipher key parameter directly in each request. Other clients will have to provide this key when downloading the file to decrypt the content successfully.

The code below sends the file cat_picture.jpg of the custom type file-message on the channel my_channel. Note that not all SDKs yet support sending messages with a custom message type.

// web
const input = document.querySelector('input[file]');

input.addEventListener('change', async () => {
  const file = input.files[0];

  const result = await pubnub.sendFile({
    channel: 'my_channel',
    file: file,
    customMessageType: 'file-message'
  });
});

// Node.js
import fs from 'fs';
show all 36 lines

Even though you upload and share the files directly from the client, it's the storage service that stores and manages the actual files for each key.

Once the file has been uploaded to the storage service, subscribers of a particular channel receive a file message. With this file message (which contains a description, filename, and file ID) you can use our SDKs to generate a URL to display the file or download the file directly. Refer to Retrieve Files for more information.

Enable the Feature

File Sharing is an optional feature that you must enable by turning on the feature for your keys in the Admin Portal.

File Operations​

Apart from sending files, you can list all files that were sent to a channel or delete a file that has been previously uploaded to the storage service. Much like with regular messages, you can also search through historical file messages using the Message Persistence API if you enabled Message Persistence on your API key. The information returned by the Message Persistence API allows you to either display the file in the browser or download it.

Refer to the File Sharing section in the SDK documentation to learn more about operations on files.

Receive Files​

In order to receive a file, the receiving client should be listening to an event of type file, and should subscribe to a channel in which the file is being sent. There is no need to subscribe any differently to a channel for receiving a file.

Retrieve Files​

Retrieving files is a two-step process accomplished using the History API and File Sharing-related SDK methods. To retrieve a file:

  1. Get the file message using History API or the listFiles method
  2. Display or download the file using dedicated SDK methods based on the obtained file information.
File URLs

Neither the History API nor the listFiles method returns file URLs. They return file-specific information like the file's name and ID that you need to display or download the file.

When you fetch file messages using History API, the response includes the file details (ID, filename) and a message type of 4 that indicates it's a file message. You can use this information to display or download the file.

Display and Download Files​

Apart from the optional description, a file message contains the ID and name of the file.

As a file message does not contain the file URL, you must use one of the available SDK methods to construct the file URL to either display the file or download it.

The following code returns the URL of the cat_picture.jpg file sent to channel my_channel:

const result = pubnub.getFileUrl({ channel: 'my_channel', id: 'd9515cb7-48a7-41a4-9284-f4bf331bc770', name: 'cat_picture.jpg' });

The response to this call is the file URL which you can use to display the file in the browser.

You need the same set of file information to download the file. The following code downloads the file cat_picture.jpg sent to the channel my_channel:

// web
const file = await pubnub.downloadFile({
  channel: 'my_channel',
  id: '...',
  name: 'cat_picture.jpg',
});

const myImageTag = document.createElement('img');
myImageTag.src = URL.createObjectURL(await file.toFile());

document.body.appendChild(myImageTag);

// Node.js using streams
import fs from 'fs'

show all 38 lines

List Files​

If you're only interested in the actual files and not the file messages (which include the optional description of the uploaded file) that were sent, you can list up to 100 files sent to a particular channel. However, if there are more than 100 files to be returned, the more flag will be present in the response.

The code below returns the name, ID, size, and created timestamp for up to 100 files sent to the channel my_channel:

const result = await pubnub.listFiles({ channel: 'my_channel' });
Last updated on
Related Resources
On this page