Erste Schritte

1. Paket installieren

   npm

   npm i @capgo/capacitor-ibeacon

   pnpm

   pnpm add @capgo/capacitor-ibeacon

   yarn

   yarn add @capgo/capacitor-ibeacon

   bun

   bun add @capgo/capacitor-ibeacon

2. Mit nativen Projekten synchronisieren

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Konfiguration

iOS Konfiguration

Fügen Sie Folgendes zu Ihrem Info.plist hinzu:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to detect nearby beacons</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access to monitor beacons in the background</string>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to detect nearby beacons</string>

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

Android Konfiguration

Fügen Sie Folgendes zu Ihrem AndroidManifest.xml hinzu:

<manifest>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.BLUETOOTH" />
  <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

Wichtig: Für Android müssen Sie die Bibliothek AltBeacon in Ihr Projekt integrieren, damit die Beacon-Erkennung funktioniert.

Fügen Sie build.gradle Ihrer App hinzu:

dependencies {
    implementation 'org.altbeacon:android-beacon-library:2.20+'
}

Nutzung

Grundeinrichtung

import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';

// Define your beacon region
const beaconRegion = {
  identifier: 'MyStore',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  major: 1, // Optional
  minor: 2  // Optional
};

Berechtigungen anfordern

// Request "When In Use" permission
const requestPermission = async () => {
  const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
  console.log('Permission status:', status);
  // status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use'
};

// Request "Always" permission (for background monitoring)
const requestAlwaysPermission = async () => {
  const { status } = await CapacitorIbeacon.requestAlwaysAuthorization();
  console.log('Always permission status:', status);
};

// Check current authorization status
const checkPermission = async () => {
  const { status } = await CapacitorIbeacon.getAuthorizationStatus();
  console.log('Current status:', status);
};

Überprüfen Sie die Gerätefunktionen

// Check if Bluetooth is enabled
const checkBluetooth = async () => {
  const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
  if (!enabled) {
    console.log('Please enable Bluetooth');
  }
};

// Check if ranging is available
const checkRanging = async () => {
  const { available } = await CapacitorIbeacon.isRangingAvailable();
  console.log('Ranging available:', available);
};

Beacon-Regionen überwachen

Die Überwachung erkennt, wenn Sie eine Beacon-Region betreten oder verlassen. Dies funktioniert im Hintergrund.

// Start monitoring
const startMonitoring = async () => {
  await CapacitorIbeacon.startMonitoringForRegion({
    identifier: 'MyStore',
    uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
    major: 1,
    minor: 2
  });
  console.log('Started monitoring for beacons');
};

// Stop monitoring
const stopMonitoring = async () => {
  await CapacitorIbeacon.stopMonitoringForRegion({
    identifier: 'MyStore',
    uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
  });
};

Reichweitenbaken

Ranging bietet kontinuierliche Updates zu nahegelegenen Beacons und deren Entfernungen. Dazu muss die App im Vordergrund sein.

// Start ranging
const startRanging = async () => {
  await CapacitorIbeacon.startRangingBeaconsInRegion({
    identifier: 'MyStore',
    uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
  });
  console.log('Started ranging beacons');
};

// Stop ranging
const stopRanging = async () => {
  await CapacitorIbeacon.stopRangingBeaconsInRegion({
    identifier: 'MyStore',
    uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
  });
};

Ereignisse anhören

import { PluginListenerHandle } from '@capacitor/core';

// Listen for ranging events (continuous distance updates)
const rangingListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didRangeBeacons',
  (data) => {
    console.log('Beacons detected:', data.beacons);
    data.beacons.forEach(beacon => {
      console.log(`UUID: ${beacon.uuid}`);
      console.log(`Major: ${beacon.major}, Minor: ${beacon.minor}`);
      console.log(`Distance: ${beacon.accuracy}m`);
      console.log(`Proximity: ${beacon.proximity}`); // immediate, near, far, unknown
      console.log(`RSSI: ${beacon.rssi}`);
    });
  }
);

