始めから始めましょう

インストール

AI-Assisted セットアップを使用してプラグインをインストールできます。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 セットアップを使用する場合は、以下のコマンドを実行してプラグインをインストールし、以下のプラットフォーム固有の指示に従ってください。

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

iOS セットアップ

プラグインのインストールと同期は、ネイティブのライブ アクティビティ UI を作成しません。ActivityKit は、ライブ アクティビティの構成を登録するWidget Extension が必要です。 startActivity iOS 16.1 またはそれ以降の両方のアプリターゲットとウィジェット拡張ターゲットで使用できます。

要件

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

1. ウィジェット拡張を作成する

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

bunx cap open ios

次に:

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

ウィジェット拡張には、 ActivityConfiguration と登録する必要があります。 WidgetBundle. Live Activity のプレゼンテーションをすべて必要に応じて提供する必要があります:

• ロック画面
• Dynamic Island (拡張)
• Dynamic Island (コンパクト、先頭と末尾)
• Dynamic Island (最小)

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 2. Live Activities を有効にする

「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の機能を追加し、Widget Extensionターゲットにも同じIDを有効にします。

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

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

使用中 behavior.widgetUrl またはタイマーシーケンス tapUrlを使用する場合、 myapp://order/12345のURLスキームまたはUniversal Linkを登録する必要があります。カスタムスキームの場合、 のターゲットの「Info > URL Types」にスキームを追加します。 設定.

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

Push Notificationsは、ローカルアップデートをアプリが開始した場合にのみ必要です。サーバーからLive Activitiesを開始、更新、終了するには:

• Capacitorの プッシュ通知 機能をメインアプリに提供する能力。
• メインアプリのターゲットに機能を追加する。
• ActivityKitのプッシュトークンを取得し、サーバーに送信する。 liveactivity プッシュタイプ。
• Add NSSupportsLiveActivitiesFrequentUpdates メインアプリに追加する。 Info.plist Live Update

Cloudflare

Capacitor

Capgo startActivitycode

• NSSupportsLiveActivities API
• SDK ActivityConfiguration.
• CLI ActivityAttributes npm
• bun
• 利用ケースが頻繁なプッシュ更新を必要とする場合のみ。
• 両方のターゲットで共有イメージを使用している場合、対象のアプリグループは有効になっています。
• 使用しているカスタムURLスキームは widgetUrl または tapUrl Capacitorライブアップデートの代替

登録済みです。

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

API まとめ

areActivitiesSupported

areActivitiesSupported

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

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

共有App Group コンテナから保存された画像を削除します。

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

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

listImages

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

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

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

cleanupImages

共有App Group コンテナからすべての画像を削除します。

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

「Getting Started」から続けてください。

「Getting Started」を使用してダッシュボードと __CAPGO_KEEP_0__ の作業を計画している場合、 「Getting Started」を使用してダッシュボードと __CAPGO_KEEP_0__ の作業を計画している場合、 「@API/__CAPGO_KEEP_1__-live-activities」を使用して 「@capgo/capacitor-live-activities」を使用して 「@capgo/capacitor-live-activities」のネイティブ機能について 「@API/__CAPGO_KEEP_1__-live-activities」のネイティブ機能について 「API Overview」については、実装の詳細については「API Overview」については 概要 概要の実装詳細について API キー API キーの実装詳細について、 デバイス デバイスの実装詳細のために。