@capawesome/capacitor-cloudinary

Unofficial Capacitor plugin for Cloudinary SDK.[^1]

Features

Capacitor Cloudinary allows you to use the native Cloudinary SDKs to upload files directly from the filesystem without going through the WebView.

• 🔋 Supports Android, iOS and the Web
• 🍕 Chunk upload of large files
• ❌ No more out-of-memory issues
• 📁 Works with the Capacitor Filesystem and Capacitor File Picker

Installation

npm install @capawesome/capacitor-cloudinary
npx cap sync

Android

This API requires the following permission be added to your AndroidManifest.xml before the application tag:

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

You also need to add the following receiver inside the application tag in your AndroidManifest.xml:

<receiver android:name="io.capawesome.capacitorjs.plugins.cloudinary.DownloadBroadcastReceiver" android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>
  </intent-filter>
</receiver>

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

• $cloudinaryAndroidVersion version of com.cloudinary:cloudinary-android (default: 2.3.0)

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Usage

import { Cloudinary, ResourceType } from '@capawesome/capacitor-cloudinary';

const initialize = async () => {
  await Cloudinary.initialize({ cloudName: 'my_cloud_name' });
};

const uploadResource = async () => {
  await Cloudinary.uploadResource({
    path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Images/test.png',
    publicId: 'my_public_id',
    resourceType: ResourceType.image,
    uploadPreset: 'my_preset',
  });
};

const downloadResource = async () => {
  const { path } = await Cloudinary.downloadResource({
    url: 'https://res.cloudinary.com/myCloudName/image/upload/v123/123.png',
  });
  return path;
};

API

• initialize(...)
• uploadResource(...)
• downloadResource(...)
• Interfaces
• Enums

initialize(...)

initialize(options: InitializeOptions) => Promise<void>

Initialize the plugin.

This method must be called once before all other methods.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | InitializeOptions |

Since: 0.0.1

uploadResource(...)

uploadResource(options: UploadResourceOptions) => Promise<UploadResourceResult>

Upload a file to Cloudinary.

Note: Currently, only unsigned uploads are supported.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | UploadResourceOptions |

Returns: Promise<UploadResourceResult>

Since: 0.0.1

downloadResource(...)

downloadResource(options: DownloadResourceOptions) => Promise<DownloadResourceResult>

Download a file from Cloudinary.

On Android, the file will be downloaded to the Downloads directory. On iOS, the file will be downloaded to the temporary directory.

It is recommended to copy the file to a permanent location for further processing after downloading.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | DownloadResourceOptions |

Returns: Promise<DownloadResourceResult>

Since: 0.0.3

Interfaces

InitializeOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------------------------------------------------------------- | ----- | | cloudName | string | The cloud name of your app which you can find in the Cloudinary Management Console. | 0.0.1 |

UploadResourceResult

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----- | | assetId | string | The unique asset identifier of the uploaded resource. Only available on Android and Web. | 0.0.1 | | bytes | number | The number of bytes of the uploaded resource. | 0.0.1 | | createdAt | string | The timestamp at which the resource was uploaded. | 0.0.1 | | duration | number | The duration of the uploaded resource in seconds. | 0.1.5 | | format | string | The format of the uploaded resource. | 0.0.1 | | height | number | The height of the uploaded resource. | 0.1.4 | | originalFilename | string | The original filename of the uploaded resource. Only available on Android and iOS. | 0.0.1 | | resourceType | ResourceType | The resource type of the uploaded resource. | 0.0.1 | | publicId | string | The unique public identifier of the uploaded resource. | 0.0.1 | | url | string | The url of the uploaded resource. | 0.0.1 | | secureUrl | string | The secure url of the uploaded resource. | 5.1.0 | | width | number | The width of the uploaded resource. | 0.1.4 |

UploadResourceOptions

| Prop | Type | Description | Since | | ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------ | ----- | | resourceType | ResourceType | The resource type to upload. | 0.0.1 | | blob | Blob | The file to upload. Only available on Web. | 0.0.1 | | uploadPreset | string | The selected upload preset. | 0.0.1 | | path | string | The path of the file to upload. Only available on Android and iOS. | 0.0.1 | | publicId | string | Assign a unique public identifier to the resource. | 0.0.1 |

DownloadResourceResult

| Prop | Type | Description | Since | | ---------- | ------------------- | -------------------------------------------------------------------------------------------------------- | ----- | | path | string | The path of the downloaded resource where it is stored on the device. Only available on Android and iOS. | 0.0.3 | | blob | Blob | The downloaded resource as a blob. Only available on Web. | 0.0.1 |

DownloadResourceOptions

| Prop | Type | Description | Since | | --------- | ------------------- | ------------------------------------ | ----- | | url | string | The url of the resource to download. | 0.0.3 |

Enums

ResourceType

| Members | Value | Since | | ----------- | -------------------- | ----- | | Image | 'image' | 0.0.1 | | Video | 'video' | 0.0.1 | | Raw | 'raw' | 0.0.1 |

Utils

See docs/utils/README.md.

Changelog

See CHANGELOG.md.

License

See LICENSE.

Credits

This plugin is based on the Capacitor Cloudinary plugin. Thanks to everyone who contributed to the project!

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Cloudinary Ltd. or any of their affiliates or subsidiaries.