// Listen for region enter events
const enterListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didEnterRegion',
  (data) => {
    console.log('Entered region:', data.region.identifier);
    // Show welcome notification or trigger action
  }
);

// Listen for region exit events
const exitListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didExitRegion',
  (data) => {
    console.log('Exited region:', data.region.identifier);
    // Trigger goodbye action
  }
);

// Listen for region state changes
const stateListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
  'didDetermineStateForRegion',
  (data) => {
    console.log(`Region ${data.region.identifier}: ${data.state}`);
    // state: 'inside' | 'outside' | 'unknown'
  }
);

// Clean up listeners when done
const cleanup = () => {
  rangingListener.remove();
  enterListener.remove();
  exitListener.remove();
  stateListener.remove();
};

Als iBeacon bewerben (nur iOS)

Verwandeln Sie Ihr Gerät in einen iBeacon-Sender.

// Start advertising
const startAdvertising = async () => {
  await CapacitorIbeacon.startAdvertising({
    uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
    major: 1,
    minor: 2,
    identifier: 'MyBeacon',
    measuredPower: -59 // Optional: calibrated power at 1 meter
  });
  console.log('Started advertising as iBeacon');
};

// Stop advertising
const stopAdvertising = async () => {
  await CapacitorIbeacon.stopAdvertising();
};

Vollständiges Beispiel

import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
import { PluginListenerHandle } from '@capacitor/core';

export class BeaconService {
  private listeners: PluginListenerHandle[] = [];

  async init() {
    // Request permissions
    const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();

    if (status !== 'authorized_when_in_use' && status !== 'authorized_always') {
      throw new Error('Location permission denied');
    }

    // Check Bluetooth
    const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
    if (!enabled) {
      throw new Error('Bluetooth is not enabled');
    }

    // Set up event listeners
    this.setupListeners();
  }

  private setupListeners() {
    this.listeners.push(
      await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
        console.log('Welcome! Entered:', data.region.identifier);
        this.onEnterRegion(data.region);
      })
    );

    this.listeners.push(
      await CapacitorIbeacon.addListener('didExitRegion', (data) => {
        console.log('Goodbye! Left:', data.region.identifier);
        this.onExitRegion(data.region);
      })
    );

    this.listeners.push(
      await CapacitorIbeacon.addListener('didRangeBeacons', (data) => {
        this.onRangeBeacons(data.beacons);
      })
    );
  }

  async startMonitoring(uuid: string, identifier: string, major?: number, minor?: number) {
    await CapacitorIbeacon.startMonitoringForRegion({
      identifier,
      uuid,
      major,
      minor
    });
  }

  async startRanging(uuid: string, identifier: string) {
    await CapacitorIbeacon.startRangingBeaconsInRegion({
      identifier,
      uuid
    });
  }

  private onEnterRegion(region: any) {
    // Handle region entry (e.g., show notification, trigger content)
    console.log('Entered beacon region:', region);
  }

  private onExitRegion(region: any) {
    // Handle region exit
    console.log('Left beacon region:', region);
  }

  private onRangeBeacons(beacons: any[]) {
    // Process beacon distances
    const nearestBeacon = beacons.reduce((nearest, beacon) => {
      return beacon.accuracy < nearest.accuracy ? beacon : nearest;
    }, beacons[0]);

    if (nearestBeacon) {
      console.log('Nearest beacon:', nearestBeacon);
      this.handleProximity(nearestBeacon);
    }
  }

  private handleProximity(beacon: any) {
    switch (beacon.proximity) {
      case 'immediate': // < 0.5m
        console.log('Very close to beacon');
        break;
      case 'near': // 0.5m - 3m
        console.log('Near beacon');
        break;
      case 'far': // > 3m
        console.log('Far from beacon');
        break;
      case 'unknown':
        console.log('Distance unknown');
        break;
    }
  }

  cleanup() {
    this.listeners.forEach(listener => listener.remove());
    this.listeners = [];
  }
}

API Referenz

startMonitoringForRegion(Optionen)

