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 は、以下の Live Activity のプレゼンテーションを提供する必要があります: ActivityConfiguration Lock Screen WidgetBundleDynamic Island expanded

• Dynamic Island compact leading and trailing
• Dynamic Island minimal
• ターゲットを追加するだけでは不十分です。ネイティブアプリまたはプラグインは、ActivityKit の request、update、end API を呼び出す必要があります。拡張機能には、ActivityKit の呼び出しで使用される JSON 形式のレイアウトをデコードおよびレンダリングできる SwiftUI __CAPGO_KEEP_0__ が含まれている必要があります。主アプリと Widget Extension の両方に共有される ActivityKit のモデルを含める必要があります。Xcode によって生成される Live Activity のテンプレートは、このプラグインに渡される JSON 形式のレイアウトを自動的にレンダリングしません。拡張機能には、互換性のあるネイティブレイアウトレンダラーも必要です。
• 2. Live Activities を有効にする

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 主アプリのターゲットの

に以下のキーを追加します。

Add the following key to the main app target’s 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 Types 設定。

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

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

• メインアプリのターゲットに Push Notifications コンテキスト:Capgoマーケティングウェブサイト。役割:短いUIラベルまたはナビゲーションアイテム。メッセージキー`push_notifications` (Push Notifications)。
• capabilityを追加します。
• ActivityKitプッシュトークンを取得し、サーバーに送信します。 liveactivity ActivityKit通知をAPNsを使用して送信します。
• 追加 NSSupportsLiveActivitiesFrequentUpdates 主アプリに追加 Info.plist 主アプリに追加するのは、頻繁なプッシュ更新が必要なケースのみです。

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

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

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

• NSSupportsLiveActivities が、主アプリのターゲットに有効になっていることを確認してください。
• ウィジェット拡張は埋め込まれ、ウィジェット拡張は ActivityConfiguration.
• ネイティブのActivityKit実装とウィジェット拡張は同じ ActivityAttributes タイプを使用します。
• iOS 16.1 またはそれ以上のアプリとウィジェット拡張の展開対象
• iOS設定でアプリでライブアクティビティが有効になっている
• 共有画像を使用する場合、両方の展開対象で一致するアプリグループが有効になっている
• __CAPGO_KEEP_0__ widgetUrl または tapUrl Capacitorライブアップデートの代替

__CAPGO_KEEP_0__

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

API Overview

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

現在実行中の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では、ライブアクティビティとダイナミックアイランドに表示されます。 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がアップストリームで変更されたときに、パブリックの再同期を実行してください。

「始めてみる」から続けて

あなたが 「始めてみる」 to plan dashboard and API operations, connect it with Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, API の概要 API の実装詳細については、API の概要を参照してください。 導入 __CAPGO_KEEP_0__ の実装詳細については、導入を参照してください。 API キー API キーの実装詳細については、API キーを参照してください。 デバイス __CAPGO_KEEP_0__ の実装詳細については、デバイスを参照してください。