Démarrage

1. Installer 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. Synchroniser avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurer les permissions

   iOS

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

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

   Android

   Ajoutez les permissions à 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';

// Démarrer un téléchargement
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: 'Téléchargement de photo'
  });

  console.log('ID de téléchargement:', upload.id);
};

// Écouter les événements de téléchargement
const listener = await Uploader.addListener('events', (event) => {
  switch (event.name) {
    case 'uploading':
      console.log(`Téléchargement ${event.payload.id}: ${event.payload.percent}%`);
      break;
    case 'completed':
      console.log('Téléchargement terminé:', event.payload.id);
      console.log('Code de statut:', event.payload.statusCode);
      break;
    case 'failed':
      console.error('Échec du téléchargement:', event.payload.id);
      console.error('Erreur:', event.payload.error);
      break;
  }
});

// N'oubliez pas de retirer l'écouteur lorsque vous avez terminé
// listener.remove();

// Annuler un téléchargement
const cancelUpload = async (uploadId: string) => {
  await Uploader.cancelUpload({ id: uploadId });
};

// Obtenir tous les téléchargements actifs
const getActiveUploads = async () => {
  const uploads = await Uploader.getUploads();
  console.log('Téléchargements actifs:', uploads);
};

Référence API

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

cancelUpload(options)

Annule un téléchargement en cours.

interface CancelOptions {
  id: string;
}

getUploads()

Renvoie tous les téléchargements actifs.

removeUpload(options)

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

interface RemoveOptions {
  id: string;
}

Événements

events

Tous les événements de téléchargement sont délivré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':
      // Téléchargement en cours
      console.log(`Progression: ${event.payload.percent}%`);
      console.log(`ID: ${event.payload.id}`);
      break;

    case 'completed':
      // Téléchargement terminé avec succès
      console.log(`Terminé: ${event.payload.id}`);
      console.log(`Code de statut: ${event.payload.statusCode}`);
      break;

    case 'failed':
      // Échec du téléchargement
      console.error(`Échec: ${event.payload.id}`);
      console.error(`Erreur: ${event.payload.error}`);
      break;
  }
});

Types d’événements:

• uploading - Mise à jour de progression avec percent et id
• completed - Téléchargement terminé avec id et statusCode
• failed - Échec du téléchargement avec id et message d’error

Fonctionnalités avancées

Téléchargement multipart

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': 'Photo de profil utilisateur'
    },
    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 adapté au réseau

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

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

  if (status.connectionType === 'wifi') {
    // Démarrer les téléchargements de gros fichiers sur WiFi
    await startLargeUpload();
  } else if (status.connectionType === 'cellular') {
    // Mettre en file d'attente pour plus tard ou avertir l'utilisateur
    console.log('Utilisation des données cellulaires');
  }
};

Bonnes 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 écouteurs

   // Ajouter un écouteur
   const listener = await Uploader.addListener('events', handleEvent);
   
   // Nettoyer lorsque vous avez terminé
   listener.remove();

3. Réessayer les téléchargements échoués

   const retryUpload = async (filePath: string, serverUrl: string) => {
     try {
       await Uploader.startUpload({
         filePath,
         serverUrl,
         maxRetries: 3
       });
     } catch (error) {
       console.error('Échec du téléchargement après plusieurs tentatives:', error);
     }
   };

4. Afficher les notifications de téléchargement

   await Uploader.startUpload({
     filePath: 'file:///path/to/file',
     serverUrl: 'https://server.com/upload',
     notificationTitle: 'Téléchargement de fichier',
     notificationBody: 'Votre fichier est en cours de téléchargement...'
   });

Notes sur les plateformes

iOS

• Utilise URLSession pour les téléchargements en arrière-plan
• Nécessite la 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 une notification de service au premier plan pendant les téléchargements
• Respecte les paramètres d’optimisation de la batterie