Beginnen Sie mit der Überwachung einer Beacon-Region. Löst Ereignisse beim Betreten/Verlassen aus.

interface BeaconRegion {
  identifier: string;
  uuid: string;
  major?: number;
  minor?: number;
  notifyEntryStateOnDisplay?: boolean;
}

await CapacitorIbeacon.startMonitoringForRegion(options);

stopMonitoringForRegion(Optionen)

Beenden Sie die Überwachung einer Beacon-Region.

await CapacitorIbeacon.stopMonitoringForRegion(options);

startRangingBeaconsInRegion(Optionen)

Starten Sie Messbaken in einer Region, um kontinuierliche Entfernungsaktualisierungen zu erhalten.

await CapacitorIbeacon.startRangingBeaconsInRegion(options);

stopRangingBeaconsInRegion(Optionen)

Stoppen Sie Entfernungsbaken in einer Region.

await CapacitorIbeacon.stopRangingBeaconsInRegion(options);

startAdvertising(Optionen)

Beginnen Sie mit der Werbung für das Gerät als iBeacon (nur iOS).

interface BeaconAdvertisingOptions {
  uuid: string;
  major: number;
  minor: number;
  identifier: string;
  measuredPower?: number; // Calibrated power at 1 meter
}

await CapacitorIbeacon.startAdvertising(options);

stopAdvertising()

Hören Sie auf, das Gerät als iBeacon zu bewerben.

await CapacitorIbeacon.stopAdvertising();

requestWhenInUseAuthorization()

Fordern Sie die Standortautorisierung „Bei Verwendung“ an.

const result = await CapacitorIbeacon.requestWhenInUseAuthorization();
// Returns: { status: string }

requestAlwaysAuthorization()

Fordern Sie die Standortberechtigung „Immer“ an (erforderlich für die Hintergrundüberwachung).

const result = await CapacitorIbeacon.requestAlwaysAuthorization();
// Returns: { status: string }

getAuthorizationStatus()

Erhalten Sie den aktuellen Status der Standortautorisierung.

const result = await CapacitorIbeacon.getAuthorizationStatus();
// Returns: { status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use' }

isBluetoothEnabled()

Überprüfen Sie, ob Bluetooth aktiviert ist.

const result = await CapacitorIbeacon.isBluetoothEnabled();
// Returns: { enabled: boolean }

isRangingAvailable()

Überprüfen Sie, ob die Bereichswahl auf dem Gerät verfügbar ist.

const result = await CapacitorIbeacon.isRangingAvailable();
// Returns: { available: boolean }

enableARMAFilter(Optionen)

Aktivieren Sie die ARMA-Filterung für Entfernungsberechnungen (nur Android).

await CapacitorIbeacon.enableARMAFilter({ enabled: true });

Ereignisse

didRangeBeacons

Wird ausgelöst, wenn während der Entfernungsmessung Beacons erkannt werden.

interface RangingEvent {
  region: BeaconRegion;
  beacons: Beacon[];
}

interface Beacon {
  uuid: string;
  major: number;
  minor: number;
  rssi: number; // Signal strength
  proximity: 'immediate' | 'near' | 'far' | 'unknown';
  accuracy: number; // Distance in meters
}

didEnterRegion

Wird beim Betreten einer überwachten Beacon-Region ausgelöst.

interface RegionEvent {
  region: BeaconRegion;
}

didExitRegion

Wird beim Verlassen einer überwachten Beacon-Region ausgelöst.

interface RegionEvent {
  region: BeaconRegion;
}

didDetermineStateForRegion

Wird ausgelöst, wenn der Regionsstatus ermittelt wird.

interface StateEvent {
  region: BeaconRegion;
  state: 'inside' | 'outside' | 'unknown';
}

Näherungswerte

• sofort: Sehr nah (< 0.5 meters)
• near: Relatively close (0.5 - 3 meters)
• far: Further away (> 3 Meter)
• unbekannt: Entfernung kann nicht bestimmt werden

Bewährte Methoden

