YieldRadar

Capítulo 01

Qué es YieldRadar y qué trae esta versión

YieldRadar es un colector de datos geográficos que trabaja sin cobertura. Los datos viven en un GeoPackage —el formato abierto de la OGC, un solo archivo .gpkg que abre QGIS, ArcGIS y GDAL sin conversión— dentro del teléfono, y salen de él cuando usted decida.

La aplicación cubre el ciclo completo: preparar el trabajo, conectar el receptor, capturar en campo, revisar, calcular y entregar. Funciona con el GPS del teléfono y con receptores GNSS externos de precisión centimétrica.

Novedades de 7.21.19

De las versiones inmediatamente anteriores conviene recordar: descarga de áreas y ruteo sin conexión (7.21.17), candado de capa por niveles, trazo y ancho de línea en la simbología, perfil del terreno accesible desde el modelo de elevación, y soporte de capas GEOMETRYCOLLECTION.

Capítulo 02

Instalación y permisos

El entregable es un APK universal: un solo archivo válido para cualquier procesador (arm64, arm32, x86 y x86_64), incluidos los espacios virtuales y clonadores de aplicaciones. Va firmado con los tres esquemas —v1, v2 y v3— porque los clonadores reempaquetan y exigen el v1.

• Copie el .apk al teléfono y ábralo. Android pedirá permiso para instalar aplicaciones de esta fuente: concédalo.
• Abra la aplicación. En el primer arranque pedirá los permisos que necesita.
• Active la licencia (capítulo 3).

Qué permisos pide y para qué

Dónde viven sus datos

En el almacenamiento público del teléfono, en la carpeta YieldRadar/ (las instalaciones antiguas conservan también AgriCien/). Dentro, una carpeta por proyecto:

YieldRadar/
  proyectos/
    Muestreo/
      Muestreo.gpkg      ← el proyecto entero: capas, entidades, atributos
      multimedia/        ← fotos, audio y vídeo adjuntos
      layers/            ← capas auxiliares importadas
  offline/               ← mapas descargados (.mbtiles) y redes viales (.roads)

Esa ruta no depende del nombre visible de la marca, a propósito: renombrar la aplicación no debe dejar sus proyectos huérfanos.

Capítulo 03

Activar la licencia

Al primer arranque aparece la pantalla de licencia. Escriba el código que recibió y toque Activar. Hace falta conexión sólo en ese momento.

Trabajar sin cobertura

Tras la activación, la licencia queda validada localmente y la aplicación abre sin red durante 30 días. Pasado ese plazo pide una reconexión, que se resuelve en segundos con datos o WiFi. Es el equilibrio entre trabajar en una finca sin señal y que una licencia no siga viva indefinidamente en un equipo perdido.

El detalle técnico —firma del veredicto, caché anti-fraude, panel— está en el capítulo 24.

Capítulo 04

Los tres modos y sus atajos

La misma aplicación, vestida para tres oficios. Los tres modos existen siempre y ninguno esconde funciones: cambian la densidad de la pantalla, el vocabulario y —desde 7.21.19— qué faena está a un toque.

Cómo se usa el atajo

Los tres botones de modo están en el mapa, arriba a la izquierda (se repliegan con la doble flecha). El activo va en naranja.

• Toque un modo distinto → cambia a ese modo, y el aviso que aparece abajo ofrece además su atajo: «Modo de interfaz: GIS · Revisar capas».
• Toque el modo en el que ya está → lanza el atajo directamente.

Qué hace cada atajo

Campo · Empezar a trabajar

Abre la sesión de captura sobre las capas activas, enciende el seguimiento GPS, despliega el panel de captura si estaba plegado y avisa: «Listo: pulse ➕ para tomar el punto en lotes». Un toque para armar, y uno por punto.

Si no hay ninguna capa activa lleva a Proyectos y lo dice. No elige la capa por usted: así es como se acaban los puntos del lote de ayer mezclados con los de hoy.

GIS · Revisar capas

Abre una hoja con todas las capas del proyecto, cada una con su número de entidades, su geometría y su candado. Al tocar una: la enciende en el mapa, la encuadra y la deja como capa de consulta, de modo que el siguiente toque sobre una entidad abre su ficha con Editar y Borrar. Manteniendo pulsada una capa se abre su tabla de atributos.

Topo · Replantear

Pregunta de dónde salen los puntos de proyecto —de una capa, de coordenadas tecleadas o siguiendo con el replanteo en curso— y entra en modo replanteo. Capítulo 13.

Capítulo 05

El hub: cuatro pestañas

