rn-fetch-blob/README.md

react-native-fetch-blob

v0.5.0 Work In Progress README.md

Upload, and download files with customzable headers. Supports binary response/request data, upload/download progress, also has file stream, and CRUD APIs which enables you process file content in JS context. (such as display image data, and process string or data).

If you’re getting into trouble with image or file server that requires specific fields in the header, or you’re having problem with fetch API when sending/receiving binary data, you might try this module as well.

See [fetch] Does fetch with blob() marshal data across the bridge? for the reason why I made this module.

In latest version (v0.5.0), you can either upload or download files simply using a file path. We’ve also introduced fs APIs for access files, and file stream API that helps you read/write files (especially for large ones), see Examples bellow.

This module implements native methods, supports both Android (uses awesome native library AsyncHttpClient) and IOS.

TOC

• Installation
• Examples
  • Download file
  • Upload file
  • Multipart/form upload
  • Upload/Download progress
  • File access
  • File stream
  • Manage cached files
• API
  • fetch
  • session
  • base64
  • fs
• Development

Installation

Install package from npm

npm install --save react-native-fetch-blob

Link package using rnpm

rnpm link

Android Access Permission to External storage (Optional)

If you’re going to access external storage (say, SD card storage), you might have to add the following line to AndroidManifetst.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.rnfetchblobtest"
    android:versionCode="1"
    android:versionName="1.0">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
+   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />                                               
+   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />                                              

    ...

Usage

import RNFetchBlob from 'react-native-fetch-blob'

Download example : Fetch files that needs authorization token

// send http request in a new thread (using native code)
RNFetchBlob.fetch('GET', 'http://www.example.com/images/img1.png', {
    Authorization : 'Bearer access-token...',
    // more headers  ..
  })
  // when response status code is 200
  .then((res) => {
    // the conversion is done in native code
    let base64Str = res.base64()
    // the following conversions are done in js, it's SYNC
    let text = res.text()
    let json = res.json()

  })
  // Status code is not 200
  .catch((errorMessage, statusCode) => {
    // error handling
  })

Download to storage directly

The simplest way is give a fileCach option to config, and set it to true. This will let the incoming response data stored in a temporary path wihout any file extension.

These files won’t be removed automatically, please refer to Cache File Management

RNFetchBlob
  .config({
    // add this option that makes response data to be stored as a file,
    // this is much more performant.
    fileCache : true,
  })
  .fetch('GET', 'http://www.example.com/file/example.zip', {
    some headers ..
  })
  .then((res) => {
    // the temp file path
    console.log('The file saved to ', res.path())
  })

Set Temp File Extension

Sometimes you might need a file extension for some reason. For instance, when using file path as source of Image component, the path should end with something like .png or .jpg, you can do this by add appendExt option to config.

RNFetchBlob
  .config({
    fileCache : true,
    // by adding this option, the temp files will have a file extension
    appendExt : 'png'
  })
  .fetch('GET', 'http://www.example.com/file/example.zip', {
    some headers ..
  })
  .then((res) => {
    // the temp file path with file extension `png`
    console.log('The file saved to ', res.path())
    // Beware that when using a file path as Image source on Android,
    // you must prepend "file://"" before the file path
    imageView = <Image source={{ uri : Platform.OS === 'android' ? 'file://' : '' + res.path() }}/>
  })

Use Specific File Path

If you prefer a specific path rather than random generated one, you can use path option. We’ve added a getSystemDirs API in v0.5.0 that lists several common used directories.

RNFetchBlob.getSystemDirs().then((dirs) => {
  RNFetchBlob
    .config({
      // response data will be saved to this path if it has access right.
      path : dirs.DocumentDir + '/path-to-file.anything'
    })
    .fetch('GET', 'http://www.example.com/file/example.zip', {
      //some headers ..
    })
    .then((res) => {
      // the path should be dirs.DocumentDir + 'path-to-file.anything'
      console.log('The file saved to ', res.path())
    })
})

These files won’t be removed automatically, please refer to Cache File Management

Upload example : Dropbox files-upload API

react-native-fetch-blob will convert the base64 string in body to binary format using native API, this process will be done in a new thread, so it’s async.

RNFetchBlob.fetch('POST', 'https://content.dropboxapi.com/2/files/upload', {
    Authorization : "Bearer access-token...",
    'Dropbox-API-Arg': JSON.stringify({
      path : '/img-from-react-native.png',
      mode : 'add',
      autorename : true,
      mute : false
    }),
    'Content-Type' : 'application/octet-stream',
    // here's the body you're going to send, should be a BASE64 encoded string 
    // (you can use "base64" APIs to make one). 
    // The data will be converted to "byte array"(say, blob) before request sent.  
  }, base64ImageString)
  .then((res) => {
    console.log(res.text())
  })
  .catch((err) => {
    // error handling ..
  })

Upload a file from storage

If you’re going to use a file request body, just push the path with prefix RNFetchBlob-file://. (We’re planning to add an API to customize this prefix)

RNFetchBlob.fetch('POST', 'https://content.dropboxapi.com/2/files/upload', {
    // dropbox upload headers
    Authorization : "Bearer access-token...",
    'Dropbox-API-Arg': JSON.stringify({
      path : '/img-from-react-native.png',
      mode : 'add',
      autorename : true,
      mute : false
    }),
    'Content-Type' : 'application/octet-stream',
    // Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://` when the data comes from a file.
  }, 'RNFetchBlob-file://' + PATH_TO_THE_FILE)
  .then((res) => {
    console.log(res.text())
  })
  .catch((err) => {
    // error handling ..
  })

Multipart/form-data example : Post form data with file and data

In version >= 0.3.0 you can also post files with form data, just put an array in body, with elements have property name, data, and filename(optional).

Elements have property filename will be transformed into binary format, otherwise it turns into utf8 string.

  RNFetchBlob.fetch('POST', 'http://www.example.com/upload-form', {
    Authorization : "Bearer access-token",
    otherHeader : "foo",
    'Content-Type' : 'multipart/form-data',
  }, [
    // element with property `filename` will be transformed into `file` in form data
    { name : 'avatar', filename : 'avatar.png', data: binaryDataInBase64},
    // elements without property `filename` will be sent as plain text
    { name : 'name', data : 'user'},
    { name : 'info', data : JSON.stringify({
      mail : 'example@example.com',
      tel : '12345678'
    })},
  ]).then((resp) => {
    // ...
  }).catch((err) => {
    // ...
  })

What if you want to upload a file in some field ? Just like upload a file from storage example, change data to path of the file with a prefix RNFetchBlob-file:// (this feature is only available for version >= v0.5.0)

  RNFetchBlob.fetch('POST', 'http://www.example.com/upload-form', {
    Authorization : "Bearer access-token",
    otherHeader : "foo",
    // this is required, otherwise it won't be process as a multipart/form-data request
    'Content-Type' : 'multipart/form-data',
  }, [
    // append field data from file path
    { 
      name : 'avatar',
      filename : 'avatar.png',
      // Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://` when the data comes from a file path
      data: 'RNFetchBlob-file://' + PATH_TO_THE_FILE
    },
    // elements without property `filename` will be sent as plain text
    { name : 'name', data : 'user'},
    { name : 'info', data : JSON.stringify({
      mail : 'example@example.com',
      tel : '12345678'
    })},
  ]).then((resp) => {
    // ...
  }).catch((err) => {
    // ...
  })

Upload/Download progress

In version >= 0.4.2 it is possible to know the upload/download progress.

  RNFetchBlob.fetch('POST', 'http://www.example.com/upload', {
      ... some headers,
      'Content-Type' : 'octet-stream'
    }, base64DataString)
    .progress((received, total) => {
        console.log('progress', received / total)
    })
    .then((resp) => {
      // ...
    })
    .catch((err) => {
      // ...
    })

File Access

File access APIs were made when developing v0.5.0, which helping us write tests, and was not planned to be a part of this module. However I realized that, it’s hard to find a great solution to manage cached files, every one who use this moudle may need those APIs for there cases.

Here’s the list of fs APIs

• getSystemDirs
• createFile
• readStream
• writeStream
• unlink
• mkdir
• ls
• mv
• cp
• exists
• isDir

File Stream

In v0.5.0 we’ve added writeStream and readStream in fs, which allows you read/write data from file path. This API creates a file stream, rather than a BASE64 encoded data of the file, it’s handy when deal with large files.

But there’re some differences on usage of readStream and writeStream. When calling readStream method, the file stream is opened immediately, and start to read data.

