Crear una app para Wear OS
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.
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).
Requisitos
Sección titulada “Prerrequisitos”Antes de comenzar, asegúrate de tener:
- Android Studio (última versión estable)
- Un proyecto Android de Capacitor existente (
npx cap add androidsi 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
Cómo el plugin se mapea a Wear OS
Sección titulada “Cómo el plugin se mapea a Wear OS”El plugin del lado del teléfono (CapgoWatchPlugin.java) usa estas rutas de la Data Layer:
| Ruta | Tipo | Propósito |
|---|---|---|
/capgo/message | Mensaje | Mensajes unidireccionales (del teléfono al reloj y del reloj al teléfono) |
/capgo/message/withreply | Mensaje | Mensajes del reloj al teléfono que esperan una respuesta de JS vía replyToMessage |
/capgo/reply/{callbackId} | Mensaje | Respuesta del teléfono al reloj |
/capgo/context | DataItem | Contexto de la aplicación más reciente (payload string contiene JSON) |
/capgo/userinfo/{uuid} | DataItem | Informació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).
Estructura del proyecto
Sección titulada “Estructura del proyecto”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
Paso 1: Añadir un módulo de Wear OS
Sección titulada «Paso 1: Añadir un módulo de Wear OS»-
Abre la
androidcarpeta en Android Studio (no la raíz del repositorio). -
Elige Archivo → Nuevo → Nuevo módulo…
-
Selecciona Wear OS → App Wear vacía (o App de Wear OS con Compose si lo prefieres).
-
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
minSdkes 24)
- Nombre del módulo:
-
Haz clic Finalizar y deja que Gradle se sincronice.
Paso 2: dependencias de Gradle
Sección titulada «Paso 2: dependencias de Gradle»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.
Paso 3: Declara el capgo_watch capacidad
Sección titulada «Paso 3: Declara la capacidad capgo_watch»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>Paso 5: Puente del lado Wear (Kotlin)
Sección titulada «Paso 5: Puente del lado Wear (Kotlin)»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.Contextimport android.net.Uriimport android.util.Logimport com.google.android.gms.wearable.CapabilityClientimport com.google.android.gms.wearable.DataClientimport com.google.android.gms.wearable.DataEventimport com.google.android.gms.wearable.DataEventBufferimport com.google.android.gms.wearable.DataMapItemimport com.google.android.gms.wearable.MessageClientimport com.google.android.gms.wearable.MessageEventimport com.google.android.gms.wearable.PutDataMapRequestimport com.google.android.gms.wearable.Wearableimport org.json.JSONObjectimport java.nio.charset.StandardCharsetsimport java.util.UUIDimport java.util.concurrent.ConcurrentHashMapimport java.util.concurrent.Executorsimport 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.
Paso 6: Capacitor en el teléfono (TypeScript)
Sección titulada “Paso 6: Capacitor en el teléfono (TypeScript)”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()).
Paso 7: Build, instalar y probar
Sección titulada “Paso 7: Build, instalar y probar”-
Selecciona el teléfono
appconfiguración de ejecución, instálalo en un teléfono Android físico. -
Selecciona el
wearconfiguración de ejecución, instálalo en el reloj emparejado (o en un emulador de reloj vinculado al emulador del teléfono). -
Confirmar
getInfo()en el teléfono:isSupported: truecuando Google Play services y Wearable API estén disponiblesisReachable: truecuando al menos un nodo esté conectadoisWatchAppInstalled: truecuando el reloj anunciacapgo_watch
-
Enviar
CapgoWatch.sendMessagedesde el teléfono y verificabridge.onMessageen el reloj. -
Envía desde el reloj con
sendMessageWithReplyy confirmamessageReceivedWithReplyademás dereplyToMessageentrega en/capgo/reply/{callbackId}. -
Probar
updateApplicationContextytransferUserInfoen ambas direcciones usando las rutas de DataItem anteriores.
Solución de problemas
Sección titulada “Solución de problemas”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
applicationIdo 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_watchentrada enwear.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/JSObjectstrings)
La respuesta nunca regresa al reloj
- El teléfono debe llamar a
replyToMessagecon elcallbackIdde losmessageReceivedWithReply - Incluye el mismo
requestIden 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)
Próximos pasos
Sección titulada “Próximos pasos”- Creación de una app para watchOS para Apple Watch y CapgoWatchSDK
- Primeros pasos para API compartido y notas de plataforma
- Ejemplos para patrones completos de la app
- Código fuente del plugin para constantes de ruta del lado del teléfono
Continúa desde Crear una app de Wear OS
Sección titulada «Continúa desde Crear una app de Wear OS»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.