La pantalla de entrada tiene cuatro pestañas fijas —preparar el trabajo, conectar el instrumento, levantar, calcular— y una rejilla de módulos en cada una. Los nombres de las pestañas cambian según el modo; los destinos, no.

Arriba se ven siempre dos datos: el proyecto activo y el estado GNSS (calidad del fix, satélites usados/visibles, precisión y PDOP).

En modo Campo se ocultan de la rejilla los módulos que ese oficio no usa —minicaster, compartir GNSS, PPK, servicios OGC, simbología, tabla de atributos—. Siguen existiendo: se llega a ellos desde Ajustes y desde el menú lateral.

Barra inferior y menú lateral

La barra inferior flotante lleva cuatro accesos: Mapa, GNSS, AR y Buscar. El menú lateral (icono de hamburguesa) da acceso a Inicio, Módulos, Atajos, Ajustes, Registro de diagnóstico y Salir.

Capítulo 06

El mapa por dentro

Es la pantalla donde se pasa el día. Todo lo que flota sobre el mapa se puede plegar o mover.

Cintillos, de arriba abajo

Botones

• Barra de modos (izquierda): Topo · GIS · Campo, con su atajo.
• Barra de herramientas (derecha, arrastrable y plegable): superficie de elevación, acercar, alejar, norte, mi posición, captura de pantalla, hablar, capas y medir.
• Botón de captura ➕: se arrastra donde quiera y se queda ahí.
• Panel de captura: guardar, deshacer nodo, nueva parte, cancelar, automático, coordenadas y proyección de punto.

Gestos

• Un toque sobre una entidad de la capa de consulta abre su ficha.
• Mantener pulsado en cualquier punto abre el diálogo de navegación: guiado AR, Waze o Google Maps, y ruta sin conexión.
• Dos dedos: girar el mapa (si la rotación está activada en Ajustes).

Capítulo 07

Proyectos

Un proyecto es una carpeta con un GeoPackage dentro. Todo lo que capture vive ahí.

• Hub → Proyecto → Proyectos y toque +.
• Escriba el nombre. El diálogo muestra la proyección vigente y deja cambiarla ahí mismo; si no entra, se queda con la de siempre.
• Toque el proyecto para abrirlo. La aplicación lo recordará entre arranques.

Desde la lista se puede además renombrar, duplicar, borrar y compartir el .gpkg entero. El primer arranque siembra un proyecto de ejemplo, GeoDataCollector, con capas de los tres tipos para trastear sin miedo.

Capítulo 08

Capas y candados

Una capa es una tabla de entidades de un tipo de geometría. Hub → Proyecto → Capas.

Crear y activar

Al crear una capa elige tipo: punto, línea, polígono o colección (una capa que admite las tres formas a la vez, como las que traen los geopaquetes de catastro).

Activar una capa es decir «aquí es donde van los puntos que tome». Hay una ranura por tipo de geometría más una de colección, así que puede tener a la vez la capa de puntos, la de líneas y la de polígonos recibiendo datos. En la lista, la capa en edición va en naranja y negrita; las simplemente visibles, en el color de acento.

Visibilidad y orden

El ojo enciende y apaga la capa en el mapa; las flechas la suben o bajan en el orden de dibujado; la lupa encuadra el mapa en ella.

El candado: tres niveles

Editar capa → Permisos de edición

El candado se impone en el motor de datos, no en cada pantalla: cubre el mapa, la lista de entidades, la importación de archivos y los plugins. Las pantallas además quitan de antemano lo que no se puede: el menú de una entidad bloqueada no ofrece Editar ni Borrar.

Otras acciones de capa

• Vaciar: borra las entidades y deja la estructura.
• Copiar vacía: clona la capa con sus campos, sin datos. Es la vía rápida para la campaña del mes siguiente.
• Reconstruir índice: si el dibujado se vuelve lento tras miles de entidades.
• Importar entidades de otro archivo a esta capa.
• Exportar: GeoJSON, Shapefile (zip), GML, CSV, KML y GPX.

Capítulo 09

Atributos y entidades

Campos

Capas → Atributos. Cada capa nace con seis campos de plantilla —nombre, descripción, fecha de inicio, observaciones, creado y modificado— y las capas de punto suman trece de trazabilidad GNSS. Encima de eso se añaden los suyos: texto, número entero, número decimal, fecha, sí/no, lista de opciones y archivo adjunto (BLOB).

La tabla de entidades

Capas → Entidades abre la tabla completa: filtrar, ordenar, buscar, editar celda a celda, ver adjuntos, borrar y hacer zoom a una entidad. Es también el sitio donde se corrige a la vuelta lo que se anotó deprisa en campo.

