スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

次に、以下のプロンプトを使用します：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-uploader` plugin in my project.

手動セットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

bun add @capgo/capacitor-uploader
bunx cap sync

インポート

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

クイックスタート

アップロードを開始し、以下を購読します： events、および返されたアップロードを追跡します： id.

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

let uploadId = '';

const listener = await Uploader.addListener('events', async (event) => {
  if (event.id !== uploadId) return;

  if (event.name === 'uploading') {
    console.log(event.payload.percent);
  }

  if (event.name === 'completed' || event.name === 'failed') {
    if (event.eventId) {
      await Uploader.acknowledgeEvent({ eventId: event.eventId });
    }
    await listener.remove();
  }
});

const { id } = await Uploader.startUpload({
  filePath: 'file:///data/user/0/.../scan.jpg',
  serverUrl: 'https://api.example.com/v1/assets',
  method: 'POST',
  headers: { Authorization: 'Bearer token' },
  maxRetries: 3,
});
uploadId = id;

例: S3 署名付き PUT

PUT アップロードは単一ファイルのみ対応しています。署名付きURLを serverUrl 設定してください method: 'PUT'.

await Uploader.startUpload({
  filePath: capturedUri,
  serverUrl: presignedUrl,
  method: 'PUT',
  headers: { 'Content-Type': 'image/jpeg' },
});

例: 追加フィールド付き multipart form

await Uploader.uploadMultipart({
  url: 'https://api.example.com/upload',
  filePath: localPath,
  fieldName: 'file',
  fields: { userId: '42', kind: 'receipt' },
  headers: { Authorization: 'Bearer token' },
});

よくある落とし穴

• 複数ファイル: 次を使用します files を startUpload で1つのmultipartリクエストとして送信します。 PUT 複数のbodyを送信することはできません。
• Webバックグラウンド: ユーザーがタブを閉じるとアップロードは停止します。アプリがバックグラウンドに回っても完了させる必要がある場合は、native platformsを使用してください。
• キャンセル：呼び出し removeUpload({ id }) のidを使用して startUpload.
• 進捗: 必ず事前に events リスナーを登録してください。そうしないと、初期の進捗を見逃す可能性があります。

API の概要

startUpload

サーバーへのファイルアップロードを開始します。

アプリが終了したりバックグラウンドに回ったりしても、アップロードはバックグラウンドで継続されます。 アップロードイベントをリッスンして、進捗、完了、または失敗を追跡してください。

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

const { id } = await Uploader.startUpload({
  filePath: 'file:///path/to/file.jpg',
  serverUrl: 'https://example.com/upload',
  headers: {
    'Authorization': 'Bearer token'
  },
  method: 'POST',
  uploadType: 'multipart',
  fileField: 'photo'
});
console.log('Upload started with ID:', id);

removeUpload

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

実行中のアップロードを停止し、リソースをクリーンアップします。

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

await Uploader.removeUpload({ id: 'upload-123' });

型リファレンス

uploadOption

ファイルのアップロードに関する設定オプション。

export interface uploadOption {
  /**
   * The local file path of the file to upload.
   * Can be a file:// URL or an absolute path.
   *
   * @since 0.0.1
   */
  filePath: string;

  /**
   * The server URL endpoint where the file should be uploaded.
   *
   * @since 0.0.1
   */
  serverUrl: string;

  /**
   * The title of the upload notification shown to the user.
   * Android only.
   *
   * @default 'Uploading'
   * @since 0.0.1
   */
  notificationTitle?: string;

  /**
   * HTTP headers to send with the upload request.
   * Useful for authentication tokens, content types, etc.
   *
   * @since 0.0.1
   * @example
   * ```typescript
   * headers: {
   *   'Authorization': 'Bearer token123',
   *   'X-Custom-Header': 'value'
   * }
   * ```
   */
  headers: {
    [key: string]: string;
  };

  /**
   * The HTTP method to use for the upload request.
   *
   * @default 'POST'
   * @since 0.0.1
   */
  method?: 'PUT' | 'POST';

  /**
   * The MIME type of the file being uploaded.
   * If not specified, the plugin will attempt to determine it automatically.
   *
   * @since 0.0.1
   * @example 'image/jpeg', 'application/pdf', 'video/mp4'
   */
  mimeType?: string;

  /**
   * Additional form parameters to send with the upload request.
   * These will be included as form data in multipart uploads.
   *
   * @since 0.0.1
   */
  parameters?: { [key: string]: string };

  /**
   * The maximum number of times to retry the upload if it fails.
   *
   * @since 0.0.1
   * @default 0
   */
  maxRetries?: number;

  /**
   * The type of upload to perform.
   * - 'binary': Uploads the file as raw binary data in the request body
   * - 'multipart': Uploads the file as multipart/form-data
   *
   * @default 'binary'
   * @since 0.0.2
   */
  uploadType?: 'binary' | 'multipart';

  /**
   * The form field name for the file when using multipart upload type.
   * Only used when uploadType is 'multipart'.
   *
   * @default 'file'
   * @since 0.0.2
   */
  fileField?: string;
}

UploadEvent

アップロードのライフサイクル中に発行されるイベント。

export interface UploadEvent {
  /**
   * The current status of the upload.
   * - 'uploading': Upload is in progress
   * - 'completed': Upload finished successfully
   * - 'failed': Upload encountered an error
   *
   * @since 0.0.1
   */
  name: 'uploading' | 'completed' | 'failed';

  /**
   * Additional data about the upload event.
   *
   * @since 0.0.1
   */
  payload: {
    /**
     * Upload progress percentage from 0 to 100.
     * Only present during 'uploading' events.
     *
     * @since 0.0.1
     */
    percent?: number;

    /**
     * Error message if the upload failed.
     * Only present during 'failed' events.
     *
     * @since 0.0.1
     */
    error?: string;

    /**
     * HTTP status code returned by the server.
     * Present during 'completed' and 'failed' events.
     *
     * @since 0.0.1
     */
    statusCode?: number;
  };

  /**
   * Unique identifier for this upload task.
   *
   * @since 0.0.1
   */
  id: string;
}

Source of Truth

このページはプラグインの src/definitions.tsから生成されています。upstream で公開 API が変更されたら、再度 sync を実行してください。

Getting Startedの続きを進める

使用している場合 スタートガイド ダッシュボードと API の運用を計画するには、これを次と連携させます @capgo/capacitor-uploader の使用方法 @capgo/capacitor-uploader を使用して Native Build の機能を利用する場合: API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー および「API Keys」の実装の詳細については、 デバイス 実装の詳細については Devices を参照してください。