本文へスキップ
hdknr blog
戻る

Capacitor の Live Updates(OTA 更新)を自前の AWS で配信する:S3・CloudFront 構成

Capacitor アプリは中身の大半が WebView で動く Web アセットなので、その部分だけをサーバーから配って差し替える Live Updates(OTA 更新) が使えます。仕組みとストア規約との関係は、Capacitor 入門の記事の「Live Updates(OTA 更新)」の節で整理しました。

この記事では、その配信側を 自分の AWS アカウントに作る 方法を紹介します。Ionic の Appflow は 2027 年 12 月 31 日でサービスを終えます。乗り換え先を探している場合や、配信の基盤とデータを自分で管理したい場合の選択肢になります。

端末側の更新処理には、オープンソースの Capgo プラグイン(@capgo/capacitor-updater)を使います。Capgo Cloud にはつながず、手動モード(いつ何をダウンロードして切り替えるかを、アプリのコードで決めるモード)で動かします。AWS 側は S3、CloudFront、GitHub Actions だけで、常時動くサーバーはありません。

全体の構成

Capacitor の Live Updates を自前の AWS で配信する構成図。GitHub Actions がビルドした Web アセットを zip に固めてチェックサムを計算し、OIDC で引き受けた IAM ロールで S3 に zip と manifest.json を書き込む。S3 は非公開で、CloudFront が OAC 経由で読んで HTTPS で配信する。アプリは起動直後に notifyAppReady を呼び、前面に来たら manifest.json を取得し、自分のストア版に対応するバンドルを選んで、チェックサム付きで zip をダウンロードし、次にバックグラウンドへ回ったときに切り替える。新しい版で notifyAppReady が期限内に呼ばれなければ前の版へ自動で戻る

役割は 3 つに分かれます。

manifest.json の設計

この記事では、ストアで配るアプリの版番号(例: 1.4.0)を ストア版、OTA で配る Web の版(例: 1.4.0-web.13)を バンドルの版 と呼びます。

配信の中心は、ストア版ごとに、配るバンドルを 1 つ決める manifest.json です。

{
  "1.3.0": {
    "version": "1.3.0-web.7",
    "url": "https://updates.example.com/bundles/1.3.0-web.7.zip",
    "checksum": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  },
  "1.4.0": {
    "version": "1.4.0-web.13",
    "url": "https://updates.example.com/bundles/1.4.0-web.13.zip",
    "checksum": "debd3b29509fcc4a934b9b5decb994623bfc44344d526198718e140ffeb7efed"
  }
}

ストア版をキーにするのは、OTA で差し替えられるのが Web 層だけだからです。ネイティブのプラグインを増やした 1.4.0 向けの JavaScript を 1.3.0 の端末に配ると、存在しないネイティブのメソッドを呼んで壊れます。キーで分けておけば、各ストア版には、そのネイティブ部分に合わせてビルドしたバンドルだけが届きます。

この形にしておくと、次の 2 つも manifest の操作だけで済みます。

アプリ側の実装

プラグインの導入と設定

npm install @capgo/capacitor-updater @capacitor/app
npx cap sync

capacitor.config.json(TypeScript なら capacitor.config.ts の plugins)で自動更新を切り、手動モードにします。

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": false
    }
  }
}

更新を確かめるコード

どの版を配るかの判定は、テストしやすいように関数に切り出しておきます。

// src/manifest.ts
export interface BundleEntry {
  version: string;
  url: string;
  checksum: string;
}

// キーはストア版(ネイティブ)の版。値はその版に配る Web バンドル
export type Manifest = Record<string, BundleEntry>;

export function pickBundle(
  manifest: Manifest,
  nativeVersion: string,
  currentVersion: string,
): BundleEntry | null {
  const entry = manifest[nativeVersion];
  if (!entry || entry.version === currentVersion) return null;
  return entry;
}

更新を確かめる処理です。アプリのエントリポイント(Vite なら src/main.ts)の先頭で import './live-update'; として読み込みます。

// src/live-update.ts
import { App } from '@capacitor/app';
import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { type Manifest, pickBundle } from './manifest';

const MANIFEST_URL = 'https://updates.example.com/manifest.json';

// 起動直後に呼ぶ。一定時間(既定 10 秒)内に呼ばれないと前の版に戻る
CapacitorUpdater.notifyAppReady();

