ガイド
Capacitor で Live Activities を使う方法
@capgo/capacitor-live-activities の使用
iOS の Live Activities を管理するための Capacitor Live Activities プラグインインターフェース。
インストール
bun add @capgo/capacitor-live-activities
bunx cap sync
iOSのセットアップ
プラグインのインストールと同期だけでは、ネイティブの Live Activity UI は作成されません。呼び出す前に、 startActivityXcode で ActivityKit の設定を行ってください：
- 実行
bunx cap open ios. - 他の依存関係用の Widget Extension ターゲットを選択し、以下を有効にします： Live Activityを含める.
- アプリと Widget Extension のデプロイターゲットを iOS 16.1 以降に設定してください。
- Extension がメインアプリに埋め込まれていることを確認してください。
- また、
ActivityConfigurationを Extension のWidgetBundleに登録し、ロック画面および Dynamic Island のすべての表示に対応させてください。 - 追加
NSSupportsLiveActivitiesメインアプリターゲットのInfo.plist.
<key>NSSupportsLiveActivities</key>
<true/>
ターゲットを追加するだけでは不十分です。ネイティブアプリまたはプラグインからActivityKitのrequest、update、end APIを呼び出す必要があります。Widget Extensionには、SwiftUI code が、それらの呼び出しで使用される同じ ActivityAttributes コンテンツ状態をデコードして描画できるように含まれている必要があります。ActivityKitの共有モデルをメインアプリとWidget Extensionの両方のターゲットに含めてください。Xcodeが生成するLive Activityテンプレートは、このプラグインに渡されたJSONレイアウトを自動的に描画しません。拡張機能にも互換性のあるネイティブレイアウトレンダラーが必要です。
共有画像
画像管理メソッドを使う場合は、 App Groups CapabilityをメインアプリとWidget Extensionの両方のターゲットに追加してください。プラグインが期待する正確な識別子を使って、両方のターゲットで同じグループを有効にしてください：
group.<MAIN_APP_BUNDLE_ID>.liveactivities
Live Activity拡張機能はネットワークにアクセスできません。リモート画像はメインアプリでダウンロードし、共有App Groupに保存し、 saveImageその後、レイアウトから保存した画像を参照してください。バンドルされたアセットもWidget Extensionターゲットに属している必要があります。
ディープリンクとPushアップデート
- 使用されるカスタムURLスキームを登録してください
behavior.widgetUrlまたはtapUrlメインアプリターゲットの Info > URL Types の設定にスキームを追加します。 - サーバー駆動のアップデートを行うには、 プッシュ通知 capabilityを追加し、APNsを使用したActivityKitのpush-token処理を実装してください。
- 追加
NSSupportsLiveActivitiesFrequentUpdatesアプリで頻繁にActivityKitのpushアップデートが必要な場合にのみ行ってください。
Push Notificationsのcapabilityを有効にするだけでは不十分です。サーバー駆動のアップデートには、ネイティブでのトークン処理とAPNsバックエンドが必要です。
ActivityKitでは、静的および動的なLive Activityデータの合計サイズは4 KBに制限されています。Dynamic Islandは対応しているデバイスモデルでのみ表示され、その他のデバイスではロック画面に表示されます。
このプラグインで利用可能な機能
areActivitiesSupported- このデバイスが Live Activities に対応しているか確認します。iOS 16.1 以上かつデバイスのサポートが必要です。startActivity- 指定したレイアウトとデータで新しい Live Activity を開始します。updateActivity- 既存の Live Activity を新しいデータで更新します。endActivity- Live Activity を終了します。
使用例
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
});
リファレンス全文
- GitHub: https://github.com/Cap-go/capacitor-live-activities/
- ドキュメント: /docs/plugins/live-activities/
@capgo/capacitor-live-activities の使用から続ける
使用している場合 @capgo/capacitor-live-activities の使用 ネイティブメディアとインターフェースの挙動を計画するには、次と連携させてください @capgo/capacitor-live-activities @capgo/capacitor-live-activities の実装の詳細については、 スタートガイド スタートガイドの実装詳細については、 @capgo/capacitor-video-playerの使用方法 @capgo/capacitor-video-player の使い方におけるネイティブ機能については、 @capgo/capacitor-video-player @capgo/capacitor-video-player の実装の詳細、および @capgo/capacitor-native-navigation の活用 @capgo/capacitor-native-navigation. の使い方におけるネイティブ機能については