メインコンテンツへスキップ

Wear OSアプリの作成

GitHub

このガイドでは、Androidと同じData Layerパスを使ってCapacitorのスマートフォンアプリと通信するWear OSコンパニオンアプリを解説します。 CapgoWatchPlugin Androidの場合 (play-services-wearable).

開始前に、以下が揃っていることを確認してください:

  • デバッグ (最新安定版)
  • 既存の Capacitor Android プロジェクト (npx cap add android (必要に応じて)
  • スマートフォンとペアリングされた物理 Wear OS ウォッチ (エンドツーエンドテストに推奨)
  • 同じ署名キー (スマホアプリと Wear OS モジュールのリリースビルド用)

プラグインと Wear OS の対応関係

セクション「プラグインと Wear OS の対応関係」

スマートフォン側のプラグイン (CapgoWatchPlugin.java) は、これらの Data Layer ルートを使用します:

ルート種類目的
/capgo/messageメッセージ一方向メッセージ (スマートフォンからウォッチへ、ウォッチからスマートフォンへ)
/capgo/message/withreplyメッセージJS 経由で応答を期待するウォッチからスマートフォンへのメッセージ replyToMessage
/capgo/reply/{callbackId}メッセージウォッチへの返信ペイロード
/capgo/contextDataItem最新のアプリケーションコンテキスト (payload string に JSON を保持)
/capgo/userinfo/{uuid}DataItemキューイングされたユーザー情報 (payload string に JSON を保持)

スマートフォンは capgo_watch capability (WATCH_APP_CAPABILITY プラグイン内) でウォッチアプリを検出します。

このガイドを完了すると、Android ツリーは次のようになります:

  • ディレクトリandroid/
    • ディレクトリapp/ (phone モジュール、Capacitor ホスト)
      • …
    • ディレクトリwear/ (新しい Wear OS モジュール)
      • ディレクトリsrc/main/
        • AndroidManifest.xml
        • java/…/WearMainActivity.kt
        • java/…/CapgoWearBridge.kt
        • res/values/wear.xml
    • settings.gradle

ステップ 1: Wear OS モジュールの追加

「Step 1: Add a Wear OS module」セクション
  1. 次を開きます: android Android Studio 内のフォルダ(リポジトリのルートではありません)。

  2. 選択: ファイル → 新規 → 新規モジュール…

  3. 選択します Wear OS → 空の Wear アプリ (または Wear OS アプリ Compose を好む場合は、それを使用してください)。

  4. モジュールを設定します:

    • モジュール名: wear (または任意の名前)
    • パッケージ名: 可能な限り、スマートフォンアプリの namespace と一致させます
    • 最小 SDK: プロジェクトに合わせてください(プラグイン minSdk は 24 です)
  5. クリック 完了 Gradle syncを実行します。

Capacitorプラグインはすでに以下に依存しています: com.google.android.gms:play-services-wearable:18.2.0。あなたの wear モジュールには同じ API が必要です。

では wear/build.gradle (または wear/build.gradle.kts) を追加します:

dependencies {
implementation "com.google.android.gms:play-services-wearable:18.2.0"
// Your UI dependencies (Compose, etc.)
}

編集後、Gradle を同期してください。

必ず settings.gradle wear モジュールが含まれています:

include ':app'
include ':wear'

実行 npx cap sync android ネイティブモジュールを変更した場合は、Capacitor プロジェクトから変更を反映し、Android Studio で再ビルドします。

ステップ 3: 宣言する capgo_watch capability

セクション「ステップ 3: capgo_watch capability の宣言」

作成します wear/src/main/res/values/wear.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
<string-array name="android_wear_capabilities" translatable="false" tools:ignore="UnusedResources">
<item>capgo_watch</item>
</string-array>
</resources>

これにより、電話機プラグインは isWatchAppInstalled capability をクエリする際に capgo_watch.

同じ applicationId を電話機アプリと Wear モジュールの両方で使用します。設定は wear/build.gradle (および、これに一致する android/app/build.gradle):

android {
defaultConfig {
applicationId "com.example.myapp" // must match android/app
}
}

例 wear/src/main/AndroidManifest.xml スケルトン:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-feature android:name="android.hardware.type.watch" />
<application
android:allowBackup="true"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@android:style/Theme.DeviceDefault">
<activity
android:name=".WearMainActivity"
android:exported="true"
android:taskAffinity=""
android:theme="@android:style/Theme.DeviceDefault">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>

ステップ 5: Wear 側のブリッジ (Kotlin)

「ステップ 5: Wear 側ブリッジ (Kotlin)」セクション

作成します CapgoWearBridge.kt Wear パッケージ内に。これは CapgoWatchPlugin.java.

電話機プラグインは、不透明な callbackId をそれぞれに割り当て /capgo/message/withreply し、応答を /capgo/reply/{callbackId}。ウォッチは事前にそのIDを把握していません。並行リクエストの場合、 requestId をJSONペイロードに含め、スマートフォンから replyToMessageでそれを返し、ウォッチ側ではそのフィールドでハンドラーをキーにしてください。

package com.example.myapp.wear
import android.content.Context
import android.net.Uri
import android.util.Log
import com.google.android.gms.wearable.CapabilityClient
import com.google.android.gms.wearable.DataClient
import com.google.android.gms.wearable.DataEvent
import com.google.android.gms.wearable.DataEventBuffer
import com.google.android.gms.wearable.DataMapItem
import com.google.android.gms.wearable.MessageClient
import com.google.android.gms.wearable.MessageEvent
import com.google.android.gms.wearable.PutDataMapRequest
import com.google.android.gms.wearable.Wearable
import org.json.JSONObject
import java.nio.charset.StandardCharsets
import java.util.UUID
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
class CapgoWearBridge(private val context: Context) :
MessageClient.OnMessageReceivedListener,
DataClient.OnDataChangedListener {
companion object {
private const val TAG = "CapgoWearBridge"
const val CAPABILITY = "capgo_watch"
const val PATH_MESSAGE = "/capgo/message"
const val PATH_MESSAGE_WITH_REPLY = "/capgo/message/withreply"
const val PATH_REPLY_PREFIX = "/capgo/reply/"
const val PATH_CONTEXT = "/capgo/context"
const val PATH_USER_INFO_PREFIX = "/capgo/userinfo/"
}
private val executor = Executors.newSingleThreadExecutor()
private val timeoutScheduler = Executors.newSingleThreadScheduledExecutor()
private val messageClient = Wearable.getMessageClient(context)
private val dataClient = Wearable.getDataClient(context)
private val nodeClient = Wearable.getNodeClient(context)
var onMessage: ((JSONObject) -> Unit)? = null
var onContext: ((JSONObject) -> Unit)? = null
var onUserInfo: ((JSONObject) -> Unit)? = null
fun start() {
messageClient.addListener(this)
dataClient.addListener(this)
Wearable.getCapabilityClient(context)
.addLocalCapability(CAPABILITY)
}
fun stop() {
messageClient.removeListener(this)
dataClient.removeListener(this)
pendingReplyTimeouts.values.forEach { it.cancel(false) }
pendingReplyTimeouts.clear()
pendingReplyHandlers.clear()
timeoutScheduler.shutdownNow()
}
fun sendMessage(data: JSONObject, onError: (String) -> Unit = {}) {
executor.execute {
try {
val nodes = com.google.android.gms.tasks.Tasks.await(nodeClient.connectedNodes)
val payload = data.toString().toByteArray(StandardCharsets.UTF_8)
for (node in nodes) {
messageClient.sendMessage(node.id, PATH_MESSAGE, payload).let {
com.google.android.gms.tasks.Tasks.await(it)
}
}
} catch (e: Exception) {
Log.e(TAG, "sendMessage failed", e)
onError(e.message ?: "sendMessage failed")
}
}
}
private val pendingReplyHandlers = ConcurrentHashMap<String, (JSONObject) -> Unit>()
private val pendingReplyTimeouts = ConcurrentHashMap<String, java.util.concurrent.ScheduledFuture<*>>()
private val outboundUserInfoPaths = ConcurrentHashMap.newKeySet<String>()
fun sendMessageWithReply(
data: JSONObject,
onReply: (JSONObject) -> Unit,
onError: (String) -> Unit = {},
) {
executor.execute {
val requestId = UUID.randomUUID().toString()
try {
val nodes = com.google.android.gms.tasks.Tasks.await(nodeClient.connectedNodes)
if (nodes.isEmpty()) {
onError("No connected phone node")
return@execute
}
val payloadJson = JSONObject(data.toString()).apply {
put("requestId", requestId)
}
pendingReplyHandlers[requestId] = onReply
val timeout = timeoutScheduler.schedule(
{
if (pendingReplyHandlers.remove(requestId) != null) {
pendingReplyTimeouts.remove(requestId)
onError("Reply timed out after 5 minutes")
}
},
5,
TimeUnit.MINUTES,
)
pendingReplyTimeouts[requestId] = timeout
val node = nodes.first()
com.google.android.gms.tasks.Tasks.await(
messageClient.sendMessage(
node.id,
PATH_MESSAGE_WITH_REPLY,
payloadJson.toString().toByteArray(StandardCharsets.UTF_8),
),
)
} catch (e: Exception) {
pendingReplyHandlers.remove(requestId)
pendingReplyTimeouts.remove(requestId)?.cancel(false)
Log.e(TAG, "sendMessageWithReply failed", e)
onError(e.message ?: "sendMessageWithReply failed")
}
}
}
fun updateApplicationContext(contextData: JSONObject, onError: (String) -> Unit = {}) {
executor.execute {
try {
val request = PutDataMapRequest.create(PATH_CONTEXT)
request.dataMap.putString("payload", contextData.toString())
request.setUrgent()
com.google.android.gms.tasks.Tasks.await(dataClient.putDataItem(request.asPutDataRequest()))
} catch (e: Exception) {
Log.e(TAG, "updateApplicationContext failed", e)
onError(e.message ?: "updateApplicationContext failed")
}
}
}
fun transferUserInfo(userInfo: JSONObject, onError: (String) -> Unit = {}) {
executor.execute {
val path = PATH_USER_INFO_PREFIX + UUID.randomUUID()
try {
outboundUserInfoPaths.add(path)
val request = PutDataMapRequest.create(path)
request.dataMap.putString("payload", userInfo.toString())
request.setUrgent()
com.google.android.gms.tasks.Tasks.await(dataClient.putDataItem(request.asPutDataRequest()))
} catch (e: Exception) {
outboundUserInfoPaths.remove(path)
Log.e(TAG, "transferUserInfo failed", e)
onError(e.message ?: "transferUserInfo failed")
}
}
}
override fun onMessageReceived(event: MessageEvent) {
val path = event.path
val json = try {
JSONObject(String(event.data, StandardCharsets.UTF_8))
} catch (e: Exception) {
Log.w(TAG, "Ignoring non-JSON message on $path", e)
return
}
when {
path == PATH_MESSAGE -> onMessage?.invoke(json)
path.startsWith(PATH_REPLY_PREFIX) -> {
val requestId = json.optString("requestId", "")
if (requestId.isNotEmpty()) {
pendingReplyTimeouts.remove(requestId)?.cancel(false)
pendingReplyHandlers.remove(requestId)?.invoke(json)
}
}
}
}
override fun onDataChanged(dataEvents: DataEventBuffer) {
for (event in dataEvents) {
if (event.type != DataEvent.TYPE_CHANGED) continue
val item = event.dataItem
val path = item.uri.path ?: continue
val map = DataMapItem.fromDataItem(item).dataMap
val payload = map.getString("payload", "{}")
val json = try {
JSONObject(payload)
} catch (e: Exception) {
Log.w(TAG, "Ignoring non-JSON DataItem on $path", e)
continue
}
when {
path == PATH_CONTEXT -> onContext?.invoke(json)
path.startsWith(PATH_USER_INFO_PREFIX) -> {
if (outboundUserInfoPaths.remove(path)) {
continue
}
onUserInfo?.invoke(json)
dataClient.deleteDataItems(item.uri)
}
}
}
}
}

でブリッジを配線し WearMainActivity.kt:

class WearMainActivity : ComponentActivity() {
private lateinit var bridge: CapgoWearBridge
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
bridge = CapgoWearBridge(applicationContext)
bridge.onMessage = { json -> Log.d("Wear", "phone message: $json") }
bridge.onContext = { json -> Log.d("Wear", "context: $json") }
bridge.onUserInfo = { json -> Log.d("Wear", "userInfo: $json") }
bridge.start()
setContent { /* your Compose UI */ }
}
override fun onDestroy() {
bridge.stop()
super.onDestroy()
}
}

