Tipo de script API ejemplo para Capacitor y Capgo

Todas las sólidas Ejemplo de API de TypeScript for Capacitor begins the same way: with a typed plugin interface. Spell out your methods, options, and Promise results explicitly, and your web code and the native layer share one contract that TypeScript actually enforces.

Contenido de la Tabla

• Build a Strongly Typed Capacitor Plugin Interface
  • Búsqueda rápida para el diseño de API.
  • Señales de Adopción
  • Ventajas para equipos de Capacitor
  • Beneficios para los equipos de __CAPGO_KEEP_0__
  • Crear un caso empresarial
  • Escucha correctamente los argumentos de __CAPGO_KEEP_0__
  • Define contratos de actualización de __CAPGO_KEEP_0__
  • Registre los Escuchadores de Forma Segura
  • Elige el Método de Eliminación Correcto
  • Tipifica los Entradas y Salidas con Precisión
  • Organiza los Cambios para Code
  • ¿Cómo Debo Tipificar los Resultados Nativos Dinámicos?
  • ¿Cómo pueden los Escuchadores Evitar Rechazos No Manejados?
  • ¿Cómo Puedo Proteger los Actualizaciones de Capgo?

Build a Strongly Typed Capacitor Plugin Interface

La interfaz describe el API que ve tu web code. La implementación nativa detrás de ella tiene que honrar ese contrato — y TypeScript verifica los nombres de métodos, parámetros y valores de retorno antes de que tu aplicación se ejecute.

import { registerPlugin } from ‘@capacitor/core’;

export interface EstadoDelDispositivo { enLínea: boolean; nivelDeBatería?: number; }

