cordova-plugin-save-to-device

Cordova plugin for saving images and videos to Android and iOS devices.

Supported source types: remote URL, file:// URI, content:// URI, absolute file path, Blob, data: URL, and raw base64 data.

Install

cordova plugin add <path-to-cordova-plugin-save-to-device>

JavaScript API

The plugin is exposed as cordova.plugins.saveToDevice.

saveImage(input[, success, error])

Saves an image to the user's device.

saveVideo(input[, success, error])

Saves a video to the user's device.

saveMedia(input[, success, error])

Saves media when you either pass mediaType or provide a URI with a recognizable file extension.

Input

You can pass a remote URL or file URI directly:

await cordova.plugins.saveToDevice.saveImage("https://your-domain.com/path/to/image.jpg");

You can also pass a Blob directly:

const blob = await fetch("https://your-domain.com/path/to/image.jpg").then((response) => response.blob());
await cordova.plugins.saveToDevice.saveImage(blob);

Or use an options object:

cordova.plugins.saveToDevice.saveMedia({
  uri: "file:///path/to/video.mp4",
  mediaType: "video",
  fileName: "saved-video.mp4",
  album: "AppMedia"
});

Supported options:

• uri optional source path, file://, content://, absolute path, remote http(s) URL, or a data: URL
• blob optional Blob source, normalized in JavaScript before calling native code
• dataUrl optional base64 data: URL such as data:image/png;base64,...
• base64Data optional raw base64 string without the data: prefix
• mediaType optional for saveMedia, must be "image" or "video"
• mimeType optional, recommended when using raw base64Data
• fileName optional output filename
• album optional Android subfolder under Pictures or Movies

If you omit callbacks, each method returns a Promise.

Example

async function downloadAndSave() {
  const result = await cordova.plugins.saveToDevice.saveImage({
    uri: "https://your-domain.com/path/to/photo.jpg",
    fileName: "saved-photo.jpg",
    album: "AppMedia"
  });

  console.log("Saved:", result);
}

await cordova.plugins.saveToDevice.saveImage({
  dataUrl: "data:image/png;base64,<your-base64-data>"
});

await cordova.plugins.saveToDevice.saveVideo({
  base64Data: "<your-base64-data>",
  mimeType: "video/mp4",
  fileName: "saved-video.mp4"
});

For a drop-in Cordova test page, see the examples/ folder in this repository.

config.xml Notes

This plugin does not inject iOS privacy strings or Android storage permissions into your app manifest. Your app should define them in its own config.xml so they can be managed alongside your other permissions and won't conflict with hosted builders such as VoltBuilder.

Example:

<platform name="android">
    <config-file target="AndroidManifest.xml" parent="/*">
        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
    </config-file>
</platform>

<platform name="ios">
    <edit-config file="*-Info.plist" mode="merge" target="NSPhotoLibraryAddUsageDescription">
        <string>This app saves images and videos to your photo library.</string>
    </edit-config>
    <edit-config file="*-Info.plist" mode="merge" target="NSPhotoLibraryUsageDescription">
        <string>This app needs photo library access to save media.</string>
    </edit-config>
    <edit-config file="*-Info.plist" mode="merge" target="NSUserTrackingUsageDescription">
        <string>This identifier will be used to deliver personalized ads to you.</string>
    </edit-config>
</platform>

If you plan to download remote media over HTTPS in a Cordova app, make sure your app allows the hosts you use. A typical setup is:

<access origin="https://your-domain.com" />
<allow-navigation href="https://your-domain.com/*" />

If you rely on cleartext HTTP URLs on Android, you may also need app-level network security configuration. Prefer HTTPS.

Limitations

• Large video Blob, data: URL, and raw base64 inputs can be memory-intensive. Prefer remote URLs or local file URIs for larger videos.
• iOS saves media into the system photo library but does not currently support choosing a custom album.
• Remote URL support depends on the device being able to reach the host and on your Cordova app allowing that host.

Platform notes

Android

• Android 10 and newer save through MediaStore
• Android 9 and older require your app to declare WRITE_EXTERNAL_STORAGE in config.xml
• album maps to a subfolder inside Pictures for images and Movies for videos

iOS

• Saves into the system photo library via Photos.framework
• iOS supports local file paths and downloadable http(s) URLs
• Animated GIF inputs are saved as GIF data so animation is preserved
• album is currently ignored on iOS
• Your app must provide NSPhotoLibraryAddUsageDescription and NSPhotoLibraryUsageDescription in config.xml

Return value

Android resolves with:

{
  "success": true,
  "uri": "content://media/external/images/media/12345",
  "fileName": "photo.jpg",
  "mediaType": "image"
}

iOS resolves with:

{
  "success": true,
  "assetId": "A1B2C3D4-...",
  "mediaType": "image"
}