Commencer

1. Installez le package

   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. Synchronisation avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurer les autorisations

   iOS

   Ajoutez des modes d’arrière-plan à votre Info.plist :

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

   Android

   Ajoutez des autorisations à votre 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" />

Utilisation

Importez le plugin et utilisez ses méthodes pour télécharger des fichiers :

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

// Start an upload
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: 'Uploading Photo'
  });

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

// Listen for upload events
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;
  }
});

// Remember to remove listener when done
// listener.remove();

// Cancel an upload
const cancelUpload = async (uploadId: string) => {
  await Uploader.cancelUpload({ id: uploadId });
};

// Get all active uploads
const getActiveUploads = async () => {
  const uploads = await Uploader.getUploads();
  console.log('Active uploads:', uploads);
};

API Référence

startUpload(options)

Démarre un nouveau téléchargement de fichier.

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;
}

annuler le téléchargement (options)

Annule un téléchargement en cours.

interface CancelOptions {
  id: string;
}

###getUploads()

Renvoie tous les téléchargements actifs.

Supprimer le téléchargement (options)

Supprime un téléchargement de la file d’attente.

interface RemoveOptions {
  id: string;
}

Événements

événements

Tous les événements de téléchargement sont diffusés via un seul écouteur events. L’événement contient un champ name pour identifier le type :

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

    case 'completed':
      // Upload finished successfully
      console.log(`Completed: ${event.payload.id}`);
      console.log(`Status code: ${event.payload.statusCode}`);
      break;

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

Types d’événements :

• uploading - Mise à jour des progrès avec percent et id
• completed - Téléchargement terminé avec id et statusCode
• failed - Échec du téléchargement avec les messages id et error

Fonctionnalités avancées

Téléchargement de formulaire en plusieurs parties

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

Téléchargement binaire

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'
    }
  });
};

Téléchargement compatible réseau

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

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

  if (status.connectionType === 'wifi') {
    // Start large file uploads on WiFi
    await startLargeUpload();
  } else if (status.connectionType === 'cellular') {
    // Queue for later or warn user
    console.log('Using cellular data');
  }
};

## meilleures pratiques

1. Gérer tous les types d’événements

   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. Nettoyer les auditeurs

   // Add listener
   const listener = await Uploader.addListener('events', handleEvent);
   
   // Clean up when done
   listener.remove();

3. Réessayez les téléchargements ayant échoué

   const retryUpload = async (filePath: string, serverUrl: string) => {
     try {
       await Uploader.startUpload({
         filePath,
         serverUrl,
         maxRetries: 3
       });
     } catch (error) {
       console.error('Upload failed after retries:', error);
     }
   };

4. Afficher les notifications de téléchargement

   await Uploader.startUpload({
     filePath: 'file:///path/to/file',
     serverUrl: 'https://server.com/upload',
     notificationTitle: 'Uploading File',
     notificationBody: 'Your file is being uploaded...'
   });

## Remarques sur la plate-forme

iOS

• Utilise URLSession pour les téléchargements en arrière-plan
• Nécessite une capacité de traitement en arrière-plan
• Les téléchargements continuent lorsque l’application est suspendue

Android

• Utilise WorkManager pour des téléchargements fiables
• Affiche la notification du service de premier plan lors des téléchargements
• Respecte les paramètres d’optimisation de la batterie