async function checkForUpdate(): Promise<void> {
  const { version: nativeVersion } = await App.getInfo(); // ストア版の版(例: 1.4.0)
  const { bundle } = await CapacitorUpdater.current(); // いま動いている Web バンドル
  const res = await fetch(MANIFEST_URL, { cache: 'no-store' });
  if (!res.ok) return;
  const entry = pickBundle((await res.json()) as Manifest, nativeVersion, bundle.version);
  if (!entry) return;

  const downloaded = await CapacitorUpdater.download({
    url: entry.url,
    version: entry.version,
    checksum: entry.checksum, // 8.54 系では必須。無いと "Checksum required" で失敗する
  });
  // 次にバックグラウンドへ回ったときに切り替える(操作中の再読み込みを避ける)
  await CapacitorUpdater.next({ id: downloaded.id });
}

App.addListener('appStateChange', ({ isActive }) => {
  if (isActive) void checkForUpdate();
});
void checkForUpdate();

ポイントは 4 つです。

画面の文言

プラグインの README は、App Store の審査で誤解されないよう、利用者に見える画面で「アップデート」「ダウンロード中」のような言葉を使わないことを勧めています。切り替えを next() でバックグラウンドに回しているのは、利用者に何も見せずに済ませるためでもあります。

AWS 側の準備:S3・CloudFront・IAM ロール

S3 バケット

echo '{}' > manifest.json
aws s3 cp manifest.json s3://my-app-updates/manifest.json \
  --content-type application/json --cache-control "max-age=60"

CloudFront

CloudFront のディストリビューションはコンソールで作成します。押さえる設定は次の 3 点です。

バケットポリシーで、この配信からの読み取りだけを許可します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontRead",
      "Effect": "Allow",
      "Principal": { "Service": "cloudfront.amazonaws.com" },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-app-updates/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::123456789012:distribution/E1234567890ABC"
        }
      }
    }
  ]
}

GitHub Actions 用の IAM ロール

アクセスキーを GitHub に置かず、OIDC で一時的な認証情報を受け取ります。GitHub Actions が実行ごとに発行する短命のトークンを AWS に示し、一時的な認証情報と交換する仕組みです。IAM に GitHub の OIDC プロバイダ(token.actions.githubusercontent.com)を登録し、次の信頼ポリシーを持つロールを作ります。sub の条件で、引き受けられるのを特定のリポジトリの main ブランチからの実行に絞っています。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:my-org/my-app:ref:refs/heads/main"
        }
      }
    }
  ]
}

権限は、zip の置き場所と manifest への書き込みだけにします。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PutBundles",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::my-app-updates/bundles/*"
    },
    {
      "Sid": "ReadWriteManifest",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::my-app-updates/manifest.json"
    }
  ]
}

GitHub Actions の配信ワークフロー

手動で起動し、配信先のストア版を入力して実行するワークフローです。ビルドや CI 全般については、Capacitor 入門の記事の「GitHub Actions で CI を回す」の節も参照してください。

name: Live update

on:
  workflow_dispatch:
    inputs:
      native_version:
        description: 配信先のストア版(例 1.4.0)
        required: true

permissions:
  id-token: write # OIDC で AWS のロールを引き受けるため
  contents: read

concurrency: live-update # manifest.json の同時更新を防ぐ

