Getting Started

このプラグインのインストール手順と完全なマークダウンガイドを含むセットアップコマンドをコピーしてください。

        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.

インストール

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

iOSセットアップ

__CAPGO_KEEP_0__をインストールして同期すると、ネイティブのライブアクティビティUIを作成しない。ActivityKitは、ライブアクティビティの構成を登録するWidget Extensionが必要です。 startActivity 表示できるものがない。

要件

__CAPGO_KEEP_0__の両方のアプリターゲットとWidget ExtensionターゲットでiOS 16.1またはそれ以降を使用します。
__CAPGO_KEEP_0__でiOSデバイスまたは互換性のあるシミュレータでテストします。ダイナミックアイランドはサポートされるデバイスモデルのみで表示され、他のデバイスではロック画面のプレゼンテーションを使用します。
__CAPGO_KEEP_0__の組み合わせた静的とダイナミックのActivityKitデータは、Appleの4KBの制限以下に保つ必要があります。

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

bunx cap open ios

次に:

選択 ファイル > 新規作成 > ターゲット.
追加の ウィジェット拡張.
有効 ライブアクティビティを含める.
無効 Include Configuration Intent アプリがカスタマイズ可能なウィジェットも必要な場合を除いて
生成された拡張機能をメインアプリのターゲットに埋め込むようにします。

ウィジェット拡張機能には ActivityConfiguration が含まれている必要があります。 WidgetBundleウィジェット拡張機能には

に登録する必要があります。
Lock Screen
ダイナミックアイランド拡張
ダイナミックアイランドコンパクト(先頭と末尾)

Adding the target alone is not sufficient. The native app or plugin must call ActivityKit’s request, update, and end APIs. The extension must contain SwiftUI code that can decode and render the same ActivityAttributes ターゲットを追加するだけでは不十分です。ネイティブアプリまたはプラグインはActivityKitのrequest、update、endAPIを呼び出す必要があります。拡張機能には、ActivityKitのAPIで呼び出されたJSONレイアウトをデコードしてレンダリングできるSwiftUI__CAPGO_KEEP_0__が含まれている必要があります。共有ActivityKitモデルをメインアプリとウィジェット拡張機能の両方のターゲットに含める必要があります。Xcodeが生成したライブアクティビティテンプレートは、このプラグインに渡されたJSONレイアウトを自動的にレンダリングしません。拡張機能にも互換性のあるネイティブレイアウトレンダラーが必要です。

2. ライブアクティビティを有効にする

主アプリのターゲットに次のキーを追加する Info.plist:

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

プロジェクトが自ら Info.plistを生成する場合、 を追加する。 ライブアクティビティをサポートする YES 値が

の場合。

3. 共有画像用のアプリグループを設定する saveImage, removeImage, listImages、または cleanupImagesコピー

group.<MAIN_APP_BUNDLE_ID>.liveactivities

コピー com.example.delivery 主アプリのバンドル識別子が

group.com.example.delivery.liveactivities

コピー Xcodeで、両方のターゲットに App Groups

機能を追加し、両方のターゲットに同じ識別子を有効にします。

ライブアクティビティ拡張機能はネットワークにアクセスできません。リモート画像をダウンロードする主アプリで、共有App Groupに保存し、ライブアクティビティから参照してください。バンドル画像の場合も、Widget Extensionのアセットのターゲットメンバーシップを有効にします。

Capgoを使用する場合 behavior.widgetUrl __CAPGO_KEEP_0__またはタイマーシーケンス tapUrl、メインアプリにURLスキームまたはUniversal Linkを登録します。カスタムスキームの場合、例えば myapp://order/12345、メインアプリのターゲットの Info > URL Types 設定の

5. オプション: Server-Driven Updatesを有効にする

メインアプリのターゲットに

Push通知 機能を追加します。 5. Optional: Enable Server-Driven Updates
ActivityKitのプッシュトークンを取得し、サーバーに送信します。
APNsを使用してActivityKitの通知を送信するには「push type」を使用します。 liveactivity 「」に追加します。
主なアプリケーションにのみ追加してください。頻繁なプッシュ更新が必要な用途の場合。 NSSupportsLiveActivitiesFrequentUpdates ActivityKitのプッシュトークンは標準のユーザー通知デバイストークンとは別です。 Push通知の機能を有効にするだけでは十分ではなく、サーバーから更新を取得するにはネイティブのトークンハンドリングとAPNsのバックエンドが必要です。 Info.plist ネイティブセットアップチェックリスト

「ネイティブセットアップチェックリスト」のセクション

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

__CAPGO_KEEP_0__ startActivity__CAPGO_KEEP_0__

NSSupportsLiveActivities __CAPGO_KEEP_0__
ウィジェット拡張機能は埋め込まれ、<__CAPGO_KEEP_0__>を登録します。 ActivityConfiguration.
<__CAPGO_KEEP_0__>のネイティブ実装とウィジェット拡張機能は同じ<__CAPGO_KEEP_1__>を使用します。 ActivityAttributes <__CAPGO_KEEP_2__>。
アプリとウィジェット拡張機能のデプロイ対象はiOS 16.1または後です。
iOSの設定でアプリにライブアクティビティが有効になっています。
共有画像を使用する場合、両方の対象でマッチングのアプリグループが有効になっています。
<__CAPGO_KEEP_0__>を使用する場合、<__CAPGO_KEEP_3__>で使用される任意のカスタムURLスキームも登録されます。 widgetUrl コピー tapUrl タイトル「インポート」

コピー先のクリップボードにコピー

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

API オーバービュー

`areActivitiesSupported`

このデバイスでLiveアクティビティがサポートされているかどうかを確認します。 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アクティビティを開始します。

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アクティビティに新しいデータを更新します。

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`

ライブアクティビティを終了します。

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`

現在実行中のすべてのライブアクティビティを取得します。

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

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

`saveImage`

ライブアクティビティ用のウィジェット拡張で使用できるように共有アプリグループコンテナに画像を保存します。画像はウィジェット拡張で使用できるように共有コンテナに保存する必要があります。

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`

__CAPGO_KEEP_0__を共有コンテナ内に保存した画像をすべてリストします。

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

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

`cleanupImages`

__CAPGO_KEEP_0__を共有コンテナからすべて削除します。

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

await CapgoLiveActivities.cleanupImages();

`startTimerSequence`

__CAPGO_KEEP_0__でトレーニング/スポーツのタイマーシーケンスを開始します。 iOSではLive Activityとダイナミックアイランドに表示されます。 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`

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

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`

クリップボードにコピー

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

`StartActivityOptions`

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

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`

__CAPGO_KEEP_0__

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

真実の源

このページはプラグインの src/definitions.ts公開 API がアップストリームで変更された場合に再度同期を実行してください。

Getting Started から続けて

Capgo を使用している場合 Getting Started ダッシュボードとAPIの作業を計画するには、 Using @capgo/capacitor-live-activities Using @capgo/capacitor-live-activities APIの概要 CapacitorのAPIの実装詳細 Capacitorの__CAPGO_KEEP_0__の概要 Capacitorの__CAPGO_KEEP_0__の概要 CapacitorのAPIの概要 CapacitorのAPIの概要 Capacitorの__CAPGO_KEEP_0__の概要 Capacitorの__CAPGO_KEEP_0__の概要

Getting Started

インストール

iOSセットアップ

要件

1. Widget Extensionを作成

2. ライブ アクティビティを有効にする

の場合。

5. オプション: Server-Driven Updatesを有効にする

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

コピー先のクリップボードにコピー

API オーバービュー

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState