Comenzando

1. Instalar el paquete

   npm

   npm i @Capgo/Capacitor-uploader

   pnpm

   pnpm add @Capgo/Capacitor-uploader

   yarn

   yarn add @Capgo/Capacitor-uploader

   bun

   bun add @Capgo/Capacitor-uploader

2. Sincronizar con proyectos nativos

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurar permisos

   iOS

   Agrega modos de segundo plano a tu Info.plist:

   <key>UIBackgroundModes</key>
   <array>
     <string>processing</string>
   </array>

   Android

   Agrega permisos a tu AndroidManifest.xml:

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Uso

Importa el Plugin y usa sus métodos para subir archivos:

import { Uploader } from '@capgo/capacitor-uploader';

// Iniciar una subida
const startUpload = async () => {
  const upload = await Uploader.startUpload({
    filePath: 'file:///path/to/your/file.jpg',
    serverUrl: 'https://your-server.com/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-token'
    },
    parameters: {
      'userId': '12345',
      'type': 'profile'
    },
    notificationTitle: 'Subiendo Foto'
  });

  console.log('Upload ID:', upload.id);
};

// Escuchar eventos de subida
const listener = await Uploader.addListener('events', (event) => {
  switch (event.name) {
    case 'uploading':
      console.log(`Upload ${event.payload.id}: ${event.payload.percent}%`);
      break;
    case 'completed':
      console.log('Upload completed:', event.payload.id);
      console.log('Status code:', event.payload.statusCode);
      break;
    case 'failed':
      console.error('Upload failed:', event.payload.id);
      console.error('Error:', event.payload.error);
      break;
  }
});

// Recuerda remover el listener cuando termines
// listener.remove();

// Cancelar una subida
const cancelUpload = async (uploadId: string) => {
  await Uploader.cancelUpload({ id: uploadId });
};

// Obtener todas las subidas activas
const getActiveUploads = async () => {
  const uploads = await Uploader.getUploads();
  console.log('Subidas activas:', uploads);
};

Referencia API

startUpload(Opciones)

Inicia una nueva subida de archivo.

interface UploadOptions {
  filePath: string;
  serverUrl: string;
  method?: 'POST' | 'PUT';
  headers?: { [key: string]: string };
  parameters?: { [key: string]: string };
  notificationTitle?: string;
  notificationBody?: string;
  useUtf8Charset?: boolean;
  maxRetries?: number;
}

cancelUpload(Opciones)

Cancela una subida en curso.

interface CancelOptions {
  id: string;
}

getUploads()

Devuelve todas las subidas activas.

removeUpload(Opciones)

Elimina una subida de la cola.

interface RemoveOptions {
  id: string;
}

Eventos

events

Todos los eventos de subida se entregan a través de un único listener events. El evento contiene un campo name para identificar el tipo:

Uploader.addListener('events', (event: UploadEvent) => {
  switch (event.name) {
    case 'uploading':
      // Subida en progreso
      console.log(`Progress: ${event.payload.percent}%`);
      console.log(`ID: ${event.payload.id}`);
      break;

    case 'completed':
      // Subida finalizada exitosamente
      console.log(`Completed: ${event.payload.id}`);
      console.log(`Status code: ${event.payload.statusCode}`);
      break;

    case 'failed':
      // Subida fallida
      console.error(`Failed: ${event.payload.id}`);
      console.error(`Error: ${event.payload.error}`);
      break;
  }
});

Tipos de Eventos:

• uploading - Actualización de progreso con percent e id
• completed - Subida finalizada con id y statusCode
• failed - Subida fallida con id y mensaje de error

Características Avanzadas

Subida de Formulario Multipartes

const uploadWithFormData = async () => {
  const upload = await Uploader.startUpload({
    filePath: 'file:///path/to/photo.jpg',
    serverUrl: 'https://api.example.com/upload',
    method: 'POST',
    parameters: {
      'name': 'foto-perfil',
      'description': 'Foto de perfil de usuario'
    },
    headers: {
      'X-API-Key': 'your-api-key'
    }
  });
};

Subida Binaria

const uploadBinary = async () => {
  const upload = await Uploader.startUpload({
    filePath: 'file:///path/to/data.bin',
    serverUrl: 'https://api.example.com/binary',
    method: 'PUT',
    headers: {
      'Content-Type': 'application/octet-stream'
    }
  });
};

Subida Consciente de Red

import { Network } from '@capacitor/network';

const smartUpload = async () => {
  const status = await Network.getStatus();

  if (status.connectionType === 'wifi') {
    // Iniciar subidas de archivos grandes en WiFi
    await startLargeUpload();
  } else if (status.connectionType === 'cellular') {
    // Encolar para después o advertir al usuario
    console.log('Usando datos celulares');
  }
};

Mejores Prácticas

1. Manejar todos los tipos de eventos

   const setupUploadHandlers = () => {
     Uploader.addListener('events', (event) => {
       switch (event.name) {
         case 'uploading':
           handleProgress(event.payload);
           break;
         case 'completed':
           handleCompleted(event.payload);
           break;
         case 'failed':
           handleError(event.payload);
           break;
       }
     });
   };

2. Limpiar listeners

   // Agregar listener
   const listener = await Uploader.addListener('events', handleEvent);
   
   // Limpiar cuando termine
   listener.remove();

3. Reintentar subidas fallidas

   const retryUpload = async (filePath: string, serverUrl: string) => {
     try {
       await Uploader.startUpload({
         filePath,
         serverUrl,
         maxRetries: 3
       });
     } catch (error) {
       console.error('Subida fallida después de reintentos:', error);
     }
   };

4. Mostrar notificaciones de subida

   await Uploader.startUpload({
     filePath: 'file:///path/to/file',
     serverUrl: 'https://server.com/upload',
     notificationTitle: 'Subiendo Archivo',
     notificationBody: 'Tu archivo se está subiendo...'
   });

Notas de Plataforma

iOS

• Usa URLSession para subidas en segundo plano
• Requiere capacidad de procesamiento en segundo plano
• Las subidas continúan cuando la Aplicación está suspendida

Android

• Usa WorkManager para subidas confiables
• Muestra notificación de servicio en primer plano durante subidas
• Respeta configuraciones de optimización de batería