スタートガイド

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-live-activities`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/live-activities/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

インストール

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

bunx 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-live-activities` plugin in my project.

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

bun add @capgo/capacitor-live-activities
bunx cap sync

iOSのセットアップ

プラグインのインストールと同期だけでは、ネイティブのLive Activity UIは作成されません。ActivityKitでは、表示を開始する前に、Live Activityの設定を登録するWidget Extensionが必要です。 startActivity 表示を開始する前に、

要件

アプリのターゲットとWidget Extensionのターゲットの両方で、iOS 16.1以降を使用してください。
iOSの実機または互換性のあるシミュレーターでテストしてください。Dynamic Islandは対応しているデバイスモデルでのみ表示され、その他のデバイスではロック画面に表示されます。
静的および動的なActivityKitデータの合計を、Appleの4 KB制限以下に抑えてください。

ネイティブのiOSプロジェクトを開きます：

bunx cap open ios

次に:

選択します ファイル > 新規 > ターゲット.
他の依存関係用の Widget Extension.
有効にする Live Activityを導入する.
Disable Configuration Intentを含める アプリに設定可能なウィジェットが必要な場合を除きます。
生成されたextensionがメインのapp targetに組み込まれていることを確認してください。

Widget Extensionには以下を含める必要があります： ActivityConfiguration and register it in its WidgetBundle。また、以下のすべてのLive Activity表示に対応している必要があります：

ロック画面
Dynamic Island（拡張時）
Dynamic Island（コンパクト：Leading/Trailing）
Dynamic Island（最小）

targetを追加するだけでは不十分です。ネイティブアプリまたはpluginからActivityKitのrequest、update、end APIを呼び出す必要があります。また、extensionには、同じデータをデコードして描画できるSwiftUI codeを含める必要があります。 ActivityAttributes コンテンツ状態をデコードして描画できるように含まれている必要があります。ActivityKitの共有モデルをメインアプリとWidget Extensionの両方のターゲットに含めてください。Xcodeが生成するLive Activityテンプレートは、このプラグインに渡されたJSONレイアウトを自動的に描画しません。拡張機能にも互換性のあるネイティブレイアウトレンダラーが必要です。

2. Live Activitiesを有効にする

メインアプリターゲットに以下のキーを追加してください： Info.plist:

<key>NSSupportsLiveActivities</key>
<true/>

プロジェクトが以下を生成している場合は、 Info.plist、以下を追加してください： Live Activitiesのサポート Boolean値として、 YES 代わりに、メインアプリターゲットのカスタムiOSターゲットプロパティの下に追加してください。

3. 画像共有のためのApp Group設定

App Groupが必要になるのは、以下を使用する場合のみです： saveImage, removeImage, listImages、または cleanupImages. このプラグインは、以下の形式を使用してメインアプリの bundle identifier から App Group identifier を生成します：

group.<MAIN_APP_BUNDLE_ID>.liveactivities

例えば、bundle identifier が com.example.delivery 必須事項:

group.com.example.delivery.liveactivities

Xcode で、 App Groups capability をメインアプリの target と Widget Extension の target の両方に追加し、両方の target で同じ identifier を有効にしてください。

Live Activity extension はネットワークにアクセスできません。リモート画像を使用する場合は、メインアプリで画像をダウンロードして共有 App Group に保存してから、Live Activity で参照するようにしてください。バンドルされた画像を使用する場合は、asset の target membership で Widget Extension も有効にしてください。

4. Deep Link の設定

使用する場合、 behavior.widgetUrl またはタイマーシーケンス tapUrl、メインアプリに対応するURLスキームまたはUniversal Linkを登録します。次のようなカスタムスキームの場合： myapp://order/12345、メインアプリターゲットの 情報 > URL Types の設定にスキームを追加します。

5. オプション: サーバー駆動型アップデートを有効にする

アプリが開始するローカルアップデートにPush Notificationsは不要です。サーバーからLive Activitiesを開始、更新、終了するには：

次を追加します： プッシュ通知 Capabilityをメインアプリターゲットに追加します。
ActivityKit push tokenを取得し、サーバーへ送信します。
APNs経由でActivityKit通知を送信するには、 liveactivity pushタイプを使用します。
追加 NSSupportsLiveActivitiesFrequentUpdates メインアプリに対して、 Info.plist 頻繁なプッシュ更新が必要なユースケースでのみ使用してください。

ActivityKit push tokenは、標準的なユーザー通知用のデバイストークンとは異なります。 Push Notificationsの機能を有効にするだけでは不十分です。サーバー主導のアップデートには、ネイティブでのトークン処理とAPNsバックエンドが必要です。

ネイティブ設定チェックリスト

呼び出す前に、 startActivity以下を確認してください：

