スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

bunx 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-watch` plugin in my project.

手動セットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

1. パッケージをインストール

   bun add @capgo/capacitor-watch

2. ネイティブプロジェクトと同期

   bunx cap sync

3. プラグインの設定

   基本的な使用例:

   import { CapgoWatch } from '@capgo/capacitor-watch';
   
   // Check watch connectivity status
   const info = await CapgoWatch.getInfo();
   console.log('Watch paired:', info.isPaired);
   console.log('Watch reachable:', info.isReachable);
   
   // Listen for messages from watch
   await CapgoWatch.addListener('messageReceived', (event) => {
     console.log('Message from watch:', event.message);
   });

   Watchへメッセージを送信:

   // Check if watch is reachable first
   const info = await CapgoWatch.getInfo();
   if (info.isReachable) {
     await CapgoWatch.sendMessage({
       data: { action: 'refresh', timestamp: Date.now() }
     });
   }

   iOSと

   iOSでの必須設定:

   1. XcodeでiOSアプリにWatchConnectivityのCapabilityを追加します
   2. XcodeプロジェクトにwatchOSアプリのターゲットを作成します
   3. watchOSアプリにWatchConnectivityを実装します（詳細は後述の「Watch Appの実装」を参照）

   プラグインのロード時に、WCSessionが自動的にアクティブ化されます。

   Android

   Wear OSの必須セットアップ:

   1. 他の依存関係用の Wear OSモジュールを Androidプロジェクトに追加します（電話アプリと applicationId 署名も同じにする必要があります）。
   2. wearモジュール内で capgo_watch capabilityを宣言してください（詳細は 「Wear OSアプリの作成」を参照）).
   3. プラグインのパスを使用して、watch側でData Layerリスナーを実装します（/capgo/message, /capgo/context、その他）

   Phoneプラグインは、ロード時にWearable API リスナーを登録します。次を使用します: getInfo() 接続されているノードと、ウォッチアプリが検出されるかを確認するために使用します。

   詳細な手順: Wear OSアプリの作成.

4. 返信が必要なメッセージの処理

   // Listen for messages that need a response
   await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
     console.log('Request from watch:', event.message);
   
     // Process the request
     const result = await processWatchRequest(event.message);
   
     // Send reply back to watch (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         result,
       },
     });
   });

5. アプリの状態を同期

   // Update application context (latest value only)
   await CapgoWatch.updateApplicationContext({
     context: {
       theme: 'dark',
       userId: '123',
       lastSync: Date.now()
     }
   });
   
   // Listen for context updates from watch
   await CapgoWatch.addListener('applicationContextReceived', (event) => {
     console.log('Context from watch:', event.context);
   });

6. ユーザー情報を確実に転送

   // Queue data for reliable delivery (even when watch is offline)
   await CapgoWatch.transferUserInfo({
     userInfo: {
       recordId: '456',
       action: 'created',
       data: { name: 'Item 1' }
     }
   });
   
   // Listen for user info transfers
   await CapgoWatch.addListener('userInfoReceived', (event) => {
     console.log('User info from watch:', event.userInfo);
   });

7. 接続状態の監視

   // Track reachability changes
   await CapgoWatch.addListener('reachabilityChanged', (event) => {
     console.log('Watch reachable:', event.isReachable);
     if (event.isReachable) {
       // Watch is now available for interactive messaging
     }
   });
   
   // Track session activation state
   await CapgoWatch.addListener('activationStateChanged', (event) => {
     // 0 = notActivated, 1 = inactive, 2 = activated
     console.log('Session state:', event.state);
   });

クイックスタート

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

例: updateApplicationContext

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

例: transferUserInfo

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

よくある落とし穴

• リスナー: 画面がアンマウントされたらハンドルを削除します。
• ネイティブ同期: 実行 bunx cap sync プラグインのアップグレード後。
• 信頼できる情報源: 信頼 src/definitions.ts GitHub リポジトリ内。

Watch Appの実装

watchOSアプリではWatchConnectivityの実装が必要です。以下はSwiftUIでの実装例です。

import SwiftUI
import WatchConnectivity

@main
struct MyWatchApp: App {
    init() {
        WatchViewModel.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class WatchViewModel: NSObject, ObservableObject, WCSessionDelegate {
    static let shared = WatchViewModel()

    @Published var lastMessage: [String: Any] = [:]

    func activate() {
        guard WCSession.isSupported() else { return }
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    // Send message to iPhone
    func sendToPhone(_ data: [String: Any]) {
        guard WCSession.default.isReachable else {
            print("iPhone not reachable")
            return
        }
        WCSession.default.sendMessage(data, replyHandler: nil)
    }

    // Send message with reply
    func sendToPhoneWithReply(_ data: [String: Any], completion: @escaping ([String: Any]) -> Void) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(data, replyHandler: completion)
    }

    // Receive message from iPhone
    func session(_ session: WCSession, didReceiveMessage message: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = message
        }
    }

    // Receive application context
    func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = applicationContext
        }
    }

    // Required delegate methods
    func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
        print("Watch session activated: \(activationState.rawValue)")
    }
}

API リファレンス

メソッド

sendMessage(options: SendMessageOptions)

ウォッチにインタラクティブなメッセージを送信します。ウォッチが通信可能な状態である必要があります。

パラメーター:

• data: Object - ウォッチに送信するデータ

updateApplicationContext(options: UpdateContextOptions)

アプリケーションコンテキストを更新します。最新の値のみが保持されます。

パラメーター:

• context: Object - 同期するコンテキストデータ

transferUserInfo(options: TransferUserInfoOptions)

確実な配信のためにユーザー情報をキューに追加します。

パラメーター:

• userInfo: Object - 送信するユーザー情報

replyToMessage(options: ReplyMessageOptions)

返信を求めているメッセージに返信します。

パラメーター:

• callbackId: string - messageReceivedWithReply イベントのコールバック ID
• data: Object - 返信データ

getInfo()

watch の接続ステータスを取得します。

戻り値: WatchInfo 以下のプロパティを持つオブジェクト:

• isSupported: boolean - このプラットフォームで watch API が利用可能かどうか
• isPaired: boolean - Apple Watch がペアリング済み (iOS)、または少なくとも 1 つの Wear OS ノードが接続済み (Android)
• isWatchAppInstalled: boolean - Companion watch アプリがインストール済み (iOS)、または capgo_watch 機能が検出された場合 (Android)
• isReachable: boolean - 即時メッセージングのために watch に到達可能かどうか
• activationState: number - セッション状態 (iOS WCSession、Android はノード接続時に 2、それ以外は 0)

getPluginVersion()

ネイティブプラグインのバージョンを取得します。

イベント

イベント	説明
messageReceived	watchからのシンプルなメッセージ
messageReceivedWithReply	返信を待機するメッセージ (callbackIdを含む)
applicationContextReceived	watchからのコンテキスト更新
userInfoReceived	watchからのユーザー情報転送
reachabilityChanged	watchの接続状態が変更されました (iOSのみ)
activationStateChanged	セッションの有効化状態が変更されました (iOSのみ)

通信パターン

即時メッセージング (sendMessage)

• watchへの到達可能性が必要
• インタラクティブで即時性が求められる通信に最適
• watchが利用できない場合は即座に失敗します

アプリケーションコンテキスト (updateApplicationContext)

• 最新の値のみ - 前の値は上書きされます
• 現在のアプリ状態の同期に最適
• watchが利用可能になったときに配信されます

ユーザー情報の転送 (transferUserInfo)

• キューに保存され、順序通りに配信されます
• 確実に配信する必要がある重要なデータに最適
• watchが一時的に通信不能な場合でも動作します

プラットフォームに関する注意点

詳細については、 プラットフォーム対応表 プラグイン概要のメソッド別マトリクスを参照してください。

iOS (Apple Watch)

• iOS 15.0以降が必要
• WatchConnectivity frameworkを使用
• プラグインのロード時にセッションが自動的にアクティブになります
• contextおよびuser infoのバックグラウンド配信に対応
• Emitする reachabilityChanged と activationStateChanged

Android (Wear OS)

• Wear OS Data Layer を備えた Google Play services が必要です（play-services-wearableプラグインに含まれています）
• Phone と wear の APK は、同じ 同じ applicationId と 署名鍵を共有する必要があります
• Watch アプリで capability を公開する必要があります capgo_watch
• これで 決して emit reachabilityChanged または activationStateChanged; ポーリング getInfo() 必要な時に
• セットアップガイド: Wear OSアプリの作成

Web

• ブラウザではWatchメッセージングはサポートされていません
• getInfo() で解決します isSupported: false およびその他のフィールドは安全なデフォルト値に設定されます
• getPluginVersion() で解決します { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfoや replyToMessage unavailable エラーで reject する
• addListener Capacitor 経由でハンドルを解決する WebPluginただし、ブラウザでは watch イベントは未対応です（コールバックは実行されません）

よくあるユースケース

1. データ同期: watch とスマホのデータを同期
2. リモートコントロール: watch からスマホの機能を操作
3. 通知: watch にカスタム通知を送信
4. ヘルスケアデータ: フィットネスや健康指標を共有
5. メディアコントロール: ウォッチから音楽再生を操作
6. スマートホーム: 手元からデバイスを操作

トラブルシューティング

ウォッチに接続できません:

• ウォッチがBluetoothの範囲内にあるか確認してください
• 両方のアプリが起動しているか確認してください
• 両端末でWCSessionが有効であることを確認してください

メッセージを受信できません:

• 送信前にリスナーが登録されているか確認してください
• watch app が WCSessionDelegate を実装しているか確認してください
• 使用する transferUserInfo 確実に配信するために

セッションがアクティブにならない場合:

• Xcode で WatchConnectivity capability が追加されているか確認してください
• watch app に companion bundle ID が設定されているか確認してください
• 両方のアプリが互換性のある OS バージョンをターゲットにしているか確認してください

Getting Startedの続きを進める

使用している場合 スタートガイド ネイティブプラグインの作業を計画するには、次と連携してください： @capgo/capacitor-watch の使用方法 @capgo/capacitor-watch を使う際のネイティブ機能については、 Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、 プラグインの追加または更新 プラグインの追加または更新における実装詳細については、および Ionic Enterprise プラグインの代替案 Ionic Enterprise プラグインの代替案におけるプロダクトワークフローについては。