Beacon API
Beacon Getting Started
Learn how to implement Bluetooth Low Energy beacon detection with the OMX Beacon API.
Beacon API
Build with confidence
Implement precise indoor positioning and proximity detection using Bluetooth Low Energy (BLE) beacons. Create engaging micro-location experiences with iBeacon, Eddystone, and custom beacon protocols.
Installation & Setup
Get started with beacon proximity detection in just a few steps.
1
Install the package
Add the beacon module to your project
typescript
1# npm
2npm install @omx-sdk/core @omx-sdk/beacon
3
4# yarn
5yarn add @omx-sdk/core @omx-sdk/beacon
6
7# pnpm
8pnpm add @omx-sdk/core @omx-sdk/beacon
2
Initialize the client
Set up your OMX client and beacon service
typescript
1import { OMXClient } from '@omx-sdk/core';
2import { Beacon } from '@omx-sdk/beacon';
3
4const omx = new OMXClient({
5 clientId: 'your_client_id',
6 secretKey: 'your_secret_key'
7});
8
9const beacon = new Beacon(omx);
3
Register your first beacon
Register a beacon for proximity detection
typescript
1const ibeacon = await beacon.register({
2 type: 'ibeacon',
3 uuid: '550e8400-e29b-41d4-a716-446655440000',
4 major: 1,
5 minor: 100,
6 name: 'Store Entrance'
7});
8
9console.log('Beacon registered:', ibeacon.id);
Core Features
Powerful capabilities for proximity detection and indoor positioning.
Proximity Detection
Accurate distance measurements and zone-based proximity events.
Indoor Positioning
Triangulation-based positioning using multiple beacon references.
Bluetooth LE
Optimized for Bluetooth Low Energy with minimal battery impact.
Real-time Monitoring
Live proximity events and analytics for beacon interactions.
Beacon Registration
Register iBeacon and Eddystone beacons with location metadata.
typescript
1// Register an iBeacon
2const ibeacon = await beacon.register({
3 type: 'ibeacon',
4 uuid: '550e8400-e29b-41d4-a716-446655440000',
5 major: 1,
6 minor: 100,
7 name: 'Store Entrance',
8 location: {
9 name: 'Main Store Entrance',
10 address: '123 Main St, City, State'
11 }
12});
13
14// Register an Eddystone beacon
15const eddystone = await beacon.register({
16 type: 'eddystone',
17 namespaceId: '550e8400e29b41d4a716',
18 instanceId: '446655440000',
19 name: 'Product Display',
20 metadata: {
21 department: 'electronics',
22 section: 'smartphones'
23 }
24});
Proximity Detection
Set up proximity monitoring with custom zones and event handlers.
typescript
1// Set up proximity monitoring
2await beacon.startMonitoring({
3 beacons: ['beacon-id-1', 'beacon-id-2'],
4
5 // Proximity zones
6 zones: {
7 immediate: { distance: 0.5 }, // 0.5 meters
8 near: { distance: 3.0 }, // 3 meters
9 far: { distance: 10.0 } // 10 meters
10 },
11
12 // Event handlers
13 onEnter: (event) => {
14 console.log('Entered beacon range:', event.beacon);
15
16 // Trigger actions based on proximity
17 if (event.proximity === 'immediate') {
18 showProductDetails(event.beacon.metadata);
19 }
20 },
21
22 onExit: (event) => {
23 console.log('Exited beacon range:', event.beacon);
24 hideProductDetails();
25 },
26
27 onProximityChange: (event) => {
28 console.log('Proximity changed:', event.proximity);
29 updateUI(event.proximity);
30 }
31});
Indoor Positioning
Use multiple beacons for triangulation-based indoor positioning.
typescript
1// Set up multiple beacons for triangulation
2const positioning = await beacon.setupPositioning({
3 beacons: [
4 { id: 'beacon-1', x: 0, y: 0 },
5 { id: 'beacon-2', x: 10, y: 0 },
6 { id: 'beacon-3', x: 5, y: 10 }
7 ],
8
9 // Positioning algorithm
10 algorithm: 'trilateration',
11
12 // Update frequency
13 updateInterval: 1000, // ms
14
15 onPositionUpdate: (position) => {
16 console.log('Current position:', position);
17 updateMapMarker(position.x, position.y);
18 }
19});
Bluetooth & Location Permissions: Beacon functionality requires Bluetooth and location permissions on mobile devices. Ensure proper permission handling for the best user experience.
Beacon Analytics
Track beacon interaction analytics and visitor behavior patterns.
typescript
1// Get beacon interaction analytics
2const analytics = await beacon.getAnalytics({
3 beaconId: 'beacon-id',
4 period: 'last_7_days'
5});
6
7console.log('Total interactions:', analytics.totalInteractions);
8console.log('Unique visitors:', analytics.uniqueVisitors);
9console.log('Average dwell time:', analytics.averageDwellTime);
10console.log('Peak hours:', analytics.peakHours);
iOS Integration
Implement beacon monitoring using CoreLocation framework on iOS.
typescript
1// iOS CoreLocation setup
2import CoreLocation
3
4class BeaconManager: NSObject, CLLocationManagerDelegate {
5 let locationManager = CLLocationManager()
6
7 func startBeaconMonitoring() {
8 locationManager.delegate = self
9 locationManager.requestWhenInUseAuthorization()
10
11 let uuid = UUID(uuidString: "550e8400-e29b-41d4-a716-446655440000")!
12 let region = CLBeaconRegion(uuid: uuid, identifier: "Store")
13
14 locationManager.startMonitoring(for: region)
15 locationManager.startRangingBeacons(in: region)
16 }
17}
Android Integration
Set up beacon detection using Android Beacon Library.
typescript
1// Android Beacon Library setup
2public class BeaconActivity extends Activity implements BeaconConsumer {
3 private BeaconManager beaconManager;
4
5 @Override
6 protected void onCreate(Bundle savedInstanceState) {
7 super.onCreate(savedInstanceState);
8
9 beaconManager = BeaconManager.getInstanceForApplication(this);
10 beaconManager.getBeaconParsers().add(
11 new BeaconParser().setBeaconLayout("m:0-3=4c000215,i:4-19,i:20-21,i:22-23,p:24-24")
12 );
13 beaconManager.bind(this);
14 }
15}
Best Practices: Use appropriate scanning intervals to preserve battery life, implement signal filtering to reduce false positives, and position beacons at optimal heights for best performance.
Privacy Considerations: Be transparent about beacon usage and data collection. Implement proper consent mechanisms and clearly communicate how location data is used.
Next Steps
Now that you have beacon detection set up, explore these advanced guides.