NSSupportsLiveActivities がメインアプリのターゲットで有効になっていること。
Widget Extensionは埋め込まれ、以下のものを登録します： ActivityConfiguration.
ネイティブのActivityKit実装とWidget Extensionは、同じ ActivityAttributes タイプを使用します。
アプリとWidget ExtensionのデプロイターゲットはiOS 16.1以降です。
iOSの設定で、アプリのLive Activitiesが有効になっている必要があります。
画像を共有する場合は、両方のターゲットで対応するApp Groupを有効にします。
使用されるすべてのカスタムURLスキームは、 widgetUrl または tapUrl 登録されます。

インポート

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

クイックスタート

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
  console.log('Live Activities are supported!');
} else {
  console.log('Not supported:', reason);
}

例: startActivity

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'horizontal',
    children: [
      { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
      { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
    ]
  },
  dynamicIslandLayout: {
    expanded: {
      leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
      trailing: { type: 'text', content: '{{eta}}' },
      center: { type: 'text', content: '{{status}}' },
      bottom: { type: 'progress', value: 'progress' }
    },
    compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
    compactTrailing: { type: 'text', content: '{{eta}}' },
    minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
  },
  data: {
    orderNumber: '12345',
    status: 'On the way',
    eta: '10 min',
    progress: 0.6
  }
});
console.log('Started activity:', activityId);

例: updateActivity

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.updateActivity({
  activityId: 'abc123',
  data: {
    status: 'Arrived!',
    eta: 'Now',
    progress: 1.0
  },
  alertConfiguration: {
    title: 'Delivery Update',
    body: 'Your order has arrived!'
  }
});

よくある落とし穴

リスナー: 画面がアンマウントされたらハンドルを削除します。
ネイティブ同期: 実行 bunx cap sync プラグインのアップグレード後。
信頼できる情報源: 信頼 src/definitions.ts GitHub リポジトリ内。

API の概要

`areActivitiesSupported`

このデバイスで Live Activities がサポートされているか確認します。 iOS 16.1以降およびデバイスのサポートが必要です。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
  console.log('Live Activities are supported!');
} else {
  console.log('Not supported:', reason);
}

`startActivity`

指定したレイアウトとデータで、新しい Live Activity を開始します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'horizontal',
    children: [
      { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
      { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
    ]
  },
  dynamicIslandLayout: {
    expanded: {
      leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
      trailing: { type: 'text', content: '{{eta}}' },
      center: { type: 'text', content: '{{status}}' },
      bottom: { type: 'progress', value: 'progress' }
    },
    compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
    compactTrailing: { type: 'text', content: '{{eta}}' },
    minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
  },
  data: {
    orderNumber: '12345',
    status: 'On the way',
    eta: '10 min',
    progress: 0.6
  }
});
console.log('Started activity:', activityId);

`updateActivity`

既存の Live Activity を新しいデータで更新します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.updateActivity({
  activityId: 'abc123',
  data: {
    status: 'Arrived!',
    eta: 'Now',
    progress: 1.0
  },
  alertConfiguration: {
    title: 'Delivery Update',
    body: 'Your order has arrived!'
  }
});

`endActivity`

Live Activityを終了します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.endActivity({
  activityId: 'abc123',
  data: { status: 'Delivered' },
  dismissalPolicy: 'after',
  dismissAfter: Date.now() + 3600000 // 1 hour from now
});

`getAllActivities`

現在アクティブなすべてのLive Activityを取得します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

`saveImage`

Live Activitiesで使用するために、画像を共有App Groupコンテナに保存します。ウィジェット拡張機能からアクセスするには、画像を共有コンテナに保存する必要があります。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success, imageName } = await CapgoLiveActivities.saveImage({
  imageData: 'base64EncodedImageData...',
  name: 'product-image',
  compressionQuality: 0.8
});
// Use in layout with: { type: 'image', source: 'saved', value: imageName }

`removeImage`

共有コンテナから保存済みの画像を削除します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

`listImages`

共有コンテナ内の保存済み画像をすべて一覧表示します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

`cleanupImages`

共有コンテナから保存済み画像をすべて削除します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.cleanupImages();

`startTimerSequence`

