File Sharing API for Unity SDK

You can upload and share files up to 5 MB on PubNub. Common uses include sharing images in chat apps and documents in healthcare.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

Send file​

Upload the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, SendFile internally calls the PublishFileMessage method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

For details on the method that publishes the file message, see Publish file message.

Method(s)​

1pubnub.SendFile()
2 .Channel(string)
3 .File(string|byte[])
4 .Texture(Texture2D | RenderTexture)
5 .FileName(string)
6 .Ttl(int)
7 .ShouldStore(bool)
8 .Message(string)
9 .Meta(Dictionary<string, object>)
10 .CustomMessageType(string)
11 .Execute(System.Action<PNFileUploadResult, PNStatus>)
required
Channel required#
Type: string
Channel for the file.
File#
Type: string or byte[]
Full path of the file with file name or an array of bytes.
When using an array of bytes, you must set FileName.
Texture#
Type: Texture2D or RenderTexture
An instance of a Texture object. When you send a Texture, a Message with its size and format is added automatically.
FileName#
Type: string
Name of the file to send. You can use it to override the default file name.
TTL#
Type: int
How long the message should be stored in the channel's storage.
ShouldStore#
Type: bool
Whether to store the published file message in the channel's history.
Message#
Type: string
Message which should be sent along with file to specified channel.
Meta#
Type: Dictionary<string, object>
Dictionary<string, object> with values which should be used by PubNub service to filter file messages.
CustomMessageType#
Type: string
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.
Execute required#
Type: System.Action
System.Action of type PNFileUploadResult.
ExecuteAsync#
Type: None
Returns Task<PNResult<PNFileUploadResult>>.
Deprecated parameter

The CipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass CipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Sample code​

1

Response​

1{
2 "Timetoken":15957709330808500,
3 "FileId":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
4 "FileName":"cat_picture.jpg"
5}

Returns​

The SendFile() operation returns a PNResult<PNFileUploadResult> which contains the following properties:

Property NameTypeDescription
ResultPNFileUploadResultReturns a PNFileUploadResult object.
StatusPNStatusReturns a PNStatus object.

PNFileUploadResult contains the following properties:

Property NameTypeDescription
TimetokenlongReturns a PNFileUploadResult object.
FileIdstringReturns the ID of the file.
FileNamestringReturns the name of the file.

Other examples​

Send file with push notification​

Trigger push notifications when sharing files

To send mobile push notifications when sharing a file, include pn_apns (for iOS) and/or pn_fcm (for Android) payloads in the message parameter of the SendFile method.

When PubNub detects these reserved keys, it automatically forwards the push notification to the appropriate push service (APNs or FCM) for all devices registered on the channel.

