电容器

从您的 Capacitor app 中检测到附近的iBeacons : 监视背景区域,距离范围信标,并在 iOS 上作为信标广告该设备. 为零售,场地和室内相近而建.

🤖 建筑与AI编码代理? 安装 Capgo 技能 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 @capgo/capacitor-ibeacon 在您的电容应用程序中: npx skills add Cap-go/capgo-skills。然后问你的经纪人: 添加@capgo/capor-ibeacon到我的 Capacitor app 并把它接上 代理设置指南 • 妇女 主机磁共振

主要特点

• 区域监测数字 : startMonitoringForRegion() 与 didEnterRegion, (中文(简体) ), didExitRegion 财务报告和审定财务报表 didDetermineStateForRegion 事件.
• 径行数字 : startRangingBeaconsInRegion() 发射 didRangeBeacons 还有附近的信标.
• IOS上的广告数字 : startAdvertising() 财务报告和审定财务报表 stopAdvertising() 将设备变成iBeacon.
• Android 的背景扫描数字 : enableBackgroundMode(), (中文(简体) ), setBackgroundScanPeriod() 财务报告和审定财务报表 enableARMAFilter() 为更稳的距离.
• 权限和状态: 地点授权请求, isBluetoothEnabled() 财务报告和审定财务报表 isRangingAvailable()。 。 。 .
• 平台: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. iOS使用Core Lace,Android使用AltBeacon库. 在网上不可用.

文档

这里有最完整的医生: https://capgo.app/docs/plugins/ibeacon/ 页面存档备份,存于互联网档案馆

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

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

然后使用下列提示:

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

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

npm install @capgo/capacitor-ibeacon
npx cap sync

配置

iOS系统

步骤1: 配置信息. plist

将以下密钥添加到您的 ios/App/App/Info.plist 文件 :

<!-- Required: Location permission for beacon detection -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to detect nearby beacons</string>

<!-- Required for background monitoring: Always authorization -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access to monitor beacons in the background</string>

<!-- Required: Bluetooth usage (iOS 13+) -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to detect nearby beacons</string>

<!-- Required for iOS 12 and earlier -->
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to detect and advertise as beacons</string>

<!-- Required for background beacon monitoring -->
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>bluetooth-central</string>
</array>

步骤2: 在 Xcode 中启用能力

1. 在 Xcode 中打开您的工程 : ios/App/App.xcworkspace
2. 选择您的应用目标
3. 转到“ 签名能力” 标签
4. 点击"+能力"并添加"背景模式"
5. 检查以下选项:
   • ✅ 地点更新 (用于背景信标监测)
   • ✅ 使用蓝牙LE附件 (信标检测所需)

需要权限

• 使用时: 前景信标测距和监测
• 永远: 用于背景信标监测(当应用程序不活动时检测信标)
• 蓝牙: 当信标使用 CoreLocation 时, 在 iOS 13+ 上自动授予

说明:插件使用CoreLocation进行信标检测,它内部处理蓝牙扫描. 只有当您的应用程序也使用Core Bluetooth用于其他目的(例如广告作为信标)时,才需要直接蓝牙权限.

机器人

插件自动包含所有所需的权限和依赖性. 不需要手动配置 .

权限包括:

• 位置权限( 细、 粗、 背景)
• 蓝牙权限(对Android QQ11有适当的遗产支持,对Android 12+有现代权限)
• 背景信标扫描的前景服务权限
• 完成持续监测许可

依赖性包括:

• AltBeacon Android灯塔图书馆(2.21.2)

重要内容: 您仍然需要使用插件的授权方法在运行时请求权限(见下文API部分).

API 密码

所有方法都可通过 CapacitorIbeacon 对象 :

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

启动监测格式( 选项: 灯塔格式)

开始监视信标区域 进入/出行区域时触发事件.

await CapacitorIbeacon.startMonitoringForRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  major: 1,
  minor: 2
});

停止监测监管( 选项: 灯塔监管)

停止监视信标区域.

await CapacitorIbeacon.stopMonitoringForRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});

启动 Ranging Beacons InRegion( 选项: 灯塔Region)

在一个区域开始测距信标。 提供连续距离更新.

await CapacitorIbeacon.startRangingBeaconsInRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});

停止 Ranging Beacons InRegion( 选项: 灯塔Region)

在一个区域停止测距信标.

await CapacitorIbeacon.stopRangingBeaconsInRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});

开始广告( 选项: 灯塔广告选项)

开始将该设备作为iBeacon(仅iOS)进行广告.

await CapacitorIbeacon.startAdvertising({
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  major: 1,
  minor: 2,
  identifier: 'MyBeacon'
});

停止广告 ()

停止将该设备作为iBeacon(仅iOS)进行广告.

await CapacitorIbeacon.stopAdvertising();

使用授权时请求 ()

请求"何时使用"定位授权.

const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
console.log('Authorization status:', status);

总是认证 ()

请求"永远"定位授权(背景监测需要).

const { status } = await CapacitorIbeacon.requestAlwaysAuthorization();
console.log('Authorization status:', status);

获取认证状态( C)

获取当前位置授权状态 .

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

是蓝牙可读( )

检查设备是否启用了蓝牙 .

const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
if (!enabled) {
  console.log('Please enable Bluetooth');
}

