@capgo/capacitor-ibeacon 7.0.0

package/CapgoCapacitorIbeacon.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapgoCapacitorIbeacon'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Donadieu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapgoCapacitorIbeacon",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(
+            name: "CapgoCapacitorIbeacon",
+            targets: ["CapacitorIbeaconPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+    ],
+    targets: [
+        .target(
+            name: "CapacitorIbeaconPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/CapacitorIbeaconPlugin"),
+        .testTarget(
+            name: "CapacitorIbeaconPluginTests",
+            dependencies: ["CapacitorIbeaconPlugin"],
+            path: "ios/Tests/CapacitorIbeaconPluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,379 @@
+# capacitor-ibeacon
+  <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
+
+<div align="center">
+  <h2><a href="https://capgo.app/?ref=plugin"> ➡️ Get Instant updates for your App with Capgo</a></h2>
+  <h2><a href="https://capgo.app/consulting/?ref=plugin"> Missing a feature? We'll build the plugin for you 💪</a></h2>
+</div>
+
+iBeacon plugin for Capacitor - proximity detection and beacon region monitoring.
+
+## Documentation
+
+The most complete doc is available here: https://capgo.app/docs/plugins/ibeacon/
+
+## Install
+
+```bash
+npm install @capgo/capacitor-ibeacon
+npx cap sync
+```
+
+## Configuration
+
+### iOS
+
+Add the following to your `Info.plist`:
+
+```xml
+<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
+
+Add the following to your `AndroidManifest.xml`:
+
+```xml
+<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>
+```
+
+**Important**: For Android, you need to integrate the [AltBeacon](https://altbeacon.github.io/android-beacon-library/) library into your project for beacon detection to work.
+
+Add to your app's `build.gradle`:
+
+```gradle
+dependencies {
+    implementation 'org.altbeacon:android-beacon-library:2.20+'
+}
+```
+
+## API
+
+All methods are available through the `CapacitorIbeacon` object:
+
+```typescript
+import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
+```
+
+### startMonitoringForRegion(options: BeaconRegion)
+
+Start monitoring for a beacon region. Triggers events when entering/exiting the region.
+
+```typescript
+await CapacitorIbeacon.startMonitoringForRegion({
+  identifier: 'MyBeaconRegion',
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
+  major: 1,
+  minor: 2
+});
+```
+
+### stopMonitoringForRegion(options: BeaconRegion)
+
+Stop monitoring for a beacon region.
+
+```typescript
+await CapacitorIbeacon.stopMonitoringForRegion({
+  identifier: 'MyBeaconRegion',
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
+});
+```
+
+### startRangingBeaconsInRegion(options: BeaconRegion)
+
+Start ranging beacons in a region. Provides continuous distance updates.
+
+```typescript
+await CapacitorIbeacon.startRangingBeaconsInRegion({
+  identifier: 'MyBeaconRegion',
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
+});
+```
+
+### stopRangingBeaconsInRegion(options: BeaconRegion)
+
+Stop ranging beacons in a region.
+
+```typescript
+await CapacitorIbeacon.stopRangingBeaconsInRegion({
+  identifier: 'MyBeaconRegion',
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
+});
+```
+
+### startAdvertising(options: BeaconAdvertisingOptions)
+
+Start advertising the device as an iBeacon (iOS only).
+
+```typescript
+await CapacitorIbeacon.startAdvertising({
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
+  major: 1,
+  minor: 2,
+  identifier: 'MyBeacon'
+});
+```
+
+### stopAdvertising()
+
+Stop advertising the device as an iBeacon (iOS only).
+
+```typescript
+await CapacitorIbeacon.stopAdvertising();
+```
+
+### requestWhenInUseAuthorization()
+
+Request "When In Use" location authorization.
+
+```typescript
+const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
+console.log('Authorization status:', status);
+```
+
+### requestAlwaysAuthorization()
+
+Request "Always" location authorization (required for background monitoring).
+
+```typescript
+const { status } = await CapacitorIbeacon.requestAlwaysAuthorization();
+console.log('Authorization status:', status);
+```
+
+### getAuthorizationStatus()
+
+Get current location authorization status.
+
+```typescript
+const { status } = await CapacitorIbeacon.getAuthorizationStatus();
+// status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use'
+```
+
+### isBluetoothEnabled()
+
+Check if Bluetooth is enabled on the device.
+
+```typescript
+const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
+if (!enabled) {
+  console.log('Please enable Bluetooth');
+}
+```
+
+### isRangingAvailable()
+
+Check if ranging is available on the device.
+
+```typescript
+const { available } = await CapacitorIbeacon.isRangingAvailable();
+```
+
+### enableARMAFilter(options: { enabled: boolean })
+
+Enable ARMA filtering for distance calculations (Android only).
+
+```typescript
+await CapacitorIbeacon.enableARMAFilter({ enabled: true });
+```
+
+## Events
+
+Listen to beacon events using Capacitor's event system:
+
+```typescript
+import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
+import { PluginListenerHandle } from '@capacitor/core';
+
+// Listen for ranging events
+const rangingListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
+  'didRangeBeacons',
+  (data) => {
+    console.log('Beacons detected:', data.beacons);
+    data.beacons.forEach(beacon => {
+      console.log(`Beacon: ${beacon.uuid}, Distance: ${beacon.accuracy}m, Proximity: ${beacon.proximity}`);
+    });
+  }
+);
+
+// Listen for region enter events
+const enterListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
+  'didEnterRegion',
+  (data) => {
+    console.log('Entered region:', data.region.identifier);
+  }
+);
+
+// Listen for region exit events
+const exitListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
+  'didExitRegion',
+  (data) => {
+    console.log('Exited region:', data.region.identifier);
+  }
+);
+
+// Listen for region state changes
+const stateListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
+  'didDetermineStateForRegion',
+  (data) => {
+    console.log(`Region ${data.region.identifier}: ${data.state}`);
+  }
+);
+
+// Clean up listeners when done
+rangingListener.remove();
+enterListener.remove();
+exitListener.remove();
+stateListener.remove();
+```
+
+## Complete Example
+
+```typescript
+import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
+
+// Define your beacon region
+const beaconRegion = {
+  identifier: 'MyStore',
+  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
+  major: 1
+};
+
+async function setupBeaconMonitoring() {
+  try {
+    // Request permission
+    const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
+    
+    if (status !== 'authorized_when_in_use' && status !== 'authorized_always') {
+      console.error('Location permission denied');
+      return;
+    }
+
+    // Check if Bluetooth is enabled
+    const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
+    if (!enabled) {
+      console.error('Bluetooth is not enabled');
+      return;
+    }
+
+    // Set up event listeners
+    await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
+      console.log('Welcome! You entered:', data.region.identifier);
+      // Show welcome notification or trigger action
+    });
+
+    await CapacitorIbeacon.addListener('didExitRegion', (data) => {
+      console.log('Goodbye! You left:', data.region.identifier);
+    });
+
+    await CapacitorIbeacon.addListener('didRangeBeacons', (data) => {
+      data.beacons.forEach(beacon => {
+        console.log(`Beacon ${beacon.minor}: ${beacon.proximity} (${beacon.accuracy.toFixed(2)}m)`);
+      });
+    });
+
+    // Start monitoring
+    await CapacitorIbeacon.startMonitoringForRegion(beaconRegion);
+    console.log('Started monitoring for beacons');
+
+    // Start ranging for distance updates
+    await CapacitorIbeacon.startRangingBeaconsInRegion(beaconRegion);
+    console.log('Started ranging beacons');
+
+  } catch (error) {
+    console.error('Error setting up beacon monitoring:', error);
+  }
+}
+
+// Call the setup function
+setupBeaconMonitoring();
+```
+
+## TypeScript Types
+
+### BeaconRegion
+
+```typescript
+interface BeaconRegion {
+  identifier: string;
+  uuid: string;
+  major?: number;
+  minor?: number;
+  notifyEntryStateOnDisplay?: boolean;
+}
+```
+
+### Beacon
+
+```typescript
+interface Beacon {
+  uuid: string;
+  major: number;
+  minor: number;
+  rssi: number;
+  proximity: 'immediate' | 'near' | 'far' | 'unknown';
+  accuracy: number;
+}
+```
+
+### BeaconAdvertisingOptions
+
+```typescript
+interface BeaconAdvertisingOptions {
+  uuid: string;
+  major: number;
+  minor: number;
+  identifier: string;
+  measuredPower?: number;
+}
+```
+
+## Proximity Values
+
+- **immediate**: Very close to the beacon (within a few centimeters)
+- **near**: Relatively close to the beacon (within a couple of meters)
+- **far**: Further away from the beacon (10+ meters)
+- **unknown**: Distance cannot be determined
+
+## Important Notes
+
+1. **iOS Background Monitoring**: To monitor beacons in the background, you need "Always" location permission and the `location` background mode in Info.plist.
+
+2. **Android Library**: Android implementation requires the AltBeacon library to be integrated into your project.
+
+3. **Battery Usage**: Continuous beacon ranging can consume significant battery. Consider using monitoring (which is more battery-efficient) and only start ranging when needed.
+
+4. **UUID Format**: UUIDs must be in the standard format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`
+
+5. **Major/Minor Values**: These are optional 16-bit unsigned integers (0-65535) used to identify specific beacons within a UUID.
+
+6. **Permissions**: Always request and check permissions before starting beacon operations.
+
+## Credits
+
+This plugin was inspired by [cordova-plugin-ibeacon](https://github.com/petermetz/cordova-plugin-ibeacon) and adapted for Capacitor.
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this plugin.

package/android/build.gradle

@@ -0,0 +1,59 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+}
+
+buildscript {
+    repositories {
+        mavenCentral()
+        google()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "ee.forgr.plugin.capacitor_ibeacon"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    jcenter()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/java/ee/forgr/plugin/capacitor_ibeacon/CapacitorIbeaconPlugin.java

@@ -0,0 +1,171 @@
+package ee.forgr.plugin.capacitor_ibeacon;
+
+import android.Manifest;
+import android.bluetooth.BluetoothAdapter;
+import android.content.pm.PackageManager;
+import androidx.core.app.ActivityCompat;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import com.getcapacitor.annotation.Permission;
+
+@CapacitorPlugin(
+    name = "CapacitorIbeacon",
+    permissions = {
+        @Permission(alias = "location", strings = { 
+            Manifest.permission.ACCESS_FINE_LOCATION,
+            Manifest.permission.ACCESS_COARSE_LOCATION
+        }),
+        @Permission(alias = "bluetooth", strings = {
+            Manifest.permission.BLUETOOTH,
+            Manifest.permission.BLUETOOTH_ADMIN
+        })
+    }
+)
+public class CapacitorIbeaconPlugin extends Plugin {
+
+    private final String PLUGIN_VERSION = "0.0.1";
+
+    @Override
+    public void load() {
+        // Initialize beacon library if needed
+        // This requires adding a beacon library like AltBeacon
+    }
+
+    @PluginMethod
+    public void startMonitoringForRegion(PluginCall call) {
+        String identifier = call.getString("identifier");
+        String uuid = call.getString("uuid");
+        Integer major = call.getInt("major");
+        Integer minor = call.getInt("minor");
+
+        if (identifier == null || uuid == null) {
+            call.reject("Missing required parameters");
+            return
+;
+        }
+
+        // TODO: Implement beacon monitoring using AltBeacon or similar library
+        call.reject("Beacon monitoring requires AltBeacon library integration");
+    }
+
+    @PluginMethod
+    public void stopMonitoringForRegion(PluginCall call) {
+        String identifier = call.getString("identifier");
+        String uuid = call.getString("uuid");
+
+        if (identifier == null || uuid == null) {
+            call.reject("Missing required parameters");
+            return;
+        }
+
+        // TODO: Stop monitoring
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void startRangingBeaconsInRegion(PluginCall call) {
+        String identifier = call.getString("identifier");
+        String uuid = call.getString("uuid");
+        Integer major = call.getInt("major");
+        Integer minor = call.getInt("minor");
+
+        if (identifier == null || uuid == null) {
+            call.reject("Missing required parameters");
+            return;
+        }
+
+        // TODO: Implement beacon ranging
+        call.reject("Beacon ranging requires AltBeacon library integration");
+    }
+
+    @PluginMethod
+    public void stopRangingBeaconsInRegion(PluginCall call) {
+        String identifier = call.getString("identifier");
+        String uuid = call.getString("uuid");
+
+        if (identifier == null || uuid == null) {
+            call.reject("Missing required parameters");
+            return;
+        }
+
+        // TODO: Stop ranging
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void startAdvertising(PluginCall call) {
+        call.reject("Advertising is not supported on Android through this API");
+    }
+
+    @PluginMethod
+    public void stopAdvertising(PluginCall call) {
+        call.reject("Advertising is not supported on Android through this API");
+    }
+
+    @PluginMethod
+    public void requestWhenInUseAuthorization(PluginCall call) {
+        if (ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.ACCESS_FINE_LOCATION) 
+            != PackageManager.PERMISSION_GRANTED) {
+            requestPermissionForAlias("location", call, "locationPermissionCallback");
+        } else {
+            JSObject ret = new JSObject();
+            ret.put("status", "authorized_when_in_use");
+            call.resolve(ret);
+        }
+    }
+
+    @PluginMethod
+    public void requestAlwaysAuthorization(PluginCall call) {
+        requestWhenInUseAuthorization(call);
+    }
+
+    @PluginMethod
+    public void getAuthorizationStatus(PluginCall call) {
+        JSObject ret = new JSObject();
+        if (ActivityCompat.checkSelfPermission(getContext(), Manifest.permission.ACCESS_FINE_LOCATION) 
+            == PackageManager.PERMISSION_GRANTED) {
+            ret.put("status", "authorized_when_in_use");
+        } else {
+            ret.put("status", "denied");
+        }
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void isBluetoothEnabled(PluginCall call) {
+        JSObject ret = new JSObject();
+        BluetoothAdapter bluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
+        ret.put("enabled", bluetoothAdapter != null && bluetoothAdapter.isEnabled());
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void isRangingAvailable(PluginCall call) {
+        JSObject ret = new JSObject();
+        BluetoothAdapter bluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
+        ret.put("available", bluetoothAdapter != null);
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void enableARMAFilter(PluginCall call) {
+        Boolean enabled = call.getBoolean("enabled", false);
+        // TODO: Configure ARMA filter if using AltBeacon
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void getPluginVersion(final PluginCall call) {
+        try {
+            final JSObject ret = new JSObject();
+            ret.put("version", this.PLUGIN_VERSION);
+            call.resolve(ret);
+        } catch (final Exception e) {
+            call.reject("Could not get plugin version", e);
+        }
+    }
+}