1var message = new MobilePushHelper()
2 .PushTypeSupport(new [] { PNPushType.APNS2, PNPushType.FCM })
3 .Title("New File")
4 .Body("Check out this file!")
5 .Apns2Data(new List<Apns2Data>()
6 {
7 new ()
8 {
9 targets = new List<PushTarget>()
10 {
11 new ()
12 {
13 environment = Environment.Production,
14 topic = "com.yourapp.bundleid"
15 }
show all 25 lines

For more details on push notification payload structure, see the iOS Push and Android Push documentation. To prevent the sender from receiving their own push notification, add their device token to excluded_devices in the pn_push targets.

List channel files​

Retrieve a list of files uploaded to a channel.

Method(s)​

1pubnub.ListFiles()
2 .Channel(string)
3 .Limit(int)
4 .Next(string)
5 .QueryParam(Dictionary<string, object>)
6 .Execute(System.Action<PNListFilesResult, PNStatus>)
required
Channel required#
Type: string
Default: no default
Channel to get list of files.
Limit#
Type: int
Default: 100
Number of files to return.
Next#
Type: string
Default: no default
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
QueryParam#
Type: Dictionary<string, object>
Default: no default
Dictionary object to pass name/value pairs as query string params with PubNub URL request for debug purpose.
Execute required#
Type: System.Action
Default: no default
System.Action of type PNListFilesResult.
ExecuteAsync#
Type: None
Default: no default
Returns Task<PNResult<PNListFilesResult>>.

Sample code​

1

Response​

1{
2 "FilesList":[
3 {
4 "Name":"cat_picture.jpg",
5 "Id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
6 "Size":25778,
7 "Created":"2020-07-26T13:42:06Z"
8 }],
9 "Count":1,
10 "Next":null
11}

Returns​

Returns PNResult<PNListFilesResult>.

Property NameTypeDescription
ResultPNListFilesResultReturns a PNListFilesResult object.
StatusPNStatusReturns a PNStatus object.

PNListFilesResult fields:

Property NameTypeDescription
FilesListlist<PNFileResult>List of channel files.
CountintNumber of files returned.
NextstringRandom string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

PNFileResult fields:

Property NameTypeDescription
NamestringName of the file.
IdstringID of the file.
SizeintSize of the file.
CreatedstringCreate date of the file.

Get file URL​

Generate a URL to download a file from the target channel.

Method(s)​

1pubnub.GetFileUrl()
2 .Channel(string)
3 .FileId(string)
4 .FileName(string)
5 .Execute(System.Action<PNFileUrlResult, PNStatus>)
required
Channel required#
Type: string
Name of channel within which file with name has been uploaded.
FileId required#
Type: string
Unique file identifier which has been assigned during file upload.
FileName required#
Type: string
Name under which uploaded file is stored for channel.
Execute required#
Type: System.Action
System.Action of type PNFileUrlResult.
ExecuteAsync#
Type: None
Returns Task<PNResult<PNFileUrlResult>>.

Sample code​

1

Returns​

Returns PNResult<PNFileUrlResult>.

Property NameTypeDescription
ResultPNFileUrlResultReturns a PNFileUrlResult object.
StatusPNStatusReturns a PNStatus object.

PNFileUrlResult fields:

Property NameTypeDescription
UrlstringURL which can be used to download remote file with specified name and identifier.

Download file​

Download a file from the specified channel.

Method(s)​

1pubnub.DownloadFile()
2 .Channel(string)
3 .FileId(string)
4 .FileName(string)
5 .Execute(System.Action<PNDownloadFileResult, PNStatus>)
required
Channel required#
Type: string
Name of channel within which file with name has been uploaded.
FileId required#
Type: string
Unique file identifier which has been assigned during file upload.
FileName required#
Type: string
Name under which uploaded file is stored for channel.
Execute required#
Type: System.Action
System.Action of type PNDownloadFileResult.
ExecuteAsync#
Type: None
Returns Task<PNResult<PNDownloadFileResult>>.
Deprecated parameter

The CipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass CipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Sample code​

1

Response​

1{
2 //Call fileDownloadResult.SaveFileToLocal(<destination path>) to save file.
3 "FileBytes":"/9j/4AAQSkZJRgABAQEAkACQAAD/4RCERXhpZgAATU0AKgAAAAgABAE7AAIAAAAGAAAISodpAAQAAAABAAAIUJydAAEAAAA...<truncated due to lengthy data",
4 "FileName":"cat_picture.jpg"
5}

Returns​

Returns PNResult<PNDownloadFileResult>.

Property NameTypeDescription
ResultPNDownloadFileResultReturns a PNDownloadFileResult object.
StatusPNStatusReturns a PNStatus object.

PNDownloadFileResult fields:

Property NameTypeDescription
FileBytesbyte[]Bytes of the downloaded file.
FileNamestringName of the downloaded file.
SaveFileToLocal(string)n/aCall with a destination path to save the file locally.

Delete file​

Delete a file from the specified channel.

Method(s)​

1pubnub.DeleteFile()
2 .Channel(string)
3 .FileId(string)
4 .FileName(string)
5 .Execute(System.Action<PNDeleteFileResult, PNStatus>)
required
Channel required#
Type: string
Name of channel within which file with name needs to be deleted.
FileId required#
Type: string
Unique file identifier of the file to be deleted.
FileName required#
Type: string
Name of the file to be deleted from the channel.
Execute required#
Type: System.Action
System.Action of type PNDeleteFileResult.
ExecuteAsync#
Type: None
Returns Task<PNResult<PNDeleteFileResult>>.

Sample code​

1

Response​

1{}

Returns​

Returns PNResult<PNDeleteFileResult>.

Property NameTypeDescription
ResultPNDeleteFileResultReturns a PNDeleteFileResult object.
StatusPNStatusReturns a PNStatus object.

PNDeleteFileResult is empty.

Publish file message​

Publish the uploaded file message to a specified channel.

This method is called internally by SendFile as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when SendFile fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use PublishFileMessage to manually resend a file message to a channel without repeating the upload step.

Method(s)​

1pubnub.PublishFileMessage()
2 .Channel(string)
3 .FileId(string)
4 .FileName(string)
5 .Message(object)
6 .Meta(Dictionary<string, object>)
7 .ShouldStore(bool)
8 .CustomMessageType(string)
9 .Execute(System.Action<PNPublishFileMessageResult, PNStatus>)
required
Channel required#
Type: string
Default: no default
Name of channel to publish file message
FileId required#
Type: string
Default: no default
Unique file identifier of the file.
FileName required#
Type: string
Default: no default
Name of the file.
Message#
Type: string
Default: no default
The payload.
Meta#
Type: string
Default: no default
Metadata object which can be used with the filtering ability.
ShouldStore#
Type: bool
Default: true
Whether to store the message in history.
CustomMessageType#
Type: string
Default: no default
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.
Execute required#
Type: System.Action
Default: no default
System.Action of type PNPublishFileMessageResult.
ExecuteAsync#
Type: None
Default: no default
Returns Task<PNResult<PNPublishFileMessageResult>>.

Sample code​

1

Response​

1{
2 "Timetoken":15957738720237858
3}

Returns​

Returns PNResult<PNPublishFileMessageResult>.

Property NameTypeDescription
ResultPNPublishFileMessageResultReturns a PNPublishFileMessageResult object.
StatusPNStatusReturns a PNStatus object.

PNPublishFileMessageResult contains the following properties:

Property NameTypeDescription
TimetokenlongReturns a long representation of the timetoken when the message was published.

Was this page useful?

Last updated on