export interface PluginDispositivo { getStatus(): Promise; setEtiqueta(options: { etiqueta: string }): Promise<{ guardado: boolean }>;

export const Dispositivo = registerPlugin(‘Dispositivo’);

Hay mucho que sucede en esas pocas líneas:

• Tipos de retorno explícitos mantener cada resultado predecible.
• Objetos de opciones tipados capturar propiedades faltantes o mal escritas en tiempo de compilación.
• Métodos basados en promesas modelar trabajo nativo que termina de manera asíncrona.
• Un tipo genérico registerPlugin llamada Es lo que conecta la web API con la puente nativa.
• Interfaces documentan el contrato sin agregar un solo byte de tiempo de ejecución code.

Todas las llamadas reciben el mismo tratamiento:

const estado = await Device.getStatus(); console.log(estado.conectado);

await Device.setLabel({ label: ‘Producción’ });

Intercambiar { label: 'Production' } por { name: 'Production' } y el compilador lo marca en el momento. Eso supera descubrir el desajuste después de un lanzamiento móvil.

La interfaz es también donde modelas valores opcionales y casos de error. Si un método nativo no puede producir siempre una lectura de la batería batteryLevel?: number indica a todos los llamadores que manejen undefined.

La siguiente imagen muestra cómo los métodos tipados, opciones, valores de retorno, definiciones de puentes y comprobaciones en tiempo de compilación se conectan dentro de un Capacitor API.

La idea central: definiciones de tipo fluyen desde la interfaz web hacia la lógica de plataforma nativa, y los controles de tiempo de compilación vigilan cada sitio de llamada.

Consulta rápida para API Diseño

Para una referencia más profunda, lee la guía sobre la creación de APIs en TypeScriptDejar secretos y credenciales de firma fuera del cliente code, y probar la interfaz contra cada implementación de plataforma antes de publicar.

Los equipos móviles manejan JavaScript, nativo code, permisos de dispositivo y servicios de plataforma asíncronos todo al mismo tiempo. Un fuerte contrato de TypeScript funciona como una lista de verificación compartida en cada una de esas fronteras, haciendo las expectativas explícitas antes de que cualquier code llegue a un dispositivo iOS o Android.

Para un ejemplo concreto TypeScript API ejemplo, compara un método que devuelve Promise<DeviceStatus> con uno que devuelve datos sin tipificar. La versión tipificada informa a tu editor y a cada revisor exactamente cuáles campos existen. La versión sin tipificar desplaza ese trabajo de descubrimiento a registros de tiempo de ejecución, pruebas manuales y, en el peor de los casos, incidentes en producción.

Señales de Adopción

TypeScript ha superado ampliamente su nicho de front-end. La adopción alcanzó un 35% de desarrolladores en 2024, desde solo 12% en 2017, y más de un millón de GitHub contribuyentes listado como su idioma principal para 2025. Explora el contenido completo Adopción de TypeScript si quieres los números brutos.

La trayectoria importa para las organizaciones móviles de maneras prácticas. La contratación, la incorporación y la code de revisión cada vez más giran en torno a tipos compartidos. Al unirse a un proyecto Capacitor, alguien puede leer una interfaz y comprender el comportamiento nativo esperado sin seguir cada implementación.

Las API tipadas también hacen que el trabajo de lanzamiento sea más fácil de razonar. Cuando un método exige un objeto de opciones específico, un nombre de propiedad renombrado o un campo faltante falla en tiempo de compilación en lugar de producir silenciosamente una solicitud nativa parcialmente formada.

Strong typing shifts critical feedback leftcuando una corrección toma minutos en lugar de una liberación de parche de emergencia.

Beneficios para los equipos Capacitor

Cross-platform apps typically expose one web-facing API that sits on top of several native implementations. TypeScript cannot prove every native detail behaves identically, but it can keep your calls consistent across the entire application.

Aplica tipos explícitos a:

• Los parámetros de métodos, incluyendo opciones requeridas y opcionales
• Los resultados de promesas, para que los datos de éxito siempre tengan una forma predecible
• Eventos y oyentes, so callbacks handle known payloads
• Errores y valores de estadoEntonces los caminos de fallback permanecen visibles

Esa estructura se paga cuando se integran plugins de dispositivos o servicios operativos. También ayuda a los equipos que revisan la automatización de actualizaciones, donde un canal incorrecto, un identificador de paquete o un campo de compatibilidad pueden propagarse a una gran base de usuarios.

Para una inmersión más profunda en patrones relacionados, lee nuestra guía para generar APIs tipadas con OpenAPI. Cubre cómo las definiciones compartidas reducen la deriva manual que normalmente se filtra entre la documentación de API y la aplicación code.

Hacer el Caso Empresarial

El tipado estricto pide una inversión inicial, especialmente cuando el JavaScript code más antiguo lleva formas de datos inconsistentes. El retorno se muestra con el tiempo: refactores más pequeños, propiedad más clara y mucho menos sorpresas de integración.

Comienza con los límites que llevan el mayor riesgo:

1. Define interfaces de respuesta para llamadas nativas y remotas.
2. Introduzca sus objetos de opciones y payloads de eventos.
3. Activa las comprobaciones del compilador de manera incremental.
4. Require type checks before publishing any update.

Para equipos móviles de empresas, esa base mantiene la mantenibilidad predecible a través de plataformas, versiones y contribuyentes.

Capacitor’s ScreenOrientationPlugin es una gran herramienta TypeScript API example because it maps a handful of simple web methods onto platform-specific device behavior. The public contract stays identical across platforms, while iOS and Android each deal with their own native details underneath.

import { registerPlugin } from ‘@capacitor/core’;

export tipo de orientación = | ‘portrait-primary’ | ‘portrait-secondary’ | ‘landscape-primary’ | ‘landscape-secondary’;

export interface OpcionesDeBloqueo { orientación: TipoOrientación; }

export interface ScreenOrientationPlugin { orientación(): Promesa}

export interface ScreenOrientationPlugin { orientación(): Promesa}; bloquear(options: LockOptions): Promise; desbloquear(): Promise; agregarEscuchador( eventName: ‘cambioDeOrientaciónDePantalla’, listenerFunc: (data: OrientationData) => void, ): Promise<{ remove: () => Promise} } }

export const OrientaciónDePantalla = registerPlugin(‘OrientaciónDePantalla’);

Aquí está la referencia rápida para cada firma:

• orientation() — lee la orientación actual de manera asíncrona
• lock() — acepta solo un valor de orientación conocido
• unlock() — devuelve el control a la comportamiento normal del dispositivo
• addListener() — dispara un paquete tipado cada vez que cambia la orientación

Desde que cada método devuelve una Promesa, puedes usar el mismo patrón de llamada contra la puente nativa y contra una implementación de navegador. Sin ramificación, sin casos especiales.

const current = await ScreenOrientation.orientation();

if (current.type.startsWith('landscape')) { console.log(Angle: ${current.angle}); }

await ScreenOrientation.lock({ orientation: 'landscape-primary', });