使用する applicationContext クライアントを構築する際に、リスナーが設定変更後も生存するようにします。

スマートフォンアプリにプラグインをインストールして同期します(iOSと同じ手順):

import { CapgoWatch } from '@capgo/capacitor-watch';
export async function setupWatchListeners() {
await CapgoWatch.addListener('messageReceived', (event) => {
console.log('Wear message:', event.message);
});
await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
const requestId = event.message.requestId;
await CapgoWatch.replyToMessage({
callbackId: event.callbackId,
data: { requestId, ok: true, echo: event.message },
});
});
await CapgoWatch.addListener('applicationContextReceived', (event) => {
console.log('Wear context:', event.context);
});
await CapgoWatch.addListener('userInfoReceived', (event) => {
console.log('Wear userInfo:', event.userInfo);
});
}
export async function pingWatch() {
const info = await CapgoWatch.getInfo();
if (!info.isSupported) {
console.warn('Wear OS APIs not available on this device');
return;
}
if (!info.isReachable) {
console.warn('No connected Wear OS nodes');
return;
}
await CapgoWatch.sendMessage({
data: { action: 'ping', at: Date.now() },
});
}

呼び出す setupWatchListeners() アプリのブートストラップの初期段階(例えば、 platform.ready()).

ステップ 7: ビルド、インストール、テスト

