시작하기

1. 패키지 설치

   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. 네이티브 프로젝트와 동기화

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. 권한 구성

   iOS

   Info.plist에 배경 모드를 추가하세요.

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

   Android

   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" />

사용법

플러그인을 가져오고 해당 메소드를 사용하여 파일을 업로드하십시오.

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 참조

시작업로드(옵션)

새 파일 업로드를 시작합니다.

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

취소업로드(옵션)

진행 중인 업로드를 취소합니다.

interface CancelOptions {
  id: string;
}

getUpload()

모든 활성 업로드를 반환합니다.

제거업로드(옵션)

대기열에서 업로드를 제거합니다.

interface RemoveOptions {
  id: string;
}

이벤트

이벤트

모든 업로드 이벤트는 단일 events 리스너를 통해 전달됩니다. 이벤트에는 유형을 식별하기 위한 name 필드가 포함되어 있습니다.

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

이벤트 유형:

• uploading - percent 및 id 진행 상황 업데이트
• completed - id 및 statusCode 업로드가 완료되었습니다.
• failed - id 및 error 메시지로 인해 업로드에 실패했습니다.

고급 기능

멀티파트 양식 업로드

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

바이너리 업로드

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

네트워크 인식 업로드

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

모범 사례

1. 모든 이벤트 유형 처리

   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. 청취자 정리

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

3. 실패한 업로드 재시도

   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. 업로드 알림 표시

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

플랫폼 노트

iOS

• 백그라운드 업로드에 URLSession을 사용합니다.
• 백그라운드 처리 기능이 필요합니다.
• 앱이 정지되어도 업로드는 계속됩니다.

Android

• 안정적인 업로드를 위해 WorkManager을 사용합니다.
• 업로드 중 포그라운드 서비스 알림 표시
• 배터리 최적화 설정을 존중합니다.