Introduzca un valor mal escrito como landscape-main y el compilado falla en el acto. Eso es un error de compilación que se resuelve en segundos — no un error de ejecución específico de plataforma que se busca a través de registros de dispositivos.

Tipo Argumentos de Escucha Correctamente

Los escuchas merecen la misma rigurosidad que los métodos regulares. Evite any aquí, porque oculta la diferencia entre un paquete de evento y el resultado orientation() devuelve.

const handleChange = (data: OrientationData) => { document.body.dataset.orientation = data.type; };

const suscripción = await ScreenOrientation.addListener( ‘screenOrientationChange’, handleChange, );

await suscripción.remove();

Comparta solo un OrientationData Comparta solo un tipo cuando ambas implementaciones nativas garanticen los mismos campos. Si una plataforma omite angle, marquealo opcional y fuerza a los llamadores a manejarlo undefined.

La interfaz es el contrato de puente, no la implementación nativa. Manténlo pequeño, predecible y probado.

Para plataforma, permisos y pasos de instalación, lee la Capacitor Guía del plugin de orientación de pantalla. Una última costumbre que vale la pena adoptar: prueba tanto llamadas válidas como llamadas rechazadas bajo configuraciones de TypeScript estrictas. Esa combinación captura nombres de métodos incorrectos, campos faltantes y payloads de oyentes incompatibles mucho antes de que empaquetes tu aplicación móvil.

Capgo da a los equipos Capacitor una forma de enviar correcciones de JavaScript, CSS, configuración y recursos sin tener que pasar por la revisión de la tienda de aplicaciones. La trampa es tratar su pipeline de actualizaciones como cualquier otro límite de API tipado, por lo que los canales, las reglas de lanzamiento, las comprobaciones de compatibilidad y las decisiones de rollback permanecen explícitas antes de que un paquete llegue al dispositivo de un usuario.

Define Contratos de Actualización

Comienza definiendo exactamente qué valores acepta su automatización. Las uniones literales te impiden desplegar accidentalmente a un canal incorrecto, y las interfaces hacen que la relación entre un paquete y su versión nativa requerida sea auto-documentada.

tipo Canal = 'beta' | 'staging' | 'producción';

interface UpdateRequest { canal: Canal; versiónDelPaquete: string; versiónMinimaDeNativo: string; porcentajeDeLanzamiento: número; firmado: boolean; }

interface ResultDeActualización { aceptado: boolean; aplicadoEnLaSiguienteEjecución: boolean; rolbackHabilitado: boolean; }

Un ejemplo de TypeScript Un ejemplo de TypeScript API valida la solicitud antes de enviarla al cliente Capgo:

async function publicarActualización( request: SolicitudDeActualización, ): Promise { if (!request.firmado || request.porcentajeDeLanzamiento < 0 || request.porcentajeDeLanzamiento > 100) { throw new Error(‘Solicitud de actualización insegura’); }

return capgo.publicar(request); }

El nombre exacto del método del cliente cambia entre versiones Capgo SDK, por lo que envuélvelo detrás de su propia interfaz. Esa aislación se paga cada vez que actualizas y mantiene los detalles específicos del proveedor de evitar que se filtren a través de tu base de código.

Canales de Guardia y Compatibilidad

La elección de un canal no debe ser casual. Una versión de producción requiere controles más estrictos que un experimento beta, especialmente cuando el paquete web llama a capacidades nativas que no existían en versiones de la aplicación anteriores.

function puedeDesplegar( request: SolicitudDeActualización, versiónNativaInstalada: string, ): boolean { return request.firmado && versiónNativaInstalada >= request.minVersiónNativa; }

No comparen versiones con cadenas simples. Extraigan una biblioteca de versiones semánticas adecuada para ella 1.10.0 después de 1.9.0Antes de que nada llegue a un canal, revise una lista de verificación:

1. Confirmar que el paquete está firmado.
2. Verificar que el canal objetivo coincide con la intención.
3. Comparar las compatibilidades de rango nativo y de paquete.
4. Publicar primero para un público limitado.
5. Observar señales de falla y tener preparado el rollback.

Una canalización de actualización tipada convierte la política de lanzamiento en code que revisores y CI pueden inspeccionar realmente.