El bloque de atributos

Al guardar una entidad se abre el formulario con sus campos. Recuerda el último valor escrito por capa (si lo activa en Ajustes) y avisa de nombres duplicados. Los campos GNSS se rellenan solos con la calidad del momento de la captura, no del momento en que usted termina de escribir.

Capítulo 10

Capturar datos

Cinco vías, todas sobre la capa activa.

Líneas y polígonos

Cada toque o cada ➕ añade un nodo. Nueva parte empieza otro trazado dentro de la misma entidad (una finca con dos lotes separados). Deshacer quita el último nodo. Guardar cierra la geometría y abre el formulario.

Proyección de punto

Distancia y azimut desde el último punto capturado, desde su posición o desde el centro del mapa. Para el vértice al que no se puede llegar con el jalón.

Puertas de calidad

Antes de escribir nada, la aplicación comprueba:

• Que la posición venga de satélites. Si hay satélites a la vista y ninguno en el cálculo, lo que entrega el teléfono es un relleno de red con precisión de cientos de metros: se rechaza con «No viene de satélites: N a la vista, 0 en el cálculo. Punto no registrado». Esta puerta no se puede desactivar.
• RTK fijo, si lo exige en Ajustes (sólo con receptor externo).
• Precisión mínima en metros, si la configuró.

Capítulo 11

GNSS y RTK

Hub → Instrumento. Cada mosaico abre su sección del panel GNSS.

Origen de la posición

La aplicación usa el chip del teléfono por defecto y un receptor externo cuando lo configura. El chip queda de reserva caliente: si el receptor externo calla más de ocho segundos —batería, Bluetooth, fuera de alcance—, la posición vuelve al interno en vez de quedarse ciega, y regresa al externo en cuanto vuelve.

Receptor externo

NTRIP

Proveedores y credenciales, descarga del sourcetable, elección de mountpoint y estado de la conexión. Con redes virtuales (VRS/NEAR), la aplicación envía su posición al caster automáticamente. La edad de las correcciones sale en el cintillo del mapa: si crece, el RTK se está degradando.

Minicaster y compartir

Minicaster convierte el equipo en base: retransmite las correcciones de su receptor a otros equipos de la cuadrilla. Compartir GNSS publica la posición para que otra aplicación del mismo teléfono la consuma.

PPK

Registro crudo de observaciones para postproceso. Se graba durante el levantamiento y se descarga después.

Estado del equipo

Constelaciones, relación señal/ruido por satélite, DOP, tipo de solución y edad de correcciones. Es la pantalla a la que hay que mirar antes de dudar de un dato.

Capítulo 12

Precisión, alturas y coordenadas

Altura de antena

La cota que se guarda es la del terreno, no la de la antena. Escriba la altura del bastón en Ajustes → Levantamiento.

Promediado

Actívelo para que cada punto sea la media de N épocas o de T segundos, lo que ocurra primero. El diálogo muestra el avance, la media en coordenadas proyectadas y las desviaciones σ horizontal y vertical. Con el filtro de RTK fijo activo sólo cuentan las épocas fijas.

Geoide y cota ortométrica

Con un modelo de geoide instalado (EGM2008), la aplicación convierte la altura elipsoidal en ortométrica: H = h − N. Sin modelo, marca el valor como elipsoidal en vez de fingir.

Sistema de coordenadas

Hub → Proyecto → Unidades y coordenadas. Elija el EPSG —CRTM05 (8908) es el predeterminado en Costa Rica— o pegue una cadena proj4 propia. Ahí mismo se fijan las unidades de longitud (m, km, ft) y de área (m², ha, ac, km²), que mandan en todo lo que muestra la aplicación.

En el primer arranque, la aplicación pregunta si conoce la proyección que utiliza. Si dice que no, fija el UTM WGS 84 de su zona y se lo comunica.

Capítulo 13

Replanteo nuevo

Llevar al terreno un punto que existe en el proyecto: ir hasta él, clavar la estaca y dejar registrado dónde quedó realmente.

• Póngase en modo Topo y toque su botón otra vez (o use Replantear del aviso al cambiar de modo).
• Elija de dónde salen los puntos: Puntos de una capa del proyecto, o Coordenadas tecleadas en WGS84 o CRTM05.
• Camine siguiendo la flecha y los números. Al entrar en tolerancia, el equipo pita y la diana se pone verde.
• Clave la estaca y toque Guardar: se registra su posición medida con la desviación respecto al proyecto, y pasa al punto siguiente.

Lo que dice el cintillo

P-14 · 3/37 · 12 ✓ · 3,42 m · 47°
2,33 m al norte · 2,50 m al este · cortar 0,18 m

