Saltar al contenido

Crear una app para Wear OS

GitHub

Esta guía te muestra cómo crear una app complementaria para Wear OS que se comunica con tu app de Capacitor para el teléfono mediante las mismas rutas de Data Layer que CapgoWatchPlugin en Android (play-services-wearable).

Antes de comenzar, asegúrate de tener:

  • Android Studio (última versión estable)
  • Un proyecto Android de Capacitor existente (npx cap add android si es necesario)
  • Un reloj Wear OS físico emparejado con el teléfono (recomendado para pruebas de extremo a extremo)
  • La misma clave de firma para las builds de release de la app del teléfono y el módulo de Wear OS

El plugin del lado del teléfono (CapgoWatchPlugin.java) usa estas rutas de la Data Layer:

RutaTipoPropósito
/capgo/messageMensajeMensajes unidireccionales (del teléfono al reloj y del reloj al teléfono)
/capgo/message/withreplyMensajeMensajes del reloj al teléfono que esperan una respuesta de JS vía replyToMessage
/capgo/reply/{callbackId}MensajeRespuesta del teléfono al reloj
/capgo/contextDataItemContexto de la aplicación más reciente (payload string contiene JSON)
/capgo/userinfo/{uuid}DataItemInformación de usuario en cola (payload string contiene JSON)

El teléfono detecta tu app de reloj con la capgo_watch capacidad (WATCH_APP_CAPABILITY en el plugin).

Tras completar esta guía, tu árbol de Android se verá así:

  • Directorioandroid/
    • Directorioapp/ (módulo de teléfono, host de Capacitor)
      • …
    • Directoriowear/ (nuevo módulo de Wear OS)
      • Directoriosrc/main/
        • AndroidManifest.xml
        • java/…/WearMainActivity.kt
        • java/…/CapgoWearBridge.kt
        • res/values/wear.xml
    • settings.gradle
  1. Abre la android carpeta en Android Studio (no la raíz del repositorio).

  2. Elige Archivo → Nuevo → Nuevo módulo…

  3. Selecciona Wear OS → App Wear vacía (o App de Wear OS con Compose si lo prefieres).

  4. Configura el módulo:

    • Nombre del módulo: wear (o el nombre que prefieras)
    • Nombre del paquete: match your phone app namespace when possible
    • Mínimo SDK: alinéalo con tu proyecto (el plugin minSdk es 24)
  5. Haz clic Finalizar y deja que Gradle se sincronice.

El plugin Capacitor ya depende de com.google.android.gms:play-services-wearable:18.2.0. Tu wear módulo necesita el mismo API.

En wear/build.gradle (o wear/build.gradle.kts), añade:

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

Sincroniza Gradle después de editar.

Ensure settings.gradle incluya el módulo wear:

include ':app'
include ':wear'

Ejecuta npx cap sync android de tu proyecto Capacitor cuando cambies módulos nativos, y luego recompila en Android Studio.

Crear 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>

Esto permite que el plugin del teléfono establezca isWatchAppInstalled cuando consulta la capacidad capgo_watch.

Paso 4: Manifiesto del módulo Wear e ID de aplicación

Sección titulada «Paso 4: Manifiesto del módulo Wear e ID de aplicación»

Usa la misma applicationId en la app del teléfono y en el módulo wear. Configúralo en wear/build.gradle (y que coincida con android/app/build.gradle):

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

Ejemplo wear/src/main/AndroidManifest.xml esqueleto:

<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>

Crear CapgoWearBridge.kt en tu paquete wear. Refleja las rutas en CapgoWatchPlugin.java.

El plugin del teléfono asigna un callbackId para cada /capgo/message/withreply y envía la respuesta en /capgo/reply/{callbackId}. El reloj nunca ve ese ID con antelación. Para solicitudes concurrentes, incluye un requestId en tu payload JSON, haz que el teléfono lo devuelva en replyToMessage, y usa ese campo como clave para los handlers del reloj.

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

Conecta el bridge en 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()
}
}

Usa applicationContext al construir los clientes para que los listeners sobrevivan a cambios de configuración.

Instala y sincroniza el plugin en la app del teléfono (igual que en 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() },
});
}

Llama a setupWatchListeners() al inicio del bootstrap de tu app (por ejemplo, después de platform.ready()).

  1. Selecciona el teléfono app configuración de ejecución, instálalo en un teléfono Android físico.

  2. Selecciona el wear configuración de ejecución, instálalo en el reloj emparejado (o en un emulador de reloj vinculado al emulador del teléfono).

  3. Confirmar getInfo() en el teléfono:

    • isSupported: true cuando Google Play services y Wearable API estén disponibles
    • isReachable: true cuando al menos un nodo esté conectado
    • isWatchAppInstalled: true cuando el reloj anuncia capgo_watch
  4. Enviar CapgoWatch.sendMessage desde el teléfono y verifica bridge.onMessage en el reloj.

  5. Envía desde el reloj con sendMessageWithReply y confirma messageReceivedWithReply además de replyToMessage entrega en /capgo/reply/{callbackId}.

  6. Probar updateApplicationContext y transferUserInfo en ambas direcciones usando las rutas de DataItem anteriores.

isSupported: false en un teléfono real

  • Servicios de Google Play ausentes o desactualizados
  • Wearable API no disponible en el dispositivo

isReachable: false pero el reloj está emparejado

  • Bluetooth desactivado o la app del reloj no se ha ejecutado recientemente
  • Diferentes applicationId o claves de firma entre módulos
  • Ningún nodo Wear OS conectado actualmente a los servicios de Google Play

isWatchAppInstalled: false

  • APK de compañía Wear no instalada en el reloj
  • Faltante capgo_watch entrada en wear.xml
  • Capacidad no sincronizada: reinstala el APK de wear tras cambiar las capacidades

Los mensajes nunca llegan

  • La ruta debe coincidir exactamente (/capgo/message, no un prefijo personalizado)
  • El payload debe ser texto JSON en UTF-8 (el plugin usa JSONObject / JSObject strings)

La respuesta nunca regresa al reloj

  • El teléfono debe llamar a replyToMessage con el callbackId de los messageReceivedWithReply
  • Incluye el mismo requestId en el JSON de respuesta si el reloj correlaciona solicitudes concurrentes
  • Las respuestas pendientes expiran después de 5 minutos en Android (constante del plugin PENDING_REPLY_TTL_MS)

Si estás usando Crear una app para Wear OS para planificar el trabajo con plugins nativos, conéctalo con Usando @capgo/capacitor-watch para la capacidad nativa en Uso de @capgo/capacitor-watch, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.