expo-beacon 0.7.3 → 0.7.5

package/README.md

@@ -63,6 +63,8 @@ An Expo module for scanning, pairing, and monitoring **iBeacons** and **Eddyston
   - [destroyEventLogs()](#destroyeventlogs)
 - [Events](#events)
 - [TypeScript Types](#typescript-types)
+- [Native Integrations](#native-integrations)
+  - [react-native-background-geolocation](#react-native-background-geolocation)
 - [Background Behaviour](#background-behaviour)
 - [Notifications](#notifications)
 - [Platform-Specific Notes & Gotchas](#platform-specific-notes--gotchas)
@@ -1610,6 +1612,148 @@ type EventLogEntry = {
 
 ---
 
+## Native Integrations
+
+Dispatching work in response to beacon enter/exit events can be done at the native level, before the JS bridge is involved. expo-beacon exposes a plugin registry on both platforms for this purpose.
+
+When a plugin is registered, `onBeaconEnter` / `onBeaconExit` (and their Eddystone equivalents) are called synchronously inside the same choke point that fires the JS event — so the native side-effect is guaranteed even when the JS thread is sleeping.
+
+### react-native-background-geolocation
+
+This integration starts BGLocation when any beacon is entered and stops it when all beacons are exited.
+
+> **Requirement**: bare workflow or `npx expo prebuild`. Does not work with Expo Go.
+
+#### 1. Install packages
+
+```sh
+npx expo install expo-beacon react-native-background-geolocation
+```
+
+Follow [react-native-background-geolocation's native setup](https://transistorsoft.github.io/react-native-background-geolocation) — it requires extra Gradle / CocoaPods config and a license key.
+
+#### 2. Add the Expo config plugin
+
+In `app.json` (or `app.config.js`), add `expo-beacon/plugin/withBeaconBGLocation` to your plugins list:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      "expo-beacon/plugin/withBeaconBGLocation"
+    ]
+  }
+}
+```
+
+Then run prebuild to apply the native changes:
+
+```sh
+npx expo prebuild --clean
+```
+
+The plugin writes `BeaconGeoPlugin.swift` / `BeaconGeoPlugin.kt` into your native project and wires them up in `AppDelegate.swift` and `MainApplication.kt` automatically.
+
+#### 3. Configure BGLocation once at JS startup
+
+Call `ready()` once when your app starts, **not** inside a beacon callback:
+
+```ts
+import BackgroundGeolocation from 'react-native-background-geolocation';
+
+BackgroundGeolocation.ready({
+  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
+  distanceFilter: 10,
+  stopOnTerminate: false,
+  startOnBoot: true,
+  // ...your config
+});
+```
+
+#### How it works at runtime
+
+```
+Beacon region entered (native)
+  → BeaconForegroundService / ExpoBeaconModule (expo-beacon)
+  → BeaconPluginRegistry / BeaconLifecycleRegistry dispatches to plugins
+  → BeaconGeoPlugin.onBeaconEnter / beaconDidEnter
+  → BackgroundGeolocation.start()   ← native only, no JS bridge involved
+```
+
+---
+
+#### Manual wiring (without the config plugin)
+
+If you prefer not to use `expo prebuild` (e.g. you manage your native project manually), create the following files yourself after each `npx expo prebuild`:
+
+**iOS** — `ios/<AppName>/BeaconGeoPlugin.swift` (add to Xcode target):
+
+```swift
+import ExpoBeacon
+import TSLocationManager
+
+final class BeaconGeoPlugin: BeaconLifecycleDelegate {
+    func beaconDidEnter(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) {
+        TSLocationManager.sharedManager().start()
+    }
+    func beaconDidExit(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) {
+        TSLocationManager.sharedManager().stop()
+    }
+    func eddystoneDidEnter(identifier: String, namespace: String, instance: String, distance: Double) {
+        TSLocationManager.sharedManager().start()
+    }
+    func eddystoneDidExit(identifier: String, namespace: String, instance: String, distance: Double) {
+        TSLocationManager.sharedManager().stop()
+    }
+}
+```
+
+Register in `ios/<AppName>/AppDelegate.swift` **before** `super`:
+
+```swift
+import ExpoBeacon
+
+// in application(_:didFinishLaunchingWithOptions:):
+BeaconLifecycleRegistry.register(BeaconGeoPlugin()) // ← before super
+return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+```
+
+**Android** — `android/app/src/main/java/<pkg>/BeaconGeoPlugin.kt`:
+
+```kotlin
+package com.yourapp
+
+import android.content.Context
+import com.transistorsoft.locationmanager.adapter.BackgroundGeolocation
+import expo.modules.beacon.BeaconEventPlugin
+
+class BeaconGeoPlugin(ctx: Context) : BeaconEventPlugin {
+    private val bgGeo = BackgroundGeolocation.getInstance(ctx, null)
+
+    override fun onBeaconEnter(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) =
+        bgGeo.start(null)
+    override fun onBeaconExit(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) =
+        bgGeo.stop(null)
+    override fun onEddystoneEnter(identifier: String, namespace: String, instance: String, distance: Double) =
+        bgGeo.start(null)
+    override fun onEddystoneExit(identifier: String, namespace: String, instance: String, distance: Double) =
+        bgGeo.stop(null)
+}
+```
+
+Register in `MainApplication.kt` inside `onCreate()` after `super`:
+
+```kotlin
+import expo.modules.beacon.BeaconPluginRegistry
+
+override fun onCreate() {
+    super.onCreate()
+    BeaconPluginRegistry.register(BeaconGeoPlugin(this)) // ← after super
+}
+```
+
+---
+
 ## Background Behaviour
 
 ### Android

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "expo-beacon",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Expo module for scanning, pairing, and monitoring iBeacons on Android and iOS",
   "main": "build/index.js",
   "types": "build/index.d.ts",
+  "plugin": "./plugin/build/withBeaconBGLocation",
   "exports": {
     ".": {
       "import": "./build/index.js",
@@ -13,6 +14,7 @@
   },
   "files": [
     "build/",
+    "plugin/build/",
     "ios/",
     "android/src/",
     "android/build.gradle",
@@ -21,11 +23,12 @@
   ],
   "scripts": {
     "build": "expo-module build",
+    "build:plugin": "tsc -p plugin/tsconfig.json",
     "clean": "expo-module clean",
     "lint": "expo-module lint",
     "test": "expo-module test",
-    "prepare": "expo-module prepare",
-    "prepublishOnly": "expo-module prepublishOnly",
+    "prepare": "expo-module prepare && npm run build:plugin",
+    "prepublishOnly": "expo-module prepublishOnly && npm run build:plugin",
     "expo-module": "expo-module",
     "open:ios": "xed example/ios",
     "open:android": "open -a \"Android Studio\" example/android"
@@ -60,6 +63,7 @@
     "react-native": "0.83.2"
   },
   "peerDependencies": {
+    "@expo/config-plugins": "*",
     "expo": ">=51.0.0",
     "react": "*",
     "react-native": "*"

package/plugin/build/withBeaconBGLocation.d.ts

@@ -0,0 +1,4 @@
+import { ConfigPlugin } from '@expo/config-plugins';
+declare const _default: ConfigPlugin<void>;
+export default _default;
+//# sourceMappingURL=withBeaconBGLocation.d.ts.map

package/plugin/build/withBeaconBGLocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withBeaconBGLocation.d.ts","sourceRoot":"","sources":["../src/withBeaconBGLocation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAKb,MAAM,sBAAsB,CAAC;;AA4P9B,wBAIE"}

package/plugin/build/withBeaconBGLocation.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("@expo/config-plugins");
+const fs = require("fs");
+const path = require("path");
+// ─── Generated file contents ─────────────────────────────────────────────────
+const IOS_PLUGIN_SWIFT = `\
+import ExpoBeacon
+import TSLocationManager
+
+final class BeaconGeoPlugin: BeaconLifecycleDelegate {
+    func beaconDidEnter(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) {
+        TSLocationManager.sharedManager().start()
+    }
+    func beaconDidExit(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) {
+        TSLocationManager.sharedManager().stop()
+    }
+    func eddystoneDidEnter(identifier: String, namespace: String, instance: String, distance: Double) {
+        TSLocationManager.sharedManager().start()
+    }
+    func eddystoneDidExit(identifier: String, namespace: String, instance: String, distance: Double) {
+        TSLocationManager.sharedManager().stop()
+    }
+}
+`;
+function getAndroidPluginKotlin(packageName) {
+    return `\
+package ${packageName}
+
+import android.content.Context
+import com.transistorsoft.locationmanager.adapter.BackgroundGeolocation
+import expo.modules.beacon.BeaconEventPlugin
+
+class BeaconGeoPlugin(ctx: Context) : BeaconEventPlugin {
+    private val bgGeo = BackgroundGeolocation.getInstance(ctx, null)
+
+    override fun onBeaconEnter(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) =
+        bgGeo.start(null)
+    override fun onBeaconExit(identifier: String, uuid: String, major: Int, minor: Int, distance: Double) =
+        bgGeo.stop(null)
+    override fun onEddystoneEnter(identifier: String, namespace: String, instance: String, distance: Double) =
+        bgGeo.start(null)
+    override fun onEddystoneExit(identifier: String, namespace: String, instance: String, distance: Double) =
+        bgGeo.stop(null)
+}
+`;
+}
+// ─── iOS helpers ─────────────────────────────────────────────────────────────
+/**
+ * Finds the UUID (key) of a PBXGroup by name, handling both quoted and unquoted
+ * name values produced by node-xcode's parser.
+ */
+function findPBXGroupKeyByName(xcodeProject, name) {
+    var _a;
+    const pbxGroups = (_a = xcodeProject.hash.project.objects['PBXGroup']) !== null && _a !== void 0 ? _a : {};
+    for (const key of Object.keys(pbxGroups)) {
+        if (key.endsWith('_comment'))
+            continue;
+        const group = pbxGroups[key];
+        // node-xcode stores quoted strings with literal quote characters in the value.
+        if (group.name === `"${name}"` || group.name === name)
+            return key;
+    }
+    return null;
+}
+/** Returns true if a PBXFileReference for filename already exists (idempotency guard). */
+function isFileInXcodeProject(xcodeProject, filename) {
+    var _a;
+    const refs = (_a = xcodeProject.hash.project.objects['PBXFileReference']) !== null && _a !== void 0 ? _a : {};
+    return Object.values(refs).some((f) => typeof f === 'object' &&
+        f !== null &&
+        (f.path === `"${filename}"` || f.path === filename));
+}
+function modifySwiftAppDelegate(contents) {
+    // Insert `import ExpoBeacon` after the last existing import line.
+    if (!contents.includes('import ExpoBeacon')) {
+        const lines = contents.split('\n');
+        const lastImportIdx = lines.reduce((last, line, i) => (line.trimStart().startsWith('import ') ? i : last), -1);
+        if (lastImportIdx >= 0) {
+            lines.splice(lastImportIdx + 1, 0, 'import ExpoBeacon');
+            contents = lines.join('\n');
+        }
+    }
+    // Insert `BeaconLifecycleRegistry.register(BeaconGeoPlugin())` immediately
+    // before `return super.application(`, preserving indentation.
+    const marker = 'BeaconLifecycleRegistry.register(BeaconGeoPlugin())';
+    if (!contents.includes(marker)) {
+        contents = contents.replace(/([ \t]*)(return super\.application\()/, `$1${marker}\n$1$2`);
+    }
+    return contents;
+}
+// ─── Android helpers ─────────────────────────────────────────────────────────
+function modifyMainApplication(contents) {
+    const importLine = 'import expo.modules.beacon.BeaconPluginRegistry';
+    // Add missing import after the last existing import.
+    if (!contents.includes(importLine)) {
+        const lines = contents.split('\n');
+        const lastImportIdx = lines.reduce((last, line, i) => (line.trimStart().startsWith('import ') ? i : last), -1);
+        if (lastImportIdx >= 0) {
+            lines.splice(lastImportIdx + 1, 0, importLine);
+        }
+        else {
+            // No imports yet — insert after the package declaration.
+            const pkgIdx = lines.findIndex((l) => l.startsWith('package '));
+            lines.splice(pkgIdx >= 0 ? pkgIdx + 1 : 0, 0, '', importLine);
+        }
+        contents = lines.join('\n');
+    }
+    // Add registration call immediately after `super.onCreate()`.
+    const registration = '    BeaconPluginRegistry.register(BeaconGeoPlugin(this))';
+    if (!contents.includes('BeaconPluginRegistry.register(BeaconGeoPlugin(this))')) {
+        contents = contents.replace(/(super\.onCreate\(\)[ \t]*\n)/, `$1${registration}\n`);
+    }
+    return contents;
+}
+// ─── iOS plugin steps ────────────────────────────────────────────────────────
+const withBeaconIOSBGLocation = (config) => {
+    // Step 1 – write BeaconGeoPlugin.swift and add it to the Xcode project.
+    config = (0, config_plugins_1.withXcodeProject)(config, (config) => {
+        var _a;
+        const xcodeProject = config.modResults;
+        const { projectName, platformProjectRoot } = config.modRequest;
+        if (!projectName || !platformProjectRoot)
+            return config;
+        const swiftFilePath = path.join(platformProjectRoot, projectName, 'BeaconGeoPlugin.swift');
+        fs.writeFileSync(swiftFilePath, IOS_PLUGIN_SWIFT);
+        if (!isFileInXcodeProject(xcodeProject, 'BeaconGeoPlugin.swift')) {
+            const groupKey = (_a = findPBXGroupKeyByName(xcodeProject, projectName)) !== null && _a !== void 0 ? _a : undefined;
+            xcodeProject.addSourceFile('BeaconGeoPlugin.swift', null, groupKey !== null && groupKey !== void 0 ? groupKey : undefined);
+        }
+        return config;
+    });
+    // Step 2 – patch AppDelegate.swift to register the plugin before super.
+    config = (0, config_plugins_1.withAppDelegate)(config, (config) => {
+        if (config.modResults.language === 'swift') {
+            config.modResults.contents = modifySwiftAppDelegate(config.modResults.contents);
+        }
+        else {
+            console.warn('[expo-beacon] withBeaconBGLocation: AppDelegate is not Swift — ' +
+                'please add BeaconLifecycleRegistry.register(BeaconGeoPlugin()) manually.');
+        }
+        return config;
+    });
+    return config;
+};
+// ─── Android plugin steps ─────────────────────────────────────────────────────
+const withBeaconAndroidBGLocation = (config) => {
+    // Step 1 – write BeaconGeoPlugin.kt into the app source tree.
+    config = (0, config_plugins_1.withDangerousMod)(config, [
+        'android',
+        (config) => {
+            var _a;
+            const pkgName = (_a = config.android) === null || _a === void 0 ? void 0 : _a.package;
+            if (!pkgName) {
+                console.warn('[expo-beacon] android.package not set — BeaconGeoPlugin.kt was not written.');
+                return config;
+            }
+            const pkgPath = pkgName.replace(/\./g, '/');
+            const outputPath = path.join(config.modRequest.platformProjectRoot, 'app/src/main/java', pkgPath, 'BeaconGeoPlugin.kt');
+            fs.writeFileSync(outputPath, getAndroidPluginKotlin(pkgName));
+            return config;
+        },
+    ]);
+    // Step 2 – patch MainApplication (Kotlin or Java) to call register().
+    config = (0, config_plugins_1.withDangerousMod)(config, [
+        'android',
+        (config) => {
+            var _a;
+            const pkgName = (_a = config.android) === null || _a === void 0 ? void 0 : _a.package;
+            if (!pkgName)
+                return config;
+            const pkgPath = pkgName.replace(/\./g, '/');
+            const javaRoot = path.join(config.modRequest.platformProjectRoot, 'app/src/main/java', pkgPath);
+            // Support both Kotlin and Java MainApplication.
+            const mainAppPath = [
+                path.join(javaRoot, 'MainApplication.kt'),
+                path.join(javaRoot, 'MainApplication.java'),
+            ].find(fs.existsSync);
+            if (!mainAppPath) {
+                console.warn('[expo-beacon] MainApplication.kt / .java not found — ' +
+                    'please add BeaconPluginRegistry.register(BeaconGeoPlugin(this)) manually.');
+                return config;
+            }
+            const original = fs.readFileSync(mainAppPath, 'utf-8');
+            fs.writeFileSync(mainAppPath, modifyMainApplication(original));
+            return config;
+        },
+    ]);
+    return config;
+};
+// ─── Combined plugin ─────────────────────────────────────────────────────────
+const withBeaconBGLocation = (config) => {
+    config = withBeaconIOSBGLocation(config);
+    config = withBeaconAndroidBGLocation(config);
+    return config;
+};
+exports.default = (0, config_plugins_1.createRunOncePlugin)(withBeaconBGLocation, 'expo-beacon-bglocation', '1.0.0');