Detalles que importan en el terreno

• La flecha gira respecto a su rumbo sólo si el rumbo vale algo. Parado, el rumbo del GNSS da vueltas enteras, así que por debajo de 0,5 m/s la flecha apunta al azimut geográfico: no ayuda a girar, pero no miente.
• El pitido suena al entrar en tolerancia, no mientras se está dentro. Un pitido por época con el jalón apoyado acaba con el sonido apagado y el punto siguiente sin aviso.
• La tolerancia se fija una vez (10 cm por defecto) desde el mismo diálogo del atajo, y sólo mira la planta: un centímetro en planta con medio metro de desnivel es una estaca bien puesta.
• ◀ ▶ recorren la lista y dan la vuelta al llegar al final: en campo se salta el punto que tiene un carro encima y se vuelve a él al terminar.
• La lista no ofrece el registro interno de capturas ni las capas vacías: un replanteo se hace contra puntos de proyecto.

Qué se guarda

La posición medida, no la coordenada de proyecto — es lo que distingue un replanteo de un dibujo. En la descripción queda la desviación: Replanteo de P-14 · N 2,33 m · E 2,50 m · dist 3,42 m, y los campos GNSS de la capa recogen la calidad del momento.

Hace falta una capa de puntos activa donde escribir. Si la capa está bajo candado, se dice como tal; y si la posición no viene de satélites, no se registra nada.

Capítulo 14

Medir y calcular

El botón de medición del mapa abre un trazado temporal que no toca sus datos: toque para poner nodos y lea distancias parciales, distancia total, área y ángulos interiores. Cerrando el trazado se obtiene el área del recinto.

El cintillo de medición es además la puerta a los cálculos de movimiento de tierras y al perfil del terreno (capítulo 15).

Extensión de cálculos topográficos

Como módulo aparte se distribuye la calculadora de campo: inversa y directa, factores de cuadrícula a terreno, intersecciones, resección con aviso de círculo peligroso, poligonal con ajuste, división de líneas y áreas, curvas horizontales y verticales, nivelación, volúmenes y conversión de coordenadas. Toma puntos del proyecto o del GNSS y devuelve los resultados a una capa del GeoPackage. No declara permiso de red: los cálculos no salen del equipo.

Capítulo 15

Modelo de elevación y movimiento de tierras

El botón de superficie del mapa levanta un modelo del terreno con los puntos que ya tiene levantados: interpolación IDW o triangulación TIN, con rampa hipsométrica de colores.

De qué puntos se construye

De las capas con cota y del registro de captura. Puede excluir puntos por precisión —descartar todo lo que pase de X metros— para que un fix malo no deforme la superficie.

Corte y relleno

Con una superficie y un recinto medido: la aplicación calcula volumen de corte, de relleno, su diferencia, y el nivel de plataforma que los equilibra. Con la capacidad de la vagoneta configurada, traduce el volumen a viajes. El resultado se comparte como texto o imagen.

Perfil del terreno

Modelo de elevación → Perfil del terreno → Trazar un perfil. La aplicación da el paso que falte: sin modelo lo enciende, sin trazado entra en Medir y pide los puntos, y con todo listo calcula. IDW o TIN se eligen en el mismo diálogo.

Auto-survey

Con la superficie encendida, la aplicación puede ir añadiendo puntos al modelo mientras camina, respetando la precisión mínima y una distancia mínima entre muestras.

Capítulo 16

Multimedia y evidencias

Al exportar el proyecto puede incluirse el paquete multimedia completo, de modo que quien lo reciba vea las fotos junto a las entidades.

Capítulo 17

Mapa base y servicios OGC

Mapa base

Hub → Herramientas → Mapa base: callejero, satélite, satélite con rótulos o ninguno (fondo limpio para trabajar sólo con sus capas).

Servicios

Hub → Herramientas → Servicios añade capas remotas:

• WMS y WMTS: cartografía oficial, ortofotos institucionales.
• XYZ: cualquier teselado estándar.
• WFS: entidades vectoriales consultables.

Se guarda nodo, tipo, capas y cobertura. Desde la hoja de capas activas del mapa se elige cuál responde a los toques, y se ocultan las que estorben.

Capítulo 18

Trabajar sin conexión

Lo que se lleva al campo se baja antes, con cobertura.

• Hub → Herramientas → Mapas sin conexión → + → Descargar área desde el mapa
• Encuadre el área en el mapa y ajuste el recuadro. La pantalla se abre donde usted está: primero en el fix GNSS, y si no lo hay, en el último centro del mapa.
• Elija el rango de zoom. La aplicación estima cuántas teselas y cuántos megas son antes de empezar.
• Descargue. Es un servicio en primer plano: bajar un cantón son minutos y apagar la pantalla no lo aborta.

