Getting Started

インストール

CapgoのAI-Assisted Setupを使用してプラグインをインストールできます。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 デバイスまたは互換性のあるシミュレータでテストしてください。ダイナミック アイランドは、サポートされているデバイス モデルでしか表示されません。 他のデバイスでは、ロック画面のプレゼンテーションが使用されます。
• Apple の 4 KB の制限以下の静的とダイナミックの ActivityKit データを保持してください。
• If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:__CAPGO_KEEP_0__

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

ネイティブiOSプロジェクトを開く:

bunx cap open ios

次に:

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

ウィジェット拡張機能には ActivityConfiguration で登録する必要があります。 WidgetBundleLive Activityの必要なプレゼンテーションをすべて提供する必要があります:

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

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

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

主アプリのターゲットに次のキーを追加します。 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で、主アプリターゲットとウィジェット拡張ターゲットに アプリ グループ 機能を追加し、両方のターゲットに同じ識別子を有効にします。

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

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

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

5. 任意: Server-Driven Updatesを有効にする

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

• Add the Push Notifications __CAPGO_KEEP_0__機能をアプリケーションに追加します。
• ActivityKitのプッシュトークンを取得し、サーバーに送信します。
• APNsを使用してActivityKitの通知を送信します。 liveactivity __CAPGO_KEEP_0__タイプのプッシュ通知。
• アプリケーションに追加 NSSupportsLiveActivitiesFrequentUpdates アプリケーションに追加する必要があります。 Info.plist 頻繁にプッシュ更新が必要なケースのみに、

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

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

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

• NSSupportsLiveActivities __CAPGO_KEEP_0__はメインアプリのターゲットで有効になっています。
• ウィジェット拡張機能は埋め込まれ、ウィジェット拡張機能が登録します。 ActivityConfiguration.
• ネイティブのActivityKit実装とウィジェット拡張機能は同じ ActivityAttributes タイプです。
• アプリとウィジェット拡張機能のデプロイメントターゲットはiOS 16.1または後です。
• iOSの設定でアプリのライブアクティビティが有効になっています。
• 共有画像を使用する場合、両方のターゲットで一致するアプリグループが有効になっています。
• ウィジェット拡張機能で使用する任意のカスタムURLスキームは widgetUrl または 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ではライブアクティビティとダイナミックアイランドに表示されます。 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

__CAPGO_KEEP_0__

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

__CAPGO_KEEP_0__

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

RemoveImageOptions

__CAPGO_KEEP_0__

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

RemoveImageResult

__CAPGO_KEEP_0__

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から続けて

あなたが使用している場合 スタート APIと連携するためにダッシュボードとAPIの運用を計画する capgo/capacitor-live-activitiesを使用する capgo/capacitor-live-activitiesのネイティブ機能について APIの概要 APIの実装詳細について 導入 __CAPGO_KEEP_0__の実装詳細について APIのキー APIの実装詳細について デバイス __CAPGO_KEEP_0__の実装詳細について