ワークアウトやスポーツ向けのタイマーシーケンスを開始します。 iOSの場合: Live ActivityとDynamic Islandに表示されます Androidの場合: タイマー付きのフォアグラウンド通知として表示されます

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { sequenceId } = await CapgoLiveActivities.startTimerSequence({
  title: 'HIIT Workout',
  steps: [
    { duration: 30, title: 'Jumping Jacks', subtitle: 'Warm up', color: '#FF6B00', icon: 'figure.jumprope' },
    { duration: 10, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Burpees', subtitle: 'High intensity', color: '#FF0000', icon: 'flame.fill' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Mountain Climbers', color: '#FF0000', icon: 'figure.run' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
  ],
  loop: true,
  loopCount: 3,
  soundEnabled: true,
  vibrateEnabled: true,
  countdownBeeps: true,
  tapUrl: 'myapp://workout/hiit'
});

`pauseTimerSequence`

タイマーシーケンスを一時停止します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

`resumeTimerSequence`

一時停止中のタイマーシーケンスを再開します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

`stopTimerSequence`

タイマーシーケンスを停止して閉じます。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

`skipTimerStep`

シーケンスの次のステップへスキップします。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

`previousTimerStep`

シーケンスの前のステップに戻ります。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

`getTimerState`

タイマーシーケンスの現在の状態を取得します。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const state = await CapgoLiveActivities.getTimerState({ sequenceId: 'abc123' });
console.log(`Step ${state.currentStepIndex + 1}/${state.totalSteps}: ${state.currentStep.title}`);
console.log(`Time remaining: ${state.remainingSeconds}s`);

型リファレンス

`AreActivitiesSupportedResult`

Live Activityがサポートされているかどうかの確認結果。

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

`StartActivityOptions`

Live Activityを開始するためのオプション。

export interface StartActivityOptions {
  /** Main activity layout (lock screen widget) */
  layout: ActivityLayout;
  /** Dynamic Island layout configuration */
  dynamicIslandLayout: DynamicIslandLayout;
  /** Activity behavior settings */
  behavior?: LiveActivitiesBehavior;
  /** Dynamic data for the activity */
  data: Record<string, unknown>;
  /** Stale date timestamp (activity becomes stale after this) */
  staleDate?: number;
  /** Relevance score for activity ordering (0-100) */
  relevanceScore?: number;
}

`StartActivityResult`

アクティビティを開始した結果。

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

`UpdateActivityOptions`

Live Activityを更新するためのオプション。

export interface UpdateActivityOptions {
  /** Activity ID to update */
  activityId: string;
  /** Updated data */
  data: Record<string, unknown>;
  /** Optional alert to show with update */
  alertConfiguration?: ActivityAlertConfiguration;
  /** Updated stale date */
  staleDate?: number;
  /** Updated relevance score */
  relevanceScore?: number;
}

`EndActivityOptions`

Live Activityを終了するためのオプション。

export interface EndActivityOptions {
  /** Activity ID to end */
  activityId: string;
  /** Final data to display */
  data?: Record<string, unknown>;
  /** Dismissal policy */
  dismissalPolicy?: 'immediate' | 'default' | 'after';
  /** Dismiss after timestamp (when dismissalPolicy is 'after') */
  dismissAfter?: number;
}

`GetAllActivitiesResult`

getAllActivitiesの実行結果。

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

`SaveImageOptions`

画像を保存するためのオプション。

export interface SaveImageOptions {
  /** Base64 encoded image data */
  imageData: string;
  /** Name to save the image as */
  name: string;
  /** JPEG compression quality (0-1, default 0.8) */
  compressionQuality?: number;
}

`SaveImageResult`

画像の保存結果。

export interface SaveImageResult {
  /** Whether the save was successful */
  success: boolean;
  /** Saved image name */
  imageName: string;
}

`RemoveImageOptions`

画像を削除するためのオプション。

export interface RemoveImageOptions {
  /** Name of the image to remove */
  name: string;
}

`RemoveImageResult`

画像の削除結果。

export interface RemoveImageResult {
  /** Whether the removal was successful */
  success: boolean;
}

`ListImagesResult`

画像一覧取得の結果。

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

`TimerSequenceOptions`

タイマーシーケンスを開始するためのオプション。

export interface TimerSequenceOptions {
  /** Array of steps in the sequence */
  steps: TimerStep[];
  /** Overall title for the sequence (e.g., "HIIT Workout", "Tabata") */
  title?: string;
  /** Whether to loop the sequence when complete */
  loop?: boolean;
  /** Number of times to loop (if loop is true, 0 means infinite) */
  loopCount?: number;
  /** Play sound on step change (default: true) */
  soundEnabled?: boolean;
  /** Vibrate on step change (default: true) */
  vibrateEnabled?: boolean;
  /** Play countdown beeps in last 3 seconds (default: true) */
  countdownBeeps?: boolean;
  /** Deep link URL when tapping the notification/activity */
  tapUrl?: string;
  /** Keep screen on during timer (Android only, default: false) */
  keepScreenOn?: boolean;
}

Source of Truth

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

Getting Startedの続きを進める

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

スタートガイド

インストール

iOSのセットアップ

要件

1. Widget Extensionの作成

2. Live Activitiesを有効にする

3. 画像共有のためのApp Group設定

4. Deep Link の設定

5. オプション: サーバー駆動型アップデートを有効にする

ネイティブ設定チェックリスト

インポート

クイックスタート

例: startActivity

例: updateActivity

よくある落とし穴

API の概要

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState