react-native-blob-util

Since version 0.8.0, react-native-blob-util automatically determines how to send the request body based on the type and the Content-Type header:

• Form Data: The Content-Type header is ignored. If the body is an Array, the library sets the proper content type for you.
• Binary Data: You can use a BASE64 encoded string or a file path.
  • If Content-Type contains ;BASE64 or application/octet, the body is treated as BASE64 and decoded to binary.
  • Otherwise, if the string starts with ReactNativeBlobUtil-file:// (use ReactNativeBlobUtil.wrap(PATH) to generate this), it uses the file at that URI as the body.
• As-is: To send the body without transformation, use a Content-Type that does not contain ;BASE64 or application/octet.

Important Notes:

• Caching: HTTP requests use cache by default. To disable it, add the header 'Cache-Control': 'no-store'.
• Chunked Encoding: Chunked transfer encoding is disabled by default since 0.9.4. To use it, explicitly set the Transfer-Encoding header to Chunked.

For Android 5.0 or lower, you must manually add permissions to your AndroidManifest.xml to access external storage.

To automatically add Android permissions during linking (for projects using react-native link), use the RNFB_ANDROID_PERMISSIONS=true environment variable.

```sh
# Automatically add permissions during linking
RNFB_ANDROID_PERMISSIONS=true react-native react-native-blob-util

Manual Manifest additions for Android 5.0 or lower:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />

Additional requirements:

• Android Download Manager: Add <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/> to your intent filter.
• wifiOnly flag: Add <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />.

For large downloads on Android, use the system DownloadManager. This provides native progress bars and notifications and handles the task via the OS.

Requirements & Limitations:

• Requires useDownloadManager: true in the addAndroidDownloads config.
• Only supports the GET method (request body is ignored).
• fileCache and path in the top-level config() are ignored because DownloadManager stores files in external storage.
• You must specify a path in addAndroidDownloads to avoid permission/parsing issues when installing APKs.

ReactNativeBlobUtil
        .config({
            addAndroidDownloads: {
                useDownloadManager: true,
                notification: true,
                title: 'Download Success',
                description: 'An image file.',
                mime: 'image/png',
                mediaScannable: true,
            }
        })
        .fetch('GET', 'http://example.com/file/somefile')
        .then((resp) => {
            console.log('Downloaded to:', resp.path())
        })

When using fileCache: true or the path option with fetch, files are stored in the file system and are not automatically removed. You must manage them manually to prevent storage bloat.

Removal Methods

1. res.flush(): Call this on a ReactNativeBlobUtilResponse object to remove the specific cached file associated with that response.
2. fs.unlink(path): Remove a file by its specific path.
3. session.dispose(): Group multiple requests into a session and remove all files in that session at once.

Using Sessions

You can assign a response to a session using res.session('name') or configure a session globally in .config({ session: 'name' }). You can also manually manage sessions via ReactNativeBlobUtil.session('name') to add, remove, or list file paths.

// Using sessions to group and dispose of files
ReactNativeBlobUtil.config({ session: 'my-session', fileCache: true })
    .fetch('GET', 'http://example.com/file')
    .then((res) => {
        // Files are now part of 'my-session'
    });

// Later, clear all files in that session
ReactNativeBlobUtil.session('my-session').dispose().then(() => {
    console.log('Session cleared');
});

To post form data containing both text and files, pass an Array as the body in fetch(). Each element in the array is an object with the following properties:

• name: The field name.
• data: The value (string, BASE64, or a wrapped file path).
• filename (optional): If present, the element is treated as a file. If absent, it is sent as a UTF-8 string.
• type (optional): Custom MIME type (e.g., 'image/png').

To upload a file from storage within a multipart request, wrap the path using ReactNativeBlobUtil.wrap(PATH).

ReactNativeBlobUtil.fetch('POST', 'http://www.example.com/upload-form', {
    'Content-Type': 'multipart/form-data',
}, [
    // File from BASE64
    {name: 'avatar', filename: 'avatar.png', data: binaryDataInBase64},
    // File from storage
    {name: 'avatar-foo', filename: 'avatar-foo.png', type: 'image/foo', data: ReactNativeBlobUtil.wrap(path_to_a_file)},
    // Plain text field
    {name: 'name', data: 'user'},
    // JSON field
    { name: 'info', data: JSON.stringify({ mail: 'test@example.com' }) }
]).then((resp) => {
    // ...
});

You can specify how data is transformed whenever the library reads from or writes to storage (e.g., for encryption). To use a file transformer, you must implement the platform-specific interface:

• iOS: ReactNativeBlobUtilFileTransformer.h
• Android: ReactNativeBlobUtilFileTransformer.java

Once implemented, set the transformer during app startup.

The transformer applies to:

• Reading a file from the file system.
• Writing a file into the file system.
• HTTP responses downloaded directly to storage.

// Android: Set in MainApplication.java
public class MainApplication extends Application implements ReactApplication {
    @Override
    public void onCreate() {
       ReactNativeBlobUtilFileTransformer.sharedFileTransformer = new MyCustomEncryptor();
    }
}

// iOS: Set in AppDelegate.m
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [ReactNativeBlobUtilFileTransformer setFileTransformer: MyCustomEncryptor.new];
    return YES;
}