Capgo se integra bien en ese patrón con su entrega diferencial y controles de canal, y su observabilidad a nivel de dispositivo permite a los equipos rastrear la adopción o las señales de falla después de los hechos. Para el lado de la instrumentación de eventos, consulte Esta guía sobre el seguimiento de eventos personalizados con Capgo..

Las claves de firma y las credenciales de administrador deben estar en el servidor o en el sistema CI, no en la aplicación embarcada. Aplicar la actualización en la próxima ejecución, probar el rollback con un paquete rechazado intencionalmente y registrar cada decisión con un resultado tipado. Esa combinación mantiene la entrega rápida compatible con el control de liberación móvil disciplinado.

Los oyentes tipados son lo que hace que las API asíncronas sean fáciles de confiar. Ya sea que un callback siga la orientación de la pantalla o un Capgo evento de actualización, debe recibir la misma forma de payload en cada plataforma — y el compilador debe ser el que lo enfoque.

interface EventoDeActualización { versión: string; canal: ‘beta’ | ‘producción’; disponible: boolean; }

tipo Escuchador void (payload: T) => void

interface ServicioDeActualización { agregarEscuchador( evento: ‘actualizaciónDisponible’, callback: Escuchador, ): Promesa<{ eliminar: () => Promesa} >; eliminarTodosLosEscuchadores(): Promesa; }

Esta TipoScript API ejemplo vincula el nombre del evento a una literal y une la llamada a un payload tipado. Su editor autocompleta version de forma gratuita, y el compilador rechaza cualquier llamada que espera datos no relacionados. Es una pequeña cantidad de configuración, y se paga cada vez que el API cambia.

¿Preferir verlo en acción? Mire el recorrido:

Registrar Escuchadores de forma Segura

En el interior de un componente, mantenga el manejador de suscripción alrededor para que la limpieza quede explícita. El mismo patrón se desploma en las pestañas de ciclo de vida de Angular, efectos de React y montaje de Vue sin cambios.

let orientationHandle: { remove: () => Promise} | indefinido; } | undefined;

async function start() { orientationHandle = await ScreenOrientation.addListener( 'screenOrientationChange', ({ type, angle }) => { console.log(type, angle); }, ); }

función asíncrona stop() {\nawait orientationHandle?.remove();\norientationHandle = undefined;\n}

Run cleanup when a screen disappears — not only when the whole app closes. Skip it, and navigation leaves callbacks attached to native event sources. You end up with duplicate work and stale state updates that are painful to trace.

Cada framework te ofrece una herramienta para esto:

• Angular — limpieza de desechos desde ngOnDestroy
• React — devuelva una función de limpieza segura asíncrona useEffect
• Vue — elimine la suscripción en onBeforeUnmount

Todas addListener call should have a matching removal path.

Elige el método de limpieza adecuado

Un manejador devuelto es la llamada correcta cuando un componente posee una sola suscripción. removeAllListeners() brilla cuando un servicio retiene varios oyentes y se está reiniciando por completo.

función asíncrona resetUpdates(servicio: UpdateService) { espera a que servicio.removeAllListeners(); }

No dispare el método ancho desde un componente compartido mientras otras pantallas aún dependen del servicio. Cuando la propiedad es local, manténgase con los manejadores individuales. remove() Situación

Para las notificaciones de Capgo, mantenga los payloads de actualización separados de los eventos del dispositivo. Luego pruebe la registro, entrega y limpieza por separado. Capgo custom event tracking guide tiene más información sobre la integración.

Antes de enviar, compruebe tres cosas: si el desmontaje elimina realmente los manejadores, si las promesas rechazadas se capturan y si ningún callback puede actualizar un componente destruido. Esa disciplina mantiene aplicaciones reactivas de Capacitor responsivas en Angular, React y Vue.

A bien construido Un ejemplo de TypeScript API comienza con nombres que describen la intención. Utilice verbos para métodos, sustantivos para interfaces y manténgase a consistentes sufijos como Options, Result, y EventNombres claros reducen el tiempo de onboarding porque los desarrolladores comprenden el contrato sin abrir la implementación.

Mantén interfaces públicas pequeñas. Exponga capacidades a través de métodos enfocados en lugar de dumping operaciones relacionadas de manera suelta en un solo objeto.

• getStatus() lee el estado.
• updateConfig(options) modifica la configuración.
• addListener(event, callback) se suscribe a cambios.

Define tipos de entrada y salida con precisión

