---
name: "downloadFile"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.3.2" }
  - { name: "@ray-js/ray", version: "0.3.23" }
platform:
  - "iOS"
  - "Android"
async: true
title: "p2p.downloadFile - P2P Download file"
---

## downloadFile

> [VERSION] BaseKit >= 2.3.2 | @ray-js/ray >= 0.3.23

> [PLATFORM] iOS, Android

> ⚡ **Supports Promise** — Returns a Promise when success / fail / complete callbacks are omitted.

### Description

Download a file resource to local storage. The client directly initiates an HTTPS GET request and returns the file’s local temporary path (local path). The maximum file size per download is 200 MB. Read the related notes before use. Note: Specify an appropriate Content-Type header in the server response to ensure the client handles the file type correctly.

### Parameters

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `url` | `string` | Yes | - | `2.3.2` | URL of the resource to download |
| `header` | `Record<string, string>` | No | - | `2.3.2` | HTTP request headers; Referer cannot be set |
| `timeout` | `number` | No | - | `2.3.2` | Timeout in milliseconds |
| `filePath` | `string` | No | - | `2.3.2` | Path to store the downloaded file (local path) |
| `complete` | `() => void` | No | - | - | Completion callback (executed on both success and failure) |
| `success` | `(params: Object) => void` ↓see below | No | - | - | Callback on successful API call |
| `fail` | `(params: Object) => void` ↓see below | No | - | - | Failure callback |

#### success callback parameters

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `tempFilePath` | `string` | `3.2.6` | Temporary file path (local path). Returned when filePath is not provided; the downloaded file is stored in a temporary file |
| `filePath` | `string` | `3.2.6` | User file path (local path). Returned when filePath is provided; identical to the given filePath |
| `statusCode` | `number` | `3.2.6` | HTTP status code returned by the developer server |
| `profile` | `Profile` | `3.2.6` | Debug information during the request |

#### fail callback parameters

| Property | Type | Description |
| --- | --- | --- |
| `errorMsg` | `string` | Error message |
| `errorCode` | `string \| number` | Error code |
| `innerError` | `Object` | Error extension |

##### fail(params).innerError properties

| Property | Type | Description |
| --- | --- | --- |
| `errorCode` | `string \| number` | Error extension code |
| `errorMsg` | `string` | Error extension message |


### Referenced Types

##### `interface` Profile

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `redirectStart` | `number` | `3.2.6` | Time when the first HTTP redirect occurred. Only counted for redirects within the same domain; otherwise 0 |
| `redirectEnd` | `number` | `3.2.6` | Time when the last HTTP redirect finished. Only counted for redirects within the same domain; otherwise 0 |
| `fetchStart` | `number` | `3.2.6` | Time when the component became ready to fetch the resource via HTTP, before checking the local cache |
| `domainLookupStart` | `number` | `3.2.6` | Time when DNS lookup started; if a local cache (no DNS lookup) or a persistent connection is used, equals fetchStart |
| `domainLookupEnd` | `number` | `3.2.6` | Time when DNS lookup completed; if a local cache (no DNS lookup) or a persistent connection is used, equals fetchStart |
| `connectStart` | `number` | `3.2.6` | Time when the HTTP (TCP) connection started to be established; if a persistent connection, equals fetchStart. Note: if an error occurred at the transport layer and the connection was re-established, this shows the start time of the new connection |
| `connectEnd` | `number` | `3.2.6` | Time when the HTTP (TCP) connection finished establishing (handshake completed); if a persistent connection, equals fetchStart. Note: if an error occurred at the transport layer and the connection was re-established, this shows the completion time of the new connection. Note: handshake completion includes secure connection established and SOCKS authorization passed |
| `SSLconnectionStart` | `number` | `3.2.6` | Time when the SSL connection started; if not a secure connection, the value is 0 |
| `SSLconnectionEnd` | `number` | `3.2.6` | Time when the SSL connection completed; if not a secure connection, the value is 0 |
| `requestStart` | `number` | `3.2.6` | Time when the HTTP request started reading the actual document (after the connection was established), including reads from the local cache. On reconnect after a connection error, this also shows the time the new connection was established |
| `requestEnd` | `number` | `3.2.6` | Time when reading the actual document ended |
| `responseStart` | `number` | `3.2.6` | Time when HTTP started receiving the response (first byte), including local cache reads |
| `responseEnd` | `number` | `3.2.6` | Time when the entire HTTP response was received (last byte), including local cache reads |
| `rtt` | `number` | `3.2.6` | Real-time RTT during this request’s connection |
| `estimate_nettype` | `string` | `3.2.6` | Estimated network status: slow 2g/2g/3g/4g |
| `httpRttEstimate` | `number` | `3.2.6` | Protocol layer’s estimated current network RTT based on multiple requests (for reference only) |
| `transportRttEstimate` | `number` | `3.2.6` | Transport layer’s estimated current network RTT based on multiple requests (for reference only) |
| `downstreamThroughputKbpsEstimate` | `number` | `3.2.6` | Estimated download kbps of the current network |
| `throughputKbps` | `number` | `3.2.6` | Actual download kbps of the current network |
| `peerIP` | `string` | `3.2.6` | IP address of the current request |
| `port` | `number` | `3.2.6` | Port of the current request |
| `socketReused` | `boolean` | `3.2.6` | Whether the connection is reused |
| `sendBytesCount` | `number` | `3.2.6` | Bytes sent |
| `receivedBytedCount` | `number` | `3.2.6` | Bytes received |


### Examples

#### Demo

```tsx
import { downloadFile } from '@ray-js/ray'

downloadFile({
  url: "https://airtake-public-data-1254153901.cos.ap-shanghai.myqcloud.com/ttttestfile/test_video.mp4",
  success: data => {
    console.log(data);
  },
  fail: error => {
    console.error(error);
  },
});
```