セクション「ステップ 7: ビルド、インストール、テスト」
  1. 次の スマートフォン app ラン設定を作成し、実機の Android スマートフォンにインストールします。

  2. 次の wear ラン設定を作成し、ペアリングされたウォッチ(またはスマートフォンエミュレーターにリンクされたウォッチエミュレーター)にインストールします。

  3. 確認 getInfo() スマートフォン上で:

    • isSupported: true Google Play サービスと Wearable API が利用可能な場合
    • isReachable: true 少なくとも1つのノードが接続された場合
    • isWatchAppInstalled: true ウォッチがアドバタイズした場合 capgo_watch
  4. 送信 CapgoWatch.sendMessage スマートフォンから送信し、確認します bridge.onMessage ウォッチ上で。

  5. ウォッチから送信します sendMessageWithReply 確認します messageReceivedWithReply と replyToMessage が配信されます /capgo/reply/{callbackId}.

  6. テスト updateApplicationContext と transferUserInfo 上記のDataItemパスを使用して双方向に。

isSupported: false 実機スマートフォンで

  • Google Play サービスが未インストールまたは古いバージョンです
  • デバイスで API が利用できません

isReachable: false ウォッチはペアリング済みですが

  • Bluetoothが無効、またはウォッチアプリが最近起動していない
  • 不一致 applicationId またはモジュール間の署名キーが異なる
  • 現在、Google Play servicesに接続されているWear OSノードがありません

isWatchAppInstalled: false

  • ウォッチにWear companion APKがインストールされていません
  • 不足 capgo_watch 内のエントリ wear.xml
  • Capabilityが同期されていません:capabilities変更後にwear APKを再インストールしてください

メッセージが届きません

  • パスは完全に一致する必要があります(/capgo/message、カスタムプレフィックスは不可)
  • ペイロードはUTF-8形式のJSONテキストである必要があります(プラグインは JSONObject / JSObject 文字列を使用します)

Replyはウォッチには返されません

  • Phone側から呼び出す必要があります replyToMessage を使用して、 callbackId と messageReceivedWithReply
  • 同じものも requestId reply JSONに含めてください(ウォッチが並行リクエストを紐付ける場合)
  • 保留中のreplyは次で期限切れになります 5分 Androidでは(プラグイン定数 PENDING_REPLY_TTL_MS)

「Creating a Wear OS app」から続ける

「Wear OS アプリの作成から続ける」セクション

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