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

Manual Setupを使用する場合は、以下のコマンドを実行してプラグインをインストールし、以下のプラットフォーム固有の指示に従ってください。

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);
   });

   ウォッチにメッセージを送信:

   // 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機能を追加してください
   2. XcodeプロジェクトにwatchOSアプリターゲットを作成してください
   3. watchOSアプリにWatchConnectivityを実装してください(下記のWatch App Implementationを参照してください)

   プラグインは、プラグインが読み込まれたときにWCSessionを自動的に有効にします。

   Android

   Apple WatchはiOSのみでサポートされています。Androidでは、すべてのメソッドは「Apple WatchはiOSのみでサポートされています」というエラーで拒否されます。 getInfo() メソッドは isSupported: false.

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
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: { 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);
   });

ウォッチアプリの実装

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 - メッセージを受信したときのコールバックID
• data: Object - 返信データ

getInfo()

ウォッチの接続状態を取得する

戻り値: WatchInfo オブジェクトに含まれる:

• isSupported: boolean - WatchConnectivityが利用可能か
• isPaired: boolean - ウォッチが pair済みか
• isWatchAppInstalled: boolean - ウォッチアプリがインストール済みか
• isReachable: boolean - ウォッチが接続可能か
• activationState：数値 - セッション状態 (0/1/2)

getPluginVersion()

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

イベント

イベント	説明
messageReceived	ウォッチから単純なメッセージ
messageReceivedWithReply	メッセージに返信を期待する (コールバック ID を含む)
applicationContextReceived	ウォッチからコンテキストが更新されました
userInfoReceived	ウォッチからユーザー情報が転送されました
reachabilityChanged	ウォッチの接続状態が変更されました
activationStateChanged	セッションの有効化状態が変更されました

コミュニケーションパターン

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

• ウォッチが利用可能であることを確認する必要があります
• インタラクティブでタイムセンシティブなコミュニケーションに最適
• ウォッチが利用可能でない場合に即座に失敗します

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

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

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

• 順番にキューイングされ、送信されます
• 重要なデータを送信する必要がある場合に最適
• 時計が一時的にアクセスできない場合でも機能します

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

iOS

• iOS 15.0 以降を必要とします
• WatchConnectivity フレームワークを使用します
• __CAPGO_KEEP_0__がプラグイン読み込み時に自動的に有効になります
• __CAPGO_KEEP_0__は背景でコンテキストとユーザー情報を配信することをサポートしています

Android

• __CAPGO_KEEP_0__はサポートされていません (Apple WatchはiOSのみです)
• __CAPGO_KEEP_0__はすべてのメソッドが適切なエラーで拒否されます
• getInfo() __CAPGO_KEEP_1__ isSupported: false

Web

• Web
• __CAPGO_KEEP_3__
• getInfo() __CAPGO_KEEP_1__ isSupported: false

一般的な使用例

1. データ同期: 時計とスマートフォンのデータを同期しておけ
2. リモートコントロール: 時計からスマートフォンの機能を操作する
3. 通知: カスタム通知を時計に送信する
4. 健康データ: フィットネスと健康メトリックを共有する
5. メディアコントロール: 時計から音楽再生を操作する
6. スマートホーム腕時計からデバイスを制御する

トラブルシューティング

腕時計が到達できない:

• 腕時計がBluetoothの範囲内にあることを確認
• 両方のアプリが実行されていることを確認
• 両方の側でWCSessionが有効になっていることを確認

メッセージが受信できない:

• リスナーが送信する前に登録されていることを確認
• WCSessionDelegateを実装している腕時計アプリを確認
• 使用 transferUserInfo 確実な配達を保証する

セッションが有効化されていません:

• XcodeでWatchConnectivity機能を追加するように確認してください
• 時計アプリがコンパニオンバンドルIDを持っていることを確認してください
• 両方のアプリが互換性のあるOSバージョンをターゲットにしていることを確認してください

Getting Startedから続けてください

あなたが Getting Started ネイティブプラグインの作業を計画するために接続する ネイティブ機能の@capgo/capacitor-watch ネイティブ機能の@capgo/capacitor-watch Capgo プラグイン ディレクトリ Capgo プラグイン ディレクトリの製品ワークフローについて Capacitor プラグイン (Capgo によって提供) Capacitor プラグイン (Capgo によって提供)の実装詳細について プラグインの追加または更新 プラグインの追加または更新の実装詳細について、 Ionic Enterprise プラグインの代替 Ionic Enterprise プラグインの代替の製品ワークフローについて