Busque interfaces de opciones nombradas cuando los parámetros pueden crecer:

interface OpcionesDePublicación { canal: ‘beta’ | ‘producción’; porcentajeDeDespliegue: número; }

interface ResultDePublicacion { versión: string; aceptado: boolean; }

async function publicar( opciones: OpcionesDePublicacion, ): Promise { return cliente.publicar(opciones); }

Los generics ganan su lugar cuando un API envuelve diferentes payloads pero necesita preservar sus tipos específicos:

interface RespuestaDeApi { data: T; idDeSolicitud: string; }

async function solicitud(ruta: string): Promise<RespuestaDeApi>{ return fetchJson<RespuestaDeApi>&gt;(ruta);

Pero no agregue generics solo para parecer flexible. Un generic debe expresar una relación real entre la entrada y la salida — de lo contrario, una interfaz concreta es más fácil de leer y mantener.

Haga que los estados inválidos sean difíciles de representarespecialmente en las fronteras nativas, de red y de actualización.

Documente el comportamiento junto a la contrato. Cubra permisos, unidades, promesas rechazadas, campos opcionales y si un método se aplica inmediatamente o en la próxima lanzamiento. Los comentarios en línea deberían explicar decisiones, no repetir nombres de métodos.

Organizar Code para el cambio

Separe tipos, lógica del cliente, adaptadores de plataforma y pruebas en archivos predecibles. Exporte tipos públicos desde un punto de entrada y mantenga detalles de implementación privados.

Para cambios significativos en plugins, introduce una nueva interfaz mayor o una capa de compatibilidad, mantén métodos deprecated temporalmente y escribe los pasos de migración. Aprenda más sobre las estrategias de versionado de API antes de cambiar a los consumidores.

Ejecuta comprobaciones de tipos estrictos y pruebas de contrato en CI antes de enviar. Para Capgo flujos de trabajo, verifica los valores de canal, compatibilidad nativa, paquetes firmados y comportamiento de rollback como reglas de lanzamiento tipadas — esto mantiene actualizaciones rápidas bajo control a medida que crecen los equipos, plataformas e integraciones.

¿Cómo Debería Tipificar Resultados Dinámicos Nativos?

No dejes que any se filtre en tu code cuando un método nativo devuelve datos impredecibles. En su lugar, escribe los campos que puedes confiar, marca valores genuinamente opcionales con ?y limpia la entrada incierta en la frontera antes de que nada la procese.

interface Resultado Nativo { éxito: boolean; valor?: string; }

async función leerValor(): Promesa const resultado = await NativePlugin.read(); return { éxito: Boolean(resultado.exito), valor: typeof resultado.valor === 'string' ? resultado.valor : undefined, };

Esta aproximación mantiene a tus llamados a salvo mientras hace explícita la incertidumbre en el tipo mismo. Para una mirada más amplia de este patrón de interfaz, revisa construir APIs en TypeScript.

¿Cómo Pueden Los Escuchadores Evitar Rechazos No Manejados?

Asíncronos callbacks necesitan ser defensivos por diseño. Capturar fallas dentro del propio escuchador en lugar de confiar en el sistema de eventos para silenciar promesas rechazadas.

const handleUpdate = (event: UpdateEvent): void => { void applyUpdate(event).catch((error: unknown) => { console.error(‘Falló la actualización’, error); }); };

Conservar la referencia de suscripción y eliminarla cuando el componente se desmonte. Esto previene llamadas duplicadas y actualizaciones de estado caducadas — la sección del ciclo de vida del escuchador explora esto en detalle.

Cada escuchador asíncrono necesita tanto un camino de error como un camino de limpieza.

Cómo Proteger Actualizaciones Capgo?

Las claves de firma y las credenciales administrativas permanecen en su servidor o sistema CI. Periodo. El cliente solo debe recibir paquetes firmados y utilizar resultados tipados para mostrar el estado — nunca para crear firmas.

Antes de publicar, configura uniones de canales separados, ejecuta comprobaciones de compatibilidad, configura límites de despliegue y planifica tu ruta de rollback. Capgo gestiona la entrega firmada, el control de canales, la aplicación de lanzamiento siguiente y la protección de rollback para Capacitor y aplicaciones de Electron. Sus documentos muestran cómo los flujos de trabajo de liberación tipados pueden estrechar su pipeline de actualización.