El resultado son dos archivos hermanos en la carpeta offline:

• <área>.mbtiles — las teselas de la capa base activa.
• <área>.roads — la red vial de la zona, para rutear sin cobertura.

Otros archivos sin conexión

También se importan mapas propios: .mbtiles ya hechos y ortofotos georreferenciadas en GeoTIFF. Se encienden, se apagan y se encuadran desde la misma pantalla.

Capítulo 19

Navegación y rutas

Mantenga pulsado un punto del mapa —o busque un lugar por nombre— y aparecen las tres vías, cada una con su estado real debajo:

Ninguna se oculta cuando no sirve: si falta el área descargada, la opción lleva a descargarla. Al llegar por carretera, el guiado AR toma el relevo para el último tramo a pie.

Herramientas AR

La vista de realidad aumentada añade sobre la cámara: brújula con rumbo objetivo, distancia acumulada, nivel de burbuja, clinómetro, cruz de suelo, linterna, captura y compartir posición. Los avisos sonoros permiten caminar mirando el terreno en vez de la pantalla.

Capítulo 20

Simbología

Hub → Herramientas → Simbología, con un proyecto abierto.

Tipos de simbología

• Único: un color y un trazo para toda la capa.
• Categorizado: un color por valor de un campo (por variedad, por estado).
• Graduado: rampa por rango numérico (por rendimiento, por profundidad).

Línea y borde

Ancho de 1 a 20 px y cinco trazados: continuo, discontinuo, punteado, raya-punto y marcadores. La muestra en vivo es una línea quebrada a propósito: en una recta, discontinuo y punteado no se distinguen. El patrón se escala con el ancho, no en píxeles fijos.

Etiquetas

Se elige el campo que rotula cada entidad, si se evitan solapes y desde qué número empieza la numeración automática.

Capítulo 21

Exportar e importar

Formatos

Destinos

Además de guardar en el teléfono y compartir por cualquier aplicación:

• PostgreSQL / PostGIS — escribe directo a la base corporativa.
• FTP y SFTP — servidores propios.
• Amazon S3 — con cifrado del lado del cliente: lo que sube ya va cifrado y el proveedor no puede leerlo.
• Google Drive y GitHub — repositorios de la organización.

Las credenciales de todos ellos se guardan cifradas (capítulo 23).

Copia de la configuración

Ajustes → Copia de configuración exporta e importa los ajustes del equipo —unidades, proyección, receptores, proveedores NTRIP, destinos— para clonar la configuración en el resto de la cuadrilla sin repetirla equipo por equipo. Las contraseñas no viajan en claro.

Capítulo 22

Ajustes: referencia completa

Las secciones de GNSS externo y NTRIP no aparecen en el índice de Ajustes: se abren desde el panel del instrumento, junto a las acciones con las que se usan.

Capítulo 23

Seguridad de YieldRadar

Qué protege la aplicación, con qué, y —tan importante como lo anterior— qué no protege.

Credenciales cifradas

Las contraseñas de PostGIS, FTP/SFTP, S3, NTRIP y los tokens de repositorios no se guardan en claro. Se cifran con AES-256-GCM usando una clave que vive en el Android Keystore —en el elemento seguro del equipo cuando el hardware lo soporta— y que no es extraíble ni con acceso al almacenamiento de la aplicación.

Tráfico de red

El tráfico en claro está prohibido salvo donde el protocolo no deja alternativa (un caster NTRIP en HTTP simple, un servidor FTP de la propia organización). Cada excepción está declarada en la política de red del paquete, no abierta en general.

Cifrado del lado del cliente

Al exportar a S3, los archivos se cifran antes de salir del teléfono, con una clave por proyecto. El proveedor de almacenamiento guarda un bloque opaco: aunque el bucket quedara expuesto, el contenido no es legible.

Informe de seguridad auditable

La aplicación puede generar un informe de su propia postura de seguridad: dónde vive la clave maestra, si el paquete es depurable, qué extensiones hay instaladas y con qué permisos, y qué controles cumple o incumple. Está pensado para que el responsable de seguridad de un cliente lo revise sin creer en promesas.

Lo que no protege

• Un equipo con root. Quien ejecuta código dentro del proceso de la aplicación puede leer lo que la aplicación lee.
• El candado de capa es contra el error de dedo, no contra un adversario.
• Los tokens de repositorio incrustados en el APK —el buzón compartido de datos de la marca— viajan dentro del paquete: son compartidos por todos los usuarios de la marca y la propia aplicación los señala como tales. No ponga ahí nada privado.
• Un APK depurable permitiría adjuntar un depurador al proceso. Por eso lo que se entrega es la variante de publicación, no la de depuración.

