はじめに

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

// アップロードを開始
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);
};

// アップロードイベントをリッスン
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;
  }
});

// 完了したらリスナーを削除することを忘れずに
// listener.remove();

// アップロードをキャンセル
const cancelUpload = async (uploadId: string) => {
  await Uploader.cancelUpload({ id: uploadId });
};

// すべてのアクティブなアップロードを取得
const getActiveUploads = async () => {
  const uploads = await Uploader.getUploads();
  console.log('Active uploads:', uploads);
};

APIリファレンス

startUpload(options)

新しいファイルアップロードを開始します。

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)

進行中のアップロードをキャンセルします。

interface CancelOptions {
  id: string;
}

getUploads()

すべてのアクティブなアップロードを返します。

removeUpload(options)

キューからアップロードを削除します。

interface RemoveOptions {
  id: string;
}

イベント

events

すべてのアップロードイベントは、単一のeventsリスナーを通じて配信されます。イベントには、タイプを識別するためのnameフィールドが含まれています：

Uploader.addListener('events', (event: UploadEvent) => {
  switch (event.name) {
    case 'uploading':
      // アップロード進行中
      console.log(`Progress: ${event.payload.percent}%`);
      console.log(`ID: ${event.payload.id}`);
      break;

    case 'completed':
      // アップロード完了
      console.log(`Completed: ${event.payload.id}`);
      console.log(`Status code: ${event.payload.statusCode}`);
      break;

    case 'failed':
      // アップロード失敗
      console.error(`Failed: ${event.payload.id}`);
      console.error(`Error: ${event.payload.error}`);
      break;
  }
});

イベントタイプ：

• uploading - percentとidを含む進行状況の更新
• completed - idとstatusCodeを含むアップロード完了
• failed - idとエラーmessageを含むアップロード失敗

高度な機能

マルチパートフォームアップロード

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') {
    // WiFi上で大きなファイルのアップロードを開始
    await startLargeUpload();
  } else if (status.connectionType === 'cellular') {
    // 後でキューに入れるかユーザーに警告
    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. リスナーをクリーンアップ

   // リスナーを追加
   const listener = await Uploader.addListener('events', handleEvent);
   
   // 完了したらクリーンアップ
   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を使用
• アップロード中にフォアグラウンドサービス通知を表示
• バッテリー最適化設定を尊重