env:
  BUCKET: my-app-updates
  BASE_URL: https://updates.example.com

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build

      - name: Zip the web bundle
        id: bundle
        env:
          NATIVE_VERSION: ${{ inputs.native_version }}
        run: |
          [[ "$NATIVE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "native_version must be x.y.z"; exit 1; }
          VERSION="${NATIVE_VERSION}-web.${GITHUB_RUN_NUMBER}"
          (cd dist && zip -qr "../${VERSION}.zip" . -x '.*' -x '*/.*')
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
          echo "checksum=$(sha256sum "${VERSION}.zip" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"

      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/live-update-publisher
          aws-region: ap-northeast-1

      - name: Upload the bundle
        env:
          VERSION: ${{ steps.bundle.outputs.version }}
        run: |
          aws s3 cp "${VERSION}.zip" "s3://${BUCKET}/bundles/${VERSION}.zip" \
            --content-type application/zip \
            --cache-control "public, max-age=31536000, immutable"

      - name: Point the manifest at the new bundle
        env:
          NATIVE_VERSION: ${{ inputs.native_version }}
          VERSION: ${{ steps.bundle.outputs.version }}
          CHECKSUM: ${{ steps.bundle.outputs.checksum }}
        run: |
          aws s3 cp "s3://${BUCKET}/manifest.json" manifest.json
          jq --arg n "$NATIVE_VERSION" --arg v "$VERSION" \
             --arg u "${BASE_URL}/bundles/${VERSION}.zip" --arg c "$CHECKSUM" \
             '.[$n] = {version: $v, url: $u, checksum: $c}' manifest.json > manifest.next.json
          aws s3 cp manifest.next.json "s3://${BUCKET}/manifest.json" \
            --content-type application/json \
            --cache-control "max-age=60"

いくつか意図して書いている箇所があります。

運用:ロールバックと改ざん対策

ロールバック

S3 のバージョニングを有効にしてあれば、manifest.json を S3 上の一つ前のオブジェクトバージョンに戻すだけで、全端末への配信が前のバンドルに戻ります。まずバージョンの一覧から戻したい VersionId を探し、<戻したいバージョンID> をその値に置き換えてコピーします。

aws s3api list-object-versions --bucket my-app-updates --prefix manifest.json \
  --query 'Versions[].[VersionId,LastModified,IsLatest]' --output table
aws s3api copy-object --bucket my-app-updates --key manifest.json \
  --copy-source "my-app-updates/manifest.json?versionId=<戻したいバージョンID>"

同じキーに前のバージョンをコピーすると、それが新しい現行のバージョンになり、それまでのバージョンもすべて残ります(AWS のドキュメントにある復元の手順と同じです)。

すでに新しいバンドルで起動に失敗した端末は、notifyAppReady() の仕組みで端末側でも前のバンドルに戻ります。ただしこれは「起動して JavaScript が動き始めたか」だけを見ているので、起動後の不具合は manifest を戻して直します。

改ざん対策について

この構成で配信物を守っているのは、次の 2 つです。

checksum が防ぐのは、転送中の破損や、zip だけが差し替えられた場合です。チェックサムは manifest.json に書いてあるので、manifest ごと書き換えられると防げません。

プラグインには、公開鍵(publicKey)を設定し、対応する秘密鍵で作ったバンドルしか入れないようにする仕組み(エンドツーエンドの暗号化 v2)もあります。ただし型定義には、CLI の encrypt コマンドで暗号化した場合は checksum と sessionKey の指定が必須で、値はそのコマンドの結果として受け取る、とあります。ネイティブ側の実装でも、publicKey を設定すると sessionKey の無いダウンロードは拒否されます。この記事の手動モードと組み合わせる方法は扱っていません。署名の検証まで必要な場合は、Capgo の CLI とドキュメントで確かめてください。

この記事のコードについて

src/manifest.ts と src/live-update.ts は、@capgo/capacitor-updater 8.54.2、@capacitor/app 8、@capacitor/core 8 の型定義に対して tsc --strict で型チェックを通しています。pickBundle() は、次の 4 件のテストで確かめています。

ワークフローの run: の行は、AWS CLI を呼ぶ行を除いて、手元のシェルで同じものを実行し、次のことを確かめました。

ワークフローの YAML と 3 つのポリシーの JSON は、構文として読み込めることを確かめています。実際の端末での動作と、実際の AWS への配置は試していません。

まとめ

Capacitor の Live Updates は、配信側を S3 と CloudFront だけで作れます。要になるのは、ストア版ごとに配るバンドルを決める manifest.json です。これ 1 つで、ネイティブ部分との互換、審査中の保留、ロールバックをまとめて扱えます。改ざん対策は、書き込める主体の制限と HTTPS までで、バンドルの署名検証はこの記事では扱っていません。

端末側は Capgo のオープンソースのプラグインに任せられますが、手動モードでは checksum が必須であること、審査中の端末を避ける対策は自分で用意することの 2 点を押さえておく必要があります。

参考



前の記事
Meta Muse と Hermes Agent の違い — マネージド型とセルフホスト型、常駐 AI エージェントの選び方と併用例
次の記事
Capacitor 入門:Web アプリをそのまま iOS・Android アプリにする仕組みと手順