朗金- 瓦依勒( )

检查设备是否有测距 .

const { available } = await CapacitorIbeacon.isRangingAvailable();

启用ARMAFilter( 选项 : {已启用: 布尔} )

启用 ARMA 过滤以进行远程计算( 只有Android) .

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

Android 背景扫描

Android 8+需要一个前景服务,以使蓝牙扫描在背景中保持活性. 您可以选择一次, 插件会自动 当应用程序在前景和背景之间移动时切换背景扫描.

// Enable background scanning globally (Android only)
await CapacitorIbeacon.enableBackgroundMode({ enabled: true });

// Or opt in per call
await CapacitorIbeacon.startMonitoringForRegion({
  identifier: 'MyBeaconRegion',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  enableBackgroundMode: true,
});

您也可以通过 Capacitor 配置来启用 :

// capacitor.config.ts
plugins: {
  CapacitorIbeacon: {
    enableBackgroundMode: true,
  },
}

活动

使用 Capacitor 事件系统收听信标事件:

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();

完整示例

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();

类型脚本

灯塔注册

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

灯塔

interface Beacon {
  uuid: string;
  major: number;
  minor: number;
  rssi: number;
  proximity: 'immediate' | 'near' | 'far' | 'unknown';
  accuracy: number;
}

灯塔广告选项

interface BeaconAdvertisingOptions {
  uuid: string;
  major: number;
  minor: number;
  identifier: string;
  measuredPower?: number;
}

近似值

• 即时:非常靠近信标(几厘米以内)
• 相邻: 相对靠近信标(几米之内)
• 远: 离信标更远(10+米)
• 不详: 距离无法确定

重要说明

1. iOS 背景监测:要监视背景中的信标,需要:

   • “总是”地点授权(requestAlwaysAuthorization()(中文(简体) )
   • Xcode 中启用的背景模式能力
   • UIBackgroundModes 两者 location 财务报告和审定财务报表 bluetooth-central 在Info.plist中输入

2. iOS Xcode 配置: 仅添加Info.plist 密钥是不够的. 你个 必须 启用 Xcode 的背景模式能力(见上文配置部分)。 这是最常见的设置问题.

3. Android 图书馆: 此插件包括了自动的 AltBeacon Android Beacon 库 (2.21.2).

4. 电池使用量:连续信标测距可以消耗大量的电池. 考虑使用监测(这更能节能),并只在需要时才开始测距.

5. UUID 格式: UUID 必须是标准格式: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

6. 主要/次要价值:这些是用于在UUID内识别特定信标的可选的16位无符号整数(0-65535).

7. 权限: 启动信标操作前总是请求和检查权限.

解决问题

iOS问题

“未检测到的 Beacons”或“无法工作”

1. 验证Info.plist 配置数字 :

   • 确保所有所需的密钥都存在(见上文配置部分)
   • 检查权限描述是否有意义而非空

2. 在 Xcode 中启用背景模式数字 :

   • 这是一个常见的问题 - 您的 MUST 启用 Xcode 中的能力, 而不仅仅是添加 Info. plist 密钥
   • 打开 ios/App/App.xcworkspace xcode 编码
   • 选择目标 ~ “ 签名和能力 ”
   • 添加“ 背景模式” 能力
   • 请检查access-date=中的日期值 (帮助) "Location update"和"Uss Bluetooth LE 配件"

3. 请求适当授权数字 :

   // For foreground detection only
   await CapacitorIbeacon.requestWhenInUseAuthorization();
   
   // For background monitoring (required for region enter/exit events when app is closed)
   await CapacitorIbeacon.requestAlwaysAuthorization();
   

4. 选中蓝牙已启用数字 :

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

5. 核查授权状况数字 :

   const { status } = await CapacitorIbeacon.getAuthorizationStatus();
   console.log('Auth status:', status);
   // Should be 'authorized_when_in_use' or 'authorized_always'
   

6. 检查设备兼容性数字 :

   • iBeacon需要iOS 7.0+ (英语)
   • 一些功能需要特定的iOS版本(例如背景范围)
   • 使用 isRangingAvailable() 检查设备支持

"没有事件开火"或"增加听力不起作用"

• 确保设置听众 在此之前 开始监测/范围:

  // Set up listeners first
  await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
    console.log('Entered:', data.region.identifier);
  });
  
  // Then start monitoring
  await CapacitorIbeacon.startMonitoringForRegion({
    identifier: 'MyRegion',
    uuid: 'YOUR-UUID-HERE'
  });
  

背景监测不起作用

• 需要“ 永远” 授权 : requestAlwaysAuthorization()
• 一定是这样 UIBackgroundModes 与 location 财务报告和审定财务报表 bluetooth-central 在Info.plist中输入
• 必须在 Xcode 中启用背景模式能力
• iOS 可能会节流背景扫描以保存电池

安卓问题

见上文配置中的Android权限部分。 多数Android问题涉及:

• 不请求运行时间权限
• 在Android 8+上缺少前景服务
• 蓝牙未启用

详细的Android故障排除,请检查AltBeacon图书馆文档.

贷项

此插件的灵感来自 索多瓦-插图-贝贝康 并改编为Capacitor.

许可证

麻省理工学院

捐款

见 捐款额 关于如何为此插件贡献的详细信息.