Getting Started

インストール

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

Manual Setupを使用する場合は、以下のコマンドを実行してプラグインをインストールし、以下のプラットフォーム固有の指示に従ってください。

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

iOSセットアップ

プラグインをインストールして同期しても、ネイティブのライブ アクティビティ UI は作成されません。 ActivityKit は、ライブ アクティビティの構成を登録するウィジェット拡張機能が必要です。 startActivity 要件

要件

• iOS デバイスまたは互換性のあるシミュレーターでテストしてください。ダイナミック アイランドはサポートされるデバイス モデルでのみ表示されます。 他のデバイスではロック画面のプレゼンテーションが使用されます。
• ActivityKit データの静的とダイナミックの組み合わせを、Apple の 4 KB の制限以下に保ちます。
• 1. ウィジェット拡張機能を作成する

ウィジェット拡張機能を作成する

ターミナル画面

bunx cap open ios

次の手順を実行してください。

1. 選択 ファイル > 新規作成 > ターゲット.
2. 追加する ウィジェット拡張.
3. 有効 ライブアクティビティを含める.
4. 無効 設定のインテントを含める アプリが設定可能なウィジェットも必要な場合、除外します。
5. 生成された拡張を主なアプリのターゲットに埋め込む

Widget Extensionは、以下の内容を含まなければなりません。 ActivityConfiguration と登録する必要があります。 WidgetBundle。必要なLive Activityのプレゼンテーションをすべて提供する必要があります:

• ロック画面
• ダイナミックアイランド拡張
• ダイナミックアイランドコンパクト(先頭と末尾)
• ダイナミックアイランド最小

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 とコンテンツステートをデコードおよびレンダリングできるSwiftUI__CAPGO_KEEP_0__が含まれている必要があります。両方の主アプリとWidget Extensionのターゲットに共有されるActivityKitのモデルを含める必要があります。Xcodeが生成したLive Activityのテンプレートは、このプラグインに渡されたJSONレイアウトを自動的にレンダリングしません。拡張機能には、互換性のあるネイティブレイアウトレンダラーも必要です。

2. Live Activitiesを有効にする

主アプリのターゲットの Info.plist:

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

プロジェクトが自体を生成する場合 Info.plist, 以下の追加 ライブアクティビティをサポート Boolean値が YES の主なアプリターゲットのカスタムiOSターゲットプロパティの代わりに

3. 共有イメージ用のアプリーグループを設定

App Groupは、 saveImage, removeImage, listImages、または cleanupImagesを使用する場合にのみ必要です。 プラグインは、主なアプリバンドル識別子からApp Group識別子を取得します。このフォーマットが正確に使用されます:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

例えば、バンドル識別子を持つアプリ com.example.delivery は次のように使用する必要があります:

group.com.example.delivery.liveactivities

Xcodeで、 App Groups 機能を両方のターゲット（主アプリとWidget Extension）に追加し、両方のターゲットで同じ識別子を有効にします。

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

4. ディープリンクの設定

使用する場合 behavior.widgetUrl またはタイマーシーケンス tapUrl, メインアプリでURLスキームまたはUniversal Linkを登録する必要があります。カスタムスキームの例として myapp://order/12345、メインアプリのターゲットの下にスキームを追加してください。 Info > URLタイプ 設定。

5. Server-Driven Updatesを有効にすることがオプションです。

Push Notificationsは、ローカルアップデートをアプリが開始したり終了したりするために必要ありません。サーバーからLive Activitiesを開始、更新、または終了するには:

• メインアプリのターゲットに Push Notifications capabilityを追加してください。
• ActivityKitのプッシュトークンを取得し、サーバーに送信してください。
• ActivityKitの通知をAPNsを使用して送信するには liveactivity プッシュタイプを使用してください。
• 追加 NSSupportsLiveActivitiesFrequentUpdates 主アプリケーションに追加する Info.plist 利用ケースによっては頻繁なプッシュ更新が必要な場合のみ

ActivityKitのプッシュトークンは標準のユーザー通知デバイストークンとは別です。 Push通知の機能を有効にするだけでは十分ではなく、サーバーから推奨される更新にはネイティブのトークンハンドリングとAPNsバックエンドが必要です。

ネイティブセットアップチェックリスト

呼び出す前に startActivity有効であることを確認してください。

• NSSupportsLiveActivities は、主アプリケーション目標に有効になっていることを確認してください。
• ウィジェット拡張は、タイプを登録する ActivityConfiguration.
• ネイティブActivityKit実装とウィジェット拡張は同じ ActivityAttributes タイプを使用します。
• iOS 16.1 またはそれ以上のアプリとウィジェット拡張の展開対象です。
• iOS の設定でアプリに Live Activities が有効になっています。
• 共有イメージを使用する場合、両方の展開対象でマッチングした App Group が有効になっています。
• または widgetUrl Capacitor のライブアップデートの代替手段は、 tapUrl 登録されています。

インポート

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

API の概要

areActivitiesSupported

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

指定されたレイアウトとデータで新しいライブアクティビティを開始します。

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!'
  }
});

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

共有コンテナに保存された画像の一覧を表示します。

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とダイナミックアイランドに表示されます。 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

活動がサポートされているかどうかの確認結果

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

アクティビティの開始結果

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

UpdateActivityOptions

ライブ アクティビティの更新オプション

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

ライブアクティビティを終了するためのオプション。

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.tsAPIがアップストリームで変更された場合に、パブリック APIを再度同期してください。

「始めから始める」

あなたが 始めから始める ダッシュボードとAPIの作業を計画する場合に使用している場合、 プラグインのcapgoとcapacitor-live-activities プラグインのcapgoとcapacitor-live-activities API アサター for the implementation detail in API Overview, アサターにした バームイントにはアサター アサターです API Keys for the implementation detail in API Keys, and アサタータータエンにした バームイントにはアサタータータエンです