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に登録する必要があります。Widget Extension は、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 レイアウトをレンダリングしません。Widget Extension も互換性のあるネイティブレイアウトレンダラーが必要です。

2. Live Activities を有効にする

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

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

プロジェクトが自らの Info.plist, を追加します ライブアクティビティをサポート の値が YES のカスタムiOSターゲットプロパティの代わりに

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

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

group.<MAIN_APP_BUNDLE_ID>.liveactivities

例えば、バンドル識別子を持つアプリ com.example.delivery は次のとおりでなければなりません。

group.com.example.delivery.liveactivities

Xcodeで、両方のターゲットであるメインアプリとウィジェット拡張ターゲットに App Groups 機能を追加し、両方のターゲットに同じ識別子を有効にします。

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

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 主アプリのターゲットに
• Widget Extensionは埋め込まれ、 ActivityConfiguration.
• ネイティブのActivityKit実装とWidget Extensionは同じ ActivityAttributes タイプを使用します。
• iOS 16.1 またはそれ以降のアプリとウィジェット拡張の展開対象
• iOS設定でアプリにライブアクティビティが有効になっている
• 共有画像を使用する場合、両方の展開対象でマッチングアプリグループが有効になっている
• __CAPGO_KEEP_0__ widgetUrl または tapUrl Capacitorライブアップデートの代替

__CAPGO_KEEP_0__

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

API Overview

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 Activitiesをすべて取得する。

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で使用するために共有アプリグループコンテナに画像を保存します。 画像はウィジェット拡張からアクセスできるように共有コンテナに保存する必要があります。

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の作業を計画している場合、APIを Using @capgo/capacitor-live-activities 「@capgo/capacitor-live-activities」 API Overview API の実装詳細 Introduction Introduction の実装詳細 API Keys API Keys の実装詳細 Devices Devices の実装詳細