Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-compass` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

npm install @capgo/capacitor-compass
npx cap sync

Importar

import { CapgoCompass } from '@capgo/capacitor-compass';

Inicio rápido

import { CapgoCompass } from '@capgo/capacitor-compass';

const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');

Ejemplo: startListening

import { CapgoCompass } from '@capgo/capacitor-compass';

// With default throttling (100ms interval, 2° minimum change)
await CapgoCompass.startListening();

// With custom throttling for high-frequency updates
await CapgoCompass.startListening({
  minInterval: 50,      // 50ms between events
  minHeadingChange: 1.0 // 1° minimum change
});

CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value);
});

Ejemplo: stopListening

import { CapgoCompass } from '@capgo/capacitor-compass';

await CapgoCompass.stopListening();

Errores comunes

• Permisos: llama a checkPermissions() luego requestPermissions() cuando sea necesario.
• Listeners: elimina los handles cuando se desmonten las pantallas.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Resumen de API

getCurrentHeading

Obtén la orientación actual de la brújula en grados. En iOS, la orientación se actualiza en segundo plano y se devuelve el último valor. En Android, la orientación se calcula al llamar al método usando los sensores acelerómetro y magnetómetro. No implementado en Web.

import { CapgoCompass } from '@capgo/capacitor-compass';

const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');

startListening

Empieza a escuchar los cambios de orientación de la brújula mediante eventos. Esto activa los sensores de la brújula y emite eventos ‘headingChange’.

import { CapgoCompass } from '@capgo/capacitor-compass';

// With default throttling (100ms interval, 2° minimum change)
await CapgoCompass.startListening();

// With custom throttling for high-frequency updates
await CapgoCompass.startListening({
  minInterval: 50,      // 50ms between events
  minHeadingChange: 1.0 // 1° minimum change
});

CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value);
});

stopListening

Deja de escuchar los cambios de rumbo de la brújula. Esto detiene los sensores de la brújula y deja de emitir eventos.

import { CapgoCompass } from '@capgo/capacitor-compass';

await CapgoCompass.stopListening();

checkPermissions

Comprueba el estado actual de los permisos para acceder a los datos de la brújula. En iOS, esto comprueba el estado del permiso de ubicación. En Android, siempre devuelve ‘granted’, ya que no se requieren permisos.

import { CapgoCompass } from '@capgo/capacitor-compass';

const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);

requestPermissions

Solicita permiso para acceder a los datos de la brújula. En iOS, solicita el permiso de ubicación (necesario para los datos de rumbo). En Android, se resuelve de inmediato, ya que no se requieren permisos.

import { CapgoCompass } from '@capgo/capacitor-compass';

const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
  // Can now use compass
}

watchAccuracy

Empieza a monitorizar la precisión de la brújula. En Android, monitoriza la precisión del magnetómetro y emite eventos accuracyChange. Los desarrolladores pueden escuchar estos eventos e implementar su propia UI para los prompts de calibración. En iOS y Web, este método no hace nada, ya que la monitorización de la precisión de la brújula no está disponible.

import { CapgoCompass, CompassAccuracy } from '@capgo/capacitor-compass';

// Start monitoring accuracy
await CapgoCompass.watchAccuracy();

// Listen for accuracy changes and implement custom UI
CapgoCompass.addListener('accuracyChange', (event) => {
  console.log('Accuracy changed to:', event.accuracy);
  if (event.accuracy < CompassAccuracy.MEDIUM) {
    // Show your custom calibration UI
  }
});

unwatchAccuracy

Deja de monitorear la precisión de la brújula. Esto detiene el monitoreo de precisión.

import { CapgoCompass } from '@capgo/capacitor-compass';

await CapgoCompass.unwatchAccuracy();

getAccuracy

Obtén el nivel de precisión actual de la brújula. En Android, devuelve la precisión actual del sensor magnetómetro. En iOS y Web, siempre devuelve CompassAccuracy.UNKNOWN ya que el monitoreo de precisión no está disponible.

import { CapgoCompass, CompassAccuracy } from '@capgo/capacitor-compass';

const { accuracy } = await CapgoCompass.getAccuracy();
if (accuracy < CompassAccuracy.MEDIUM) {
  console.log('Compass needs calibration');
}

Referencia de tipos

CompassHeading

Resultado que contiene el valor de la orientación de la brújula.

export interface CompassHeading {
  /** Compass heading in degrees (0-360) */
  value: number;
}

ListeningOptions

Opciones para configurar el comportamiento de escucha del compass.

export interface ListeningOptions {
  /**
   * Minimum interval between heading change events in milliseconds.
   * Lower values = more frequent updates but higher CPU/battery usage.
   *
   * @default 100
   * @since 8.1.4
   */
  minInterval?: number;

  /**
   * Minimum heading change in degrees required to trigger an event.
   * Lower values = more sensitive but more events.
   * Handles wraparound (e.g., 359° to 1° = 2° change).
   *
   * @default 2.0
   * @since 8.1.4
   */
  minHeadingChange?: number;
}

HeadingChangeEvent

Datos del evento para cambios de rumbo.

export interface HeadingChangeEvent {
  /** Compass heading in degrees (0-360) */
  value: number;
}

AccuracyChangeEvent

Datos del evento para cambios de precisión.

export interface AccuracyChangeEvent {
  /** Current accuracy level of the compass */
  accuracy: CompassAccuracy;
}

PermissionStatus

Estado de permisos para el plugin compass.

export interface PermissionStatus {
  /**
   * Permission state for accessing compass/location data.
   * On iOS, this requires location permission to access heading.
   * On Android, no special permissions are required for compass sensors.
   *
   * @since 7.0.0
   */
  compass: PermissionState;
}

CompassAccuracy

Constantes de nivel de precisión de Compass.

export enum CompassAccuracy {
  /** High accuracy - approximates to less than 5 degrees of error */
  HIGH = 3,
  /** Medium accuracy - approximates to less than 10 degrees of error */
  MEDIUM = 2,
  /** Low accuracy - approximates to less than 15 degrees of error */
  LOW = 1,
  /** Unreliable accuracy - approximates to more than 15 degrees of error */
  UNRELIABLE = 0,
  /** Unknown accuracy value */
  UNKNOWN = -1,
}

PermissionState

Estado de permiso para acceder a Compass.

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Uso de @capgo/capacitor-compass para la capacidad nativa en Uso de @capgo/capacitor-compass, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.