Capítulo 24

Licencias por dentro

Para quien administra la flota o integra el panel.

Cómo se valida

• La aplicación envía el código de licencia y el identificador de equipo al endpoint /api/validar-licencia del panel de YieldRadar.
• El servidor responde con un veredicto: si es válida, de qué tipo, cuándo expira y —lo importante— una firma ECDSA P-256 sobre esa respuesta.
• El APK verifica la firma con la clave pública que lleva dentro. Una respuesta sin firma válida se rechaza, venga de donde venga.
• El veredicto se guarda cifrado para poder abrir sin cobertura durante 30 días.

La presencia de la clave pública en el APK es el interruptor: con clave, se exige respuesta firmada; sin ella, se acepta sin firmar. Eso permitió desplegar el servidor primero y publicar el APK después sin dejar a nadie fuera.

Anti-fraude local

• Una activación por licencia. El servidor vincula el equipo la primera vez; a partir de ahí, otro teléfono recibe otro_dispositivo.
• Detección de reloj atrasado. Retrasar la fecha del teléfono no alarga la ventana sin conexión.
• Reconexión obligatoria a los 30 días.

Operación

Capítulo 25

Plugins: qué son y cómo se usan

Un plugin es una aplicación web —HTML, CSS y JavaScript— que corre dentro de YieldRadar y habla con el proyecto a través de un puente controlado por permisos. Sirve para lo que el núcleo no hace: una calculadora de un gremio, un formulario de una norma, un informe propio de la empresa.

Instalar uno

• Menú lateral → Módulos → Instalar módulo
• Elija el archivo .mtplug, o descárguelo del catálogo del repositorio configurado.
• La aplicación verifica la firma y muestra qué permisos pide. Acepte o cancele.
• El módulo aparece en Hub → Herramientas → Módulos y en el menú lateral.

Los tres niveles de confianza

Permisos que puede pedir un plugin

Cada método del puente exige el suyo. Sin declararlo en el manifiesto y sin que el usuario lo conceda, la llamada devuelve error. Un plugin del formato antiguo (v1, sin declaración) recibe sólo los permisos de lectura y escritura no destructiva: nunca borrado ni cámara.

Aislamiento entre plugins

Cada plugin corre en su propio origen web, así que su almacenamiento del navegador está separado del de los demás. Para lo sensible hay un almacén cifrado por plugin (secureGet / securePut) cuya clave vive en el Keystore y cuya identidad va atada al plugin: un valor guardado por el plugin A no se puede descifrar presentándolo como del plugin B.

Catálogo por repositorio

Compartir un .mtplug por mensajería no es fiable —WhatsApp y otros renombran o recomprimen los adjuntos que no reconocen—. Por eso los módulos se publican en un repositorio de GitHub con un catalog.json; el usuario elige de una lista y las actualizaciones llegan solas. La seguridad no depende del transporte: la firma cubre el hash de cada archivo, así que un repositorio comprometido no puede colar un plugin alterado, como mucho dejar de servirlo.

Capítulo 26

QuickStart: un plugin interno para su empresa

Objetivo: en una tarde, un módulo que sólo usará su cuadrilla. Ejemplo real: un control de visitas que registra el punto donde está el técnico, con el número de finca y el motivo, en una capa del proyecto abierto.

1 · La estructura mínima

ControlVisitas/
  manifest.json        ← identidad y permisos
  index.html           ← su interfaz
  app.js               ← su lógica
  geodata-sdk.js       ← el SDK (cópielo de plugins_seguros/sdk/)

2 · El manifiesto

manifest.json

{
  "manifest_version": 2,
  "plugin_id": "cr.miempresa.controlvisitas",
  "publisher_id": "miempresa",
  "title": "Control de visitas",
  "version": "1.0.0",
  "entryPoint": "index.html",
  "author": "Mi Empresa S.A.",
  "description": "Registra la visita del tecnico con finca y motivo.",
  "min_app_version": "7.21.15",
  "license_mode": "free",
  "permissions": ["gnss", "storage.read", "storage.write"],
  "network": { "allowedHosts": [] }
}

3 · La interfaz

index.html