1. Entsprechende Berechtigungen anfordern

   • Verwenden Sie „Bei Verwendung“ für Vordergrundfunktionen
   • Fordern Sie „Immer“ nur an, wenn Sie eine Hintergrundüberwachung benötigen
   • Erklären Sie deutlich, warum Sie einen Standortzugriff benötigen2. Bluetooth-Status verwalten

   const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
   if (!enabled) {
     // Prompt user to enable Bluetooth
   }

2. Batterieoptimierung

   • Verwenden Sie nach Möglichkeit eine Überwachung anstelle einer Entfernungsmessung (batterieeffizienter).
   • Stoppen Sie die Bereichswahl, wenn sie nicht aktiv benötigt wird
   • Erwägen Sie die Verwendung größerer Haupt-/Nebenbereiche, um die Verarbeitung zu reduzieren

3. Fehlerbehandlung

   try {
     await CapacitorIbeacon.startMonitoringForRegion(region);
   } catch (error) {
     console.error('Failed to start monitoring:', error);
   }

4. Räumen Sie die Zuhörer auf Entfernen Sie immer Ereignis-Listener, wenn die Bereitstellung einer Komponente aufgehoben wird, um Speicherlecks zu verhindern.

Plattformhinweise

iOS

• Erfordert iOS 10.0+
• Verwendet das native CoreLocation-Framework
• Unterstützt Hintergrundüberwachung mit der Berechtigung „Immer“.
• Kann mit CoreBluetooth als iBeacon werben
• Für die Entfernungsmessung muss sich die App im Vordergrund befinden

Android

• Erfordert Android 6.0 (API 23)+
• Verwendet die AltBeacon-Bibliothek
• Erfordert Standortberechtigungen, obwohl Beacons Bluetooth verwenden – Hintergrundüberwachung erfordert ACCESS_BACKGROUND_LOCATION (Android 10+)
• Kann nicht als iBeacon werben (Hardwareeinschränkung auf den meisten Geräten)

Web

– Wird auf der Webplattform nicht unterstützt

Häufige Anwendungsfälle

1. Proximity-Marketing: Lösen Sie Benachrichtigungen oder Inhalte aus, wenn sich Benutzer Ihrem Geschäft nähern
2. Indoor-Navigation: Führen Sie Benutzer mithilfe von Beacon-Wegpunkten durch Gebäude
3. Anwesenheitsverfolgung: Automatisches Einchecken, wenn Benutzer einen Standort betreten
4. Asset Tracking: Überwachen Sie Geräte- oder Bestandsbewegungen
5. Museumsführungen: Stellen Sie kontextbezogene Informationen bereit, wenn Besucher sich den Ausstellungen nähern
6. Smart Home: Automatisierungen basierend auf der Raumpräsenz auslösen

Fehlerbehebung

Beacons nicht erkannt

• Stellen Sie sicher, dass Bluetooth aktiviert ist
• Überprüfen Sie, ob Standortberechtigungen erteilt wurden
• Überprüfen Sie, ob die Beacon-UUID genau übereinstimmt (Groß- und Kleinschreibung beachten).
• Bestätigen Sie, dass die Bake mit Strom versorgt wird und sendet
• Versuchen Sie es zunächst ohne Haupt-/Nebenfilter

Hintergrundüberwachung funktioniert nicht

• Stellen Sie sicher, dass die Standortberechtigung „Immer“ erteilt ist – location zu UIBackgroundModes hinzufügen (iOS)
• ACCESS_BACKGROUND_LOCATION anfordern (Android 10+)
• Hinweis: iOS kann Hintergrundrückrufe verzögern, um Batterie zu sparen

Entfernungsmessungen ungenau

• Beacon RSSI variiert je nach Umgebung (Wände, Störungen)
• Verwenden Sie mehrere Beacons zur Triangulation
• Kalibrieren Sie die gemessene Leistung 1 Meter von der Bake entfernt – Aktivieren Sie die ARMA-Filterung auf Android für glattere Werte