let data = ''
let stream = RNFetchBlob.readStream(
    // encoding, should be one of `base64`, `utf8`
    'base64',
    // file path
    PATH_TO_THE_FILE,
    // (optional) buffer size, default to 4096 (4095 for BASE64 encoded data)
    // when reading file in BASE64 encoding, buffer size must be multiples of 3.
    4095)
stream.onData((chunk) => {
  data += chunk
})
stream.onError((err) => {
  console.log('oops', err)
})
stream.onEnd(() => {  
  <Image source={{ uri : 'data:image/png,base64' + data }}
})

Cache File Management

When using fileCache or path options along with fetch API, response data will automatically stored into file system. The files will NOT removed unless you unlink it. There’re several ways to remove the files

  // remove file using RNFetchblobResponse.flush() object method
  RNFetchblob.config({
      fileCache : true
    })
    .fetch('GET', 'http://example.com/download/file')
    .then((res) => {
      // remove cached file from storage
      res.flush()
    })

  // remove file by specifying a path
  RNFetchBlob.unlink('some-file-path').then(() => {
    // ...
  })

You can also group the requests by using session API, and use dispose to remove them all when needed.

  RNFetchblob.config({
    fileCache : true
  })
  .fetch('GET', 'http://example.com/download/file')
  .then((res) => {
    // set session of a response
    res.session('foo')
  })  

  RNFetchblob.config({
    // you can also set session beforehand
    session : 'foo'
    fileCache : true
  })
  .fetch('GET', 'http://example.com/download/file')
  .then((res) => {
    // ...
  })  

  // or put an existing file path to the session
  RNFetchBlob.session('foo').add('some-file-path')
  // remove a file path from the session
  RNFetchBlob.session('foo').remove('some-file-path')
  // list paths of a session
  RNFetchBlob.session('foo').list()
  // remove all files in a session
  RNFetchBlob.session('foo').dispose().then(() => { ... })

API

config(options:RNFetchBlobConfig):fetch

TODO

fetch(method, url, headers, body):Promise<FetchBlobResponse>

Send a HTTP request uses given headers and body, and return a Promise.

method:string Required

HTTP request method, can be one of get, post, delete, and put, case-insensitive.

url:string Required

HTTP request destination url.

headers:object (Optional)

Headers of HTTP request, value of headers should be stringified, if you’re uploading binary files, content-type should be application/octet-stream or multipart/form-data(see examples above).

body:string | Array<Object> (Optional)

Body of the HTTP request, body can either be a BASE64 string, or an array contains object elements, each element have 2 required property name, and data, and 1 optional property filename, once filename is set, content in data property will be consider as BASE64 string that will be converted into byte array later. When body is a base64 string , this string will be converted into byte array in native code, and the request body will be sent as application/octet-stream.

fetch(...).progress(eventListener):Promise<FetchBlobResponse> added in 0.4.2

Register on progress event handler for a fetch request.

eventListener:(sendOrReceivedBytes:number, totalBytes:number)

A function that triggers when there’s data received/sent, first argument is the number of sent/received bytes, and second argument is expected total bytes number.

session(name:string):RNFetchBlobSession

TODO

base64

A helper object simply uses base-64 for decode and encode BASE64 data.

RNFetchBlob.base64.encode(data)
RNFetchBlob.base64.decode(data)

fs

TODO

Types

RNFetchBlobResponse

When fetch success, it resolve a FetchBlobResponse object as first argument. FetchBlobResponse object has the following methods (these method are synchronous, so you might take quite a performance impact if the file is big)

base64():string

returns base64 string of response data (done in native context)

json():object

returns json parsed object (done in js context)

text():string

returns decoded base64 string (done in js context)

path():string

returns file path if the response data is cached in file

session(name:string):RNFetchBlobSession

when the response data is cached in a file, this method adds the file into the session. The following usages are equivalent.

RNFetchBlob.session('session-name').add(resp.path())
// or
resp.session('session-name')

RNFetchBlobSession

TODO

RNFetchBlobStream

TODO

Major Changes

Version
~0.3.0	Upload/Download octet-stream and form-data
0.4.0	Add base-64 encode/decode library and API
0.4.1	Fixe upload form-data missing file extension problem on Android
0.4.2	Supports upload/download progress
0.5.0	Upload/download with direct access to file storage, and also added file access APIs

TODOs

• Customizable Multipart MIME type
• Improvement of file cache management API

Development

If you’re interested in hacking this module, check our development guide, there might be some helpful information. Please feel free to make a PR or file an issue.