<!doctype html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Control de visitas</title>
  <style>
    body { font: 16px/1.5 system-ui, sans-serif; margin: 0; padding: 16px; }
    label { display: block; margin: 14px 0 4px; font-weight: 600; }
    input, select, button { width: 100%; padding: 12px; font-size: 16px; }
    button { margin-top: 20px; background: #0B5C48; color: #fff; border: 0; border-radius: 6px; }
    #estado { margin-top: 14px; min-height: 24px; }
  </style>
</head>
<body>
  <h1>Control de visitas</h1>
  <label for="finca">Finca</label>
  <input id="finca" placeholder="F-104">
  <label for="motivo">Motivo</label>
  <select id="motivo">
    <option>Inspeccion</option>
    <option>Muestreo</option>
    <option>Entrega</option>
  </select>
  <button id="guardar">Registrar aqui</button>
  <p id="estado"></p>

  <script src="geodata-sdk.js"></script>
  <script src="app.js"></script>
</body>
</html>

4 · La lógica

app.js

const CAPA = "visitas";
const estado = document.getElementById("estado");
let PROYECTO = null;

// Al abrir: averiguar en que proyecto esta trabajando el usuario y asegurar la capa.
// Ojo: las llamadas de datos del SDK son SINCRONAS, no llevan await.
(function preparar() {
  try {
    const activo = GeoData.data.active();          // permiso: storage.read
    PROYECTO = activo && activo.project;
    if (!PROYECTO) { estado.textContent = "Abra un proyecto primero."; return; }

    if (!GeoData.data.layerExists(PROYECTO, CAPA)) {
      GeoData.data.createLayer(PROYECTO, CAPA, "POINT");        // permiso: storage.write
      GeoData.data.addAttribute(PROYECTO, CAPA, "finca",  "TEXT");
      GeoData.data.addAttribute(PROYECTO, CAPA, "motivo", "TEXT");
      estado.textContent = "Capa «visitas» creada.";
    }
  } catch (e) {
    estado.textContent = "No se pudo preparar la capa: " + e.message;
  }
})();

document.getElementById("guardar").addEventListener("click", () => {
  estado.textContent = "Tomando posicion...";
  try {
    const fix = GeoData.gnss.current();            // permiso: gnss  →  {lat, lon}
    if (!fix || (fix.lat === 0 && fix.lon === 0)) {
      estado.textContent = "Todavia sin posicion: salga a cielo abierto.";
      return;
    }
    GeoData.data.insert(PROYECTO, CAPA, "POINT", [fix.lon, fix.lat], {
      nombre: document.getElementById("finca").value || "sin finca",
      finca:  document.getElementById("finca").value,
      motivo: document.getElementById("motivo").value
    });
    estado.textContent = "Visita registrada.";
  } catch (e) {
    if (e.name === "PermissionError") {
      estado.textContent = "Falta el permiso " + e.permission;
    } else {
      estado.textContent = "Error: " + e.message;
    }
  }
});

5 · Probarlo sin firmar

• Active Ajustes → Plugins → Modo desarrollador. Con él, la aplicación ejecuta módulos sin firma —y lo advierte en pantalla—.
• Comprima la carpeta y renómbrela a ControlVisitas.mtplug.
• Instálelo desde Módulos, ábralo y pruebe.
• Para depurar, conecte el teléfono y abra chrome://inspect en el ordenador: el WebView del plugin aparece ahí con su consola completa.

6 · Repartirlo a la cuadrilla

Para uso interno hay dos vías. La rápida: pasar el .mtplug por USB o por correo (no por mensajería, que renombra los adjuntos). La ordenada: un repositorio de GitHub privado de la empresa con un catalog.json, configurado una vez en cada equipo desde Ajustes → Conexiones remotas → Repositorios de GitHub; a partir de ahí las actualizaciones se instalan desde la lista.

Antes de repartirlo, fírmelo: es el siguiente capítulo, y evita que sus técnicos tengan que dejar el modo desarrollador encendido.

Capítulo 27

Firmar y proteger el código

La cadena de confianza

clave raiz (fabricante)  --firma-->  certificado de editor
clave de editor          --firma-->  META/hashes.json del paquete
META/hashes.json         --cubre-->  SHA-256 de CADA archivo del plugin

Criptografía: ECDSA sobre la curva P-256 con SHA-256. Se eligió P-256 y no Ed25519 porque Android sólo trae Ed25519 nativo desde la versión 13 y la aplicación soporta desde la 7.0; además P-256 es la curva que admite el Keystore, que es lo que se usa para los tokens de licencia.

Qué hay dentro de un paquete firmado

Los bytes que se firman están definidos literalmente, no como JSON canonicalizado, para que reimplementar el verificador en cualquier lenguaje sea inequívoco: el certificado firma la cadena publisher_id \n name \n pubkey \n issued \n expires, y el paquete firma los bytes exactos del archivo hashes.json tal y como quedan en disco.

Firmar, paso a paso

herramienta de referencia: mtsign.py

# Una sola vez, en un equipo controlado: la clave raiz (la guarda el fabricante)
python mtsign.py root-init

# Una vez por editor: el fabricante emite su certificado
python mtsign.py publisher-new --id miempresa --name "Mi Empresa S.A." --years 3

# Cada vez que publique una version del plugin
python mtsign.py pack ControlVisitas --publisher publishers/miempresa \
                     -o ControlVisitas-1.0.0.mtplug

# Comprobar antes de repartir
python mtsign.py verify ControlVisitas-1.0.0.mtplug

Qué protege la firma… y qué no

Proteger de verdad su propiedad intelectual

La firma garantiza integridad y origen, no confidencialidad. Si su valor está en el algoritmo, aplique estas tres, por orden de eficacia:

1. Lo que vale, en el servidor. El plugin es la interfaz; el cálculo caro vive en su API. Es la única protección que no se puede revertir en el teléfono.
2. Minifique y ofusque lo que sí baja (esbuild, terser). Sube el coste de leerlo; no lo impide.
3. Nunca incruste secretos en el paquete. Ni claves de API, ni contraseñas: lo que va dentro del .mtplug es público de facto. Para lo que deba persistir en el equipo use el almacén cifrado del puente (securePut), no localStorage.

Capítulo 28

Monetizar un plugin

El problema a resolver: su servidor de licencias no puede distinguir una petición hecha por su plugin, dentro de la aplicación de verdad, de un curl que imita la llamada. La attestation lo resuelve.

Cómo funciona

• Su plugin pide un nonce a su servidor.
• Llama a GeoData.license.attest(nonce): la aplicación firma ese nonce con una clave privada que vive en el Android Keystore del equipo y que no es extraíble.
• Su servidor verifica la firma y decide si ese dispositivo tiene licencia.
• Guarde la respuesta cifrada con GeoData.secure.set para trabajar sin cobertura un tiempo.

puerta de licencia, esquema

// El SDK ya encadena las cuatro fases: nonce → firma → canje → guardado cifrado.
// Su servidor sólo tiene que ofrecer GET /nonce y POST /verify.
const API = "https://licencias.miempresa.com/api/v1/controlvisitas";

async function comprobarLicencia() {
  try {
    const r = await GeoData.license.verify(API, { graceDays: 30 });
    if (r.valid && r.offline) {
      estado.textContent = "Licencia validada sin cobertura, con la copia guardada.";
    }
    return r.valid;
  } catch (e) {
    return false;
  }
}

Si necesita el control fino —porque su protocolo no es ese— las tres piezas están sueltas:

const info  = GeoData.license.info();              // sin permiso: quien soy y en que marca corro
const nonce = await (await fetch(API + "/nonce")).json();

// Requiere el permiso `license` declarado en el manifiesto
const token = GeoData.license.attest(nonce.nonce); // {alg, payload_b64, sig_b64, device_key_b64, key_chain_b64}

const r = await fetch(API + "/verify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ nonce: nonce.nonce, attestation: token,
                         plugin: info.plugin_id, version: info.version })
});
const veredicto = await r.json();

if (veredicto.valid) {
  GeoData.secure.set("licencia", JSON.stringify({
    hasta: veredicto.claims && veredicto.claims.expira, guardado: Date.now()
  }));
}
return veredicto.valid;

Qué recibe usted del dispositivo

Usted puede atar una licencia a un dispositivo, pero no obtiene el identificador real del equipo ni puede correlacionar al mismo usuario entre plugins de editores distintos. Es deliberado: la privacidad del usuario final no es negociable a cambio de su modelo de negocio.

Lista de comprobación antes de vender

Apéndice A

API del puente

Los 33 métodos del puente nativo y el permiso que exige cada uno. Esta tabla es la del puente crudo; lo que usted escribe es el SDK, que los agrupa por familias con nombres más cortos: GeoData.data.*, GeoData.gnss.*, GeoData.map.*, GeoData.license.* y GeoData.secure.*.

Todas las operaciones de escritura respetan el candado de capa: sobre una capa bloqueada devuelven error, igual que le ocurriría al usuario desde la interfaz.

Apéndice B

Si algo va mal

Para cualquier cosa que no esté aquí: Menú lateral → Registro de diagnóstico guarda lo que hizo la aplicación por dentro y se comparte desde ahí mismo. Con la grabación de pantalla adjunta, un problema de campo se diagnostica sin viajar.

Apéndice C

Glosario

---