bearound_flutter_sdk

Fixed

• The iOS Bluetooth alert no longer pops up over other apps (BearoundSDK 3.8.2). Both
  CBCentralManager instances in the native iOS SDK were created without
  CBCentralManagerOptionShowPowerAlertKey, which defaults to true: with the radio off or
  the Bluetooth permission denied, iOS answered that instantiation with its own alert. Because
  the SDK wakes in the background, the alert surfaced on top of whatever app the user had
  open — the host app's name showing up in an alert while the user was somewhere else. Nothing
  changes functionally: scanning was already gated on the radio being powered on, so a user
  with Bluetooth off simply doesn't scan — now silently. The first-time authorization prompt
  is a different mechanism and is unaffected.

Fixed

• requestPermissions() no longer asks for ACCESS_BACKGROUND_LOCATION on Android.
  Google Play requires the host app to show a prominent disclosure before any
  background-location request, and the SDK asking on its own took that ordering away: the
  system screen appeared regardless of what the user answered to the app's disclosure —
  including when they declined — which also makes the demonstration video Play requires
  impossible to record honestly. It is now opt-in:

  await BearoundFlutterSdk.requestPermissions(includeBackgroundLocation: true);

  This changes behaviour. Without that flag a backgrounded app stops receiving Wi-Fi
  access points (wifis[] arrives empty, with no error — Android returns the placeholder
  BSSID 02:00:00:00:00:00). If your app already shows a disclosure and wants the
  access-point map in background, pass true after showing it. Beacon detection, encounters,
  location and the presence heartbeat are unaffected — on Android 12+ the scan runs on
  BLUETOOTH_SCAN alone. This matches the React Native SDK, which already required an
  explicit opt-in.

Documentation

• The README claimed requestPermissions() was "a no-op that returns true" on Android. That
  is true only of the native method-channel handler; the Dart side requests BLUETOOTH_SCAN,
  BLUETOOTH_CONNECT, foreground location, notifications and (13+) NEARBY_WIFI_DEVICES.
  Quick Start, the API table and the troubleshooting rows were all corrected, and a
  Background location (Android) section now spells out the trade-off.

Fixed

• Debug notifications went silent on a background relaunch. The switch could only be
  flipped from Dart, and both Dart-side paths need the engine running — so when iOS relaunched
  the app in the background on a region event, the plugin took delegate callbacks while the
  flag was still off and every notification was swallowed. That is precisely the case the
  notifications exist to observe. A host-settable native switch now sits alongside the Dart
  one; either arms them.

Changed

• Native SDKs pinned to 3.8.1, which carries the fix for encounter_mesh and
  presence_heartbeat never reaching the payload — until now every beacon-less upload was
  labelled as an ordinary timer sync, so a presence report was indistinguishable from a
  regular one on the backend.

Co-Authored-By: Claude Opus 4.8 (1M context) [email protected]

Co-Authored-By: Claude Fable 5 [email protected]

Changed

• Native SDKs bumped to 3.6.3 (iOS + Android) — background detections now deliver to the ingest in seconds instead of minutes (device-matrix top-5 #1). iOS: immediate-first upload inside the execution window (background-session uploads started in background are discretionary and were deferred for minutes), stuck-sync watchdog, BGTask/push handlers that wait for the upload, foreground flush. Android: immediate flush on every background detection (the periodic timer freezes in Doze), goAsync() broadcast window, expedited one-shot sync worker with network constraint, periodic worker that awaits the upload. Field-validated on iPhone 17 Pro Max (iOS 27 beta): foreground launch→backend 14s; continuous seconds-level delivery in background; terminated wake delivering in the same second. No Dart API changes.

Changed

• Native SDKs bumped to the 3.6 line — iOS BearoundSDK 3.6.2 and Android bearound-android-sdk v3.6.1, carrying the full background/reliability package:
  • iOS — background detection unlocked: state-dependent BLE scan filter (nil foreground / 0xBEAD background, pairs with beacon firmware v6) plus presence integrity — kernel region exits are confirmed before being propagated (no more false "left the zone" while parked next to a beacon), CLRegionState.unknown is preserved, cold relaunches survive until the region state resolves, and the Location-only permission profile (no Bluetooth) now detects and syncs end-to-end.
  • iOS — coordinated sync: single funnel for all triggers, detection-driven uploads (~seconds after entering a zone), 5 s foreground fast-path for changed samples, 1 s background batch window, and a 60 s per-beacon re-report that cuts steady-state volume ~4× without changing the ingest contract.
  • iOS — device floor back to iOS 15 and honest platform-guarantees documentation.
  • Android — ghost-beacon fixes: controller "fossil replay" guard (MediaTek batch-buffer re-delivery), zombie synced-card release, and a periodic scan watchdog that keeps recovering the scan instead of dying with it.

fix: bump ErrorReporter _sdkVersion literal to 3.5.2 (release gate) (…

Changed

• Android native SDK v3.5.0 → v3.5.2 (3.5.1 was never published for this wrapper; this release carries both). Scan reliability on modern Android 13+ (anti-downgrade refresh, pure-0xBEAD batch filter, PendingIntent kept armed in foreground), continuous hardware-managed duty for MEDIUM/LOW (no more scan-start-quota starvation), adaptive foreground boost (LOW_LATENCY whenever the app is in use — best detection automatically with the MEDIUM default), smooth beacon presence (10 s stale fade / 15 s eviction), weak-receiver SoC profile (Unisoc/Spreadtrum devices get doubled retention windows automatically), ghost-beacon fixes and precision-apply fix. No Dart API changes.
• iOS native pin stays on 3.5.1 (same 3.5.x line — the Android patches are platform-specific).
• Android native SDK v3.5.0 → v3.5.1. Scan reliability on modern Android 13+ (periodic anti-downgrade scan refresh, batch-scan filter for pure-0xBEAD frames from firmware v4 beacons, PendingIntent scan kept armed in foreground), ghost-beacon fixes on the host list (expirations now reach the listener, including the empty list) and scan-precision changes now apply immediately on reconfigure. No Dart API changes — all fixes live in the embedded native SDK. See the native SDK CHANGELOG for full details.

3.5.0

Added

• Silent-push wake-up bridge (Android): BearoundFlutterSdk.handleRemoteMessage(data) — forward the FCM data message from your firebase_messaging background handler to trigger an on-demand scan + sync (returns true only for Bearound wake-ups). See README → Silent-push wake-up (Android).

Changed

• Wraps native iOS 3.5.0 (BLE scan fix — beacons detect again; regression since 2.3.2) and Android v3.5.0 (silent-push wake-up + never-crash-the-host hardening).

Published on pub.dev.

Added

• Silent-push wake-up bridge (Android): new BearoundFlutterSdk.handleRemoteMessage(Map<String, String> data) — forward the FCM data message from your firebase_messaging background handler and the SDK triggers an on-demand scan + sync (returns true only for Bearound wake-ups, marked bearound). See README → Silent-push wake-up (Android).

Changed

• Wraps native iOS 3.5.0 (BLE scan fix: withServices: nil + Service Data 0xBEAD match — beacons detect again; regression since 2.3.2) and Android v3.5.0 (silent-push wake-up + never-crash-the-host hardening).

test(never-crash): make getPersistedLog telemetry test deterministic …

Added

• Dart-layer error telemetry (ErrorReporter). The plugin now captures uncaught Dart/Flutter errors originating in package:bearound_flutter_sdk (via chained FlutterError.onError + PlatformDispatcher.onError) and ships them fire-and-forget to POST https://ingest.bearound.io/sdk-errors, matching the Android native ErrorReporter contract (sdk.platform: "flutter"). Installed automatically on configure(). Ownership is decided by the first application frame (skipping the dart:/package:flutter runtime and the telemetry file itself) — only errors that ORIGINATE in the plugin are reported; a host error that merely passes through an SDK callback is never captured. Isolated transport (dart:io HttpClient, 5 s timeouts), in-memory rate limit (20/h) + 5 min dedupe, stack capped at 8000 chars, permission snapshot via permission_handler (read without prompting). The handlers are always chained (the previous FlutterError.onError is kept and invoked; PlatformDispatcher.onError returns false) so the host's error flow is never hijacked or broken. Native crashes keep being captured by the embedded native SDKs — this only adds the Dart layer they cannot see. No new dependency.
• BearoundFlutterSdk.setErrorReportingEnabled(bool) — public opt-out for the Dart-layer telemetry (default: enabled). No-op for native crash capture, which is independent.
• Background-reliability API (Android): isIgnoringBatteryOptimizations(), openBatteryOptimizationSettings(), isAutostartManageable(), openManufacturerAutostartSettings() — exposes the native helpers to keep the process eligible to wake under Doze and aggressive OEM battery managers (Xiaomi/Huawei/Oppo/Vivo/OnePlus/Letv). No location, no Google Play policy impact (uses the Settings screen, not the restricted permission). No-op on iOS (no equivalent restriction).
• errorStream replay buffer. The wrapper now eagerly subscribes to the native error channel on the first errorStream access and buffers up to 16 errors emitted before the app's first listen(); the first listener receives them replayed in order. Fixes the class of bug where an error on the very first startScanning() (e.g. a permission/configuration failure) fired before the app attached its listener and was lost forever.
• setDebugNotificationsEnabled(bool) + configure(debugNotifications:) (iOS-only, default false) — QA aid that posts a visible local notification per silent-push-triggered scan. Silent no-op on Android. Keep false in production.

Fixed

• Never-crash-the-host hardening (Dart layer). Three fixes from the cross-platform crash-safety audit: (1) PlatformDispatcher.onError now CHAINS a pre-existing host handler (e.g. Crashlytics) instead of silently replacing it — the previous handler is captured, always delegated to, and its return value honored; (2) the plugin's internal error-stream subscription gained an onError guard — an EventChannel failure no longer surfaces as an unhandled async error attributed to the SDK inside the host app (it is swallowed and reported to error telemetry via the new ErrorReporter.reportCaught); (3) telemetry reports were labeled with the previous version (3.4.4) — now 3.4.5. Doctrine: the SDK may fail silently, but it must NEVER crash the host — and every silent failure is reported to POST /sdk-errors.
• Never-crash-the-host hardening (bridge + edge paths), from the pre-merge review. (1) The Android onMethodCall dispatch is now wrapped in a catch (Throwable) — the Flutter engine only converts RuntimeException into a PlatformException, so a linkage Error (e.g. NoSuchMethodError when the host's Gradle resolution downgrades the native SDK) used to kill the host process; it now surfaces as a catchable PlatformException (BEAROUND_INTERNAL). Same guard on onAttachedToEngine. (2) setDebugNotificationsEnabled gained the missing Android stub — it was documented as a silent no-op but actually threw MissingPluginException into the host. (3) getPersistedLog()/getPersistedLogRaw() no longer throw FormatException on malformed JSON from the native side (degrade to [] + report). (4) The Dart telemetry is installed BEFORE the native configure() call, so the session where configure itself fails — exactly the one that needs visibility — is covered. (5) PermissionService failures now report to /sdk-errors before returning false (silent for the host, visible to us). (6) The telemetry origin markers are anchored to the full package:bearound_flutter_sdk/ URI — a host file merely named after the SDK (e.g. bearound_flutter_sdk_helper.dart) can no longer have its errors misattributed to (and collected by) the SDK.
• AuthorizationStatus parsing (Android). The native side reports snake_case statuses (always, when_in_use, not_determined…); the Dart enum now parses them correctly instead of falling back to notDetermined, so getAuthorizationStatus() reflects the real permission state on Android.

Changed

• requestPermissions()/checkPermissions() semantics on Android 12+ (behavior change). Both now mirror the native 3.4.5 scan gate: only BLUETOOTH_SCAN ("Nearby devices") unlocks detection — location alone is no longer treated as sufficient, so an app that only holds location permissions now gets false where it previously got true. This reflects reality: since the manifest asserts neverForLocation, the OS never delivered scan results to the location-only path anyway; the old true was a false positive that masked "no beacons detected" complaints. On Android <12 the legacy location-based gate is unchanged.

• Bumped native SDKs to 3.4.5 (Android + iOS). Android: DX audit + error telemetry + never-crash-the-host hardening (safe no-op on blank token; graceful degradation on devices without a Bluetooth radio) + two crash/robustness fixes — (1) a second FGS crash mode (ForegroundServiceStartNotAllowedException, started from the background on Android 14+; the 3.4.4 fix only covered the permission-missing SecurityException); (2) checkPermissions now requires BLUETOOTH_SCAN on Android 12+, so the location-only path stops attempting a scan the OS blocks (no more caught-SecurityException log spam). iOS: DX audit + error telemetry + never-crash-the-host hardening (CoreBluetooth state restoration gated on the host's bluetooth-central background mode) (BearoundSDK pin 3.4.2 → 3.4.5).

[3.4.4]

Changed

• Bumped native Android SDK to 3.4.4. Brings two Android improvements to Flutter apps: (1) a crash fix — no more SecurityException/crash-loop when the user denies "Nearby devices" while foreground scanning is enabled on Android 14+; (2) background-reliability helpers (battery-optimization exemption + OEM autostart deep-links, no location, no Google Play policy impact). The crash fix is automatic (no Dart change); the reliability helpers are native-only for now. iOS pin unchanged (BearoundSDK 3.4.2).

Changed

• Bumped native Android SDK to 3.4.4. Brings two Android improvements to Flutter apps: (1) a crash fix — the SDK no longer crashes with SecurityException/crash-loop when the user denies "Nearby devices" while foreground scanning is enabled on Android 14+; (2) background-reliability helpers (battery-optimization exemption + OEM autostart deep-links, no location, no Google Play policy impact). The crash fix is automatic (no Dart change); the reliability helpers are native-only for now (not yet exposed on the Flutter method channel).

Added

• iOS: notificação local ao processar silent push. O plugin agora exibe uma notificação "Push → Scan" quando o SDK trata um silent push do backend (callback didCompletePushScan), espelhando o app nativo BeAroundScan. Depende da configuração de push no app cliente — ver a seção "Push notifications & background wakeup" no README.

Changed

• README: guia de setup de push notifications & background wakeup (iOS). Documenta como habilitar silent push e region/beacon wakeup no Flutter 3.41+: entitlement aps-environment, remote-notification no UIBackgroundModes, a desativação da UIScene (_UIApplicationSceneManifest) e o override do didReceiveRemoteNotification que contorna o flutter#155479. O example/ é a implementação de referência (validada em device iOS 26). SDK nativo inalterado (BearoundSDK 3.4.2).

Fixed

• Android: removidas USE_EXACT_ALARM e SCHEDULE_EXACT_ALARM (via SDK nativo 3.4.2). O SDK não é app de "agenda"/"despertador" e não qualifica para alarme exato no Google Play (a Play Console exige a remoção, senão pede a declaração de "Alarmes exatos"). O watchdog de scan passou a usar alarme inexato (setAndAllowWhileIdle) — o scan periódico (WorkManager + watchdog) continua funcionando, sem permissão de alarme exato. iOS não afetado.

Fixed

• Push token à prova de ordem (SDKs nativos iOS/Android 3.4.1). setPushToken, quando o scan já está ativo e o token ainda não foi enviado, força um register na hora (beacons:[] + token) em vez de esperar o próximo sync. O token chega ao backend independente de o app chamar setPushToken antes ou depois de startScanning — antes, se o register-on-init já tivesse ocorrido, o device ficava sem push até o próximo register (TTL) ou até detectar um beacon.
• Android: push token agora é encaminhado ao SDK nativo. O handler setPushToken do wrapper Android descartava o token (no-op herdado de quando o SDK Android não tinha o setter); agora chama BeAroundSDK.setPushToken (disponível no nativo Android ≥ 3.4.0), então o token fornecido pelo app chega ao backend. iOS já encaminhava.
• Doc de setPushToken: no iOS, prefira o token APNs cru (getAPNSToken()) — é o que o backend usa; o swizzle automático falha quando o Firebase está presente.

Added

• Device register on init (via native SDKs 3.4.0). The device reports to the backend on startScanning() even before detecting a beacon, so it appears in the Control Hub on first launch. No API change — handled by the native SDK.
• Scan modes documentation. README documents the two Android background-scan strategies (opportunistic vs connectedDevice foreground service) with trade-offs, scan-window cadence, and a WorkManager note.

Changed

• Foreground-service notification. Title defaults to the host app's own name (android:label, localized by the device); subtitle is a generic, localized string ("Atualizando conteúdo" / "Updating content") — no Bluetooth or "reading data" wording. Clients can still override both.
• Bumped native SDKs to 3.4.0 (Android bearound-android-sdk, iOS BearoundSDK).

Changed

• Native SDKs bumped to 3.3.1 (both platforms). Three correctness fixes around BLE zone presence:

  1. Phantom zone exit→enter flap (~1ms apart, every 5-10 min, device stationary inside zone) — cleanup-immune lastBeaconSeenAt + grace bumped 60s → 300s.
  2. iOS-only: CoreLocation daemon churn → BLE delivery stalls. Five CLLocationManager() throwaways replaced with a single lifetime-scoped instance.
  3. Phantom ENTER after OS termination + state restoration (iOS) / PendingIntent wake (Android). Zone state persisted to UserDefaults / SharedPreferences and restored on cold start; snapshots > 1h are stale and ignored.

  Pins:

  • iOS: BearoundSDK 3.3.1
  • Android: com.github.Bearound:bearound-android-sdk:3.3.1

  No bridge-level changes — pure native bump. See native CHANGELOGs for root-cause details.

⚠️ Breaking Changes

• configure() API: replaced foregroundScanInterval and backgroundScanInterval (ForegroundScanInterval / BackgroundScanInterval enums) with a single unified scanPrecision: ScanPrecision parameter, matching the native iOS/Android v2.4.0 API.
  • Before: BearoundFlutterSdk.configure(businessToken: ..., foregroundScanInterval: ForegroundScanInterval.seconds15, backgroundScanInterval: BackgroundScanInterval.seconds30, maxQueuedPayloads: ...)
  • After: BearoundFlutterSdk.configure(businessToken: ..., scanPrecision: ScanPrecision.medium, maxQueuedPayloads: ...)
• The ForegroundScanInterval and BackgroundScanInterval enums have been removed. Migrate to ScanPrecision.high / medium / low.

Changed

• Native SDKs bumped to v2.4.0:
  • Android: com.github.Bearound:bearound-android-sdk:2.4.0 (dropped legacy v prefix per JitPack cache compat)
  • iOS: BearoundSDK ~> 2.4.0
• Location is now strictly beacon-gated (mirrors native v2.4.0 doctrine). GPS and active BLE scanning only run while the device is inside a beacon region. Outside the region, only kernel-level region monitoring stays on — effectively zero battery cost.

Added

• 3 new event channels surfaced from the native SDKs:
  • bearound_flutter_sdk/beacon_region — region enter/exit transitions
  • bearound_flutter_sdk/active_scan — active scanning toggle state
  • bearound_flutter_sdk/location_capture — beacon-triggered GPS window lifecycle (started / completed)
• 3 new Dart streams on BearoundFlutterSdk:
  • beaconRegionStream → Stream<BeaconRegionEvent> (with isEnter / isExit helpers)
  • activeScanStream → Stream<ActiveScanEvent> (isActive boolean)
  • locationCaptureStream → Stream<LocationCaptureResult> (discriminated by isStarted / isCompleted)
• New models: LocationCaptureResult, CapturedLocation, BeaconRegionEvent, ActiveScanEvent, ScanPrecision.
• Example app gains a Debug Geofence card (visible in the Status tab) showing GPS policy banner (green ✅ / red ⛔), live entry/exit timestamps with 1Hz ticking ages, capture counter, last fix coordinates, and a rolling 30-event log with color-coded chips.

Battery impact

For apps that spend most of their time outside any beacon region, this release drops CoreLocation + BLE active duty cycle to ~0 outside the region. Expect noticeable battery savings on users who carry the app but rarely encounter beacons.

Changed

• Native SDKs Updated to v2.3.7:
  • Android: com.github.Bearound:bearound-android-sdk:v2.3.7
  • iOS: BearoundSDK ~> 2.3.7

Changed

• Native SDKs Updated to v2.3.6:
  • Android: com.github.Bearound:bearound-android-sdk:v2.3.6
  • iOS: BearoundSDK ~> 2.3.6

Changed

• Native SDKs Updated to v2.3.5:
  • Android: com.github.Bearound:bearound-android-sdk:v2.3.5
  • iOS: BearoundSDK ~> 2.3.5
• Documentation: Updated README to reflect native SDK v2.3.5 alignment and package version.

Changed

• Native SDKs Updated to v2.3.2:
  • Android: com.github.Bearound:bearound-android-sdk:v2.3.2
  • iOS: BearoundSDK ~> 2.3.2
• Documentation: Updated README to reflect native SDK v2.3.2 alignment and package version.

Changed

• Native SDKs Updated:
  • Android: com.github.Bearound:bearound-android-sdk:v2.3.0
  • iOS: BearoundSDK ~> 2.3.0

Added

• Bluetooth-only (BT) proximity fallback: New BeaconProximity.bt value for beacons detected via Bluetooth scanning only, without CoreLocation/distance estimation.

Technical Details

• Native SDK v2.3.0 Changes:
  • Added BT proximity for bluetooth-only fallback detection
  • Improved beacon structure with discovery source tracking

Changed

• Native SDKs Updated:
  • Android: com.github.Bearound:bearound-android-sdk:v2.2.2
  • iOS: BearoundSDK ~> 2.2.2

Fixed

• iOS Podspec Version Sync: Fixed podspec version that was out of sync with the package version.

Technical Details

• Native SDK v2.2.2 Changes:
  • Removed 1-second foreground scan interval option (minimum is now 5 seconds)
  • 5-second foreground scan interval now uses continuous scanning (no pause between scans)
  • Beacons are no longer cleared from internal state after being sent to the API

Changed

• iOS Permission Handling: Permissions are now requested via native Swift code using CLLocationManager.requestAlwaysAuthorization(), matching the behavior of the iOS native SDK and React Native SDK. This eliminates the blue GPS indicator that appeared when using the location Flutter package.

Fixed

• iOS: Blue GPS indicator no longer appears: Removed dependency on the location Flutter package for iOS. Permissions are now handled natively via MethodChannel, which prevents the continuous location updates that caused the blue GPS indicator to appear.

• iOS: Permission flow aligned with native SDKs: The permission request now goes directly to "Always" authorization (like React Native and iOS native SDKs) instead of first asking for "When In Use" and then upgrading.

Removed

• Removed location package dependency: The location package is no longer used. iOS permissions are handled via native Swift code, and Android permissions continue to use permission_handler.

Technical Details

• iOS Plugin (BearoundFlutterSdkPlugin.swift):

  • Added CLLocationManagerDelegate conformance
  • Added requestPermissions method that calls requestAlwaysAuthorization() directly
  • Added checkPermissions method to verify current authorization status
  • Both methods mirror the React Native SDK's RNBearoundBridge.swift implementation

• Permission Service (permission_service.dart):

  • iOS: Now uses MethodChannel to call native Swift permission methods
  • Android: Continues using permission_handler package
  • Added checkPermissions() method to the public API

⚠️ Breaking Changes

• Removed syncStream: The countdown updates (secondsUntilNextSync, isRanging) have been removed to save battery. The native iOS SDK removed this callback, and we're aligning all SDKs.
• Removed SyncStatus model: No longer needed without syncStream.

Fixed

• iOS/Android: Auto-restored scan not respecting configuration: Fixed critical bug where if the SDK auto-restored scanning from a previous session, it would continue with the old configuration (continuous scan) instead of using the new configuration. The plugin now detects if SDK was already scanning during configure(), stops it, applies the new configuration, and restarts with correct periodic scan settings.
• Android: No beacons appearing: Fixed critical bug where the listener was not being properly set in configure() and startScanning() methods. The Android plugin now correctly redefines the listener to ensure beacon events are received even when the listener was previously overwritten by the Application class.
• Android: Example app beacon detection blocked: Removed android:usesPermissionFlags="neverForLocation" from BLUETOOTH_SCAN permission in example app manifest. This flag was blocking iBeacon detection since beacons require location services.
• iOS: App state synchronization: Added workaround to force the SDK to recognize the correct foreground state by posting willEnterForegroundNotification when starting scan in active state. This addresses a potential race condition where the BeaconManager might have been initialized with incorrect foreground state.
• Flutter Example: Duplicate scan initialization: Removed duplicate configure() call in _startScan() method that was causing the scan to restart twice in rapid succession.

Changed

• Native SDKs Updated:
  • Android: com.github.Bearound:bearound-android-sdk:v2.2.1
  • iOS: BearoundSDK ~> 2.2.1

Technical Details

• Both iOS and Android Plugins:

  • Added logic in configure() to detect if SDK was already scanning (auto-restored)
  • If SDK was scanning, stops it, applies new config, and restarts with correct settings
  • This ensures periodic scan configuration is always applied correctly
  • Cleaned up diagnostic logs - keeping only essential error logging

• Android Plugin:

  • Re-assigns listener in both configure() and startScanning() methods
  • This ensures Flutter plugin always receives callbacks even if Application class overwrites listener
  • Maintains error logging for debugging

• iOS Plugin:

  • Posts willEnterForegroundNotification when starting scan in active state
  • This forces SDK to correctly recognize foreground state and apply periodic scan configuration
  • Syncs isActiveScan with SDK state to handle auto-restored scanning

⚠️ Breaking Changes

Simplified Configuration: Bluetooth metadata and periodic scanning are now automatic. The enableBluetoothScanning and enablePeriodicScanning parameters have been removed from the configure() method.

Added

• NEW Streams for Better Control:

  • syncLifecycleStream: Notifies when sync operations start and complete
    • onSyncStarted(beaconCount): Called before starting a sync
    • onSyncCompleted(beaconCount, success, error): Called after sync completes
  • backgroundDetectionStream: Notifies when beacons are detected in background
    • onBeaconDetectedInBackground(beaconCount): Called when beacons detected while app is in background

• New Models:

  • SyncLifecycleEvent: Represents sync lifecycle events with type, beaconCount, success, and error fields
  • BackgroundDetectionEvent: Represents background detection events with beaconCount

Changed

• Automatic Features:

  • Bluetooth metadata collection is now always enabled (no need to configure)
  • Periodic scanning is automatic:
    • Foreground: Enabled (saves battery)
    • Background: Continuous (maximum detection)

• Native SDKs Updated:

  • Android: com.github.Bearound:bearound-android-sdk:v2.2.1
  • iOS: BearoundSDK ~> 2.2.1

• Platform Improvements:

  • Android: Renamed BeAroundSDKDelegate to BeAroundSDKListener (Android naming convention)
  • Android: Changed callback prefix from did* to on* (e.g., didUpdateBeacons → onBeaconsUpdated)
  • iOS: Added new callbacks while maintaining did* prefix (iOS convention)

Removed

• enableBluetoothScanning parameter from configure() method (now automatic)
• enablePeriodicScanning parameter from configure() method (now automatic)
• setBluetoothScanning() method (no longer needed)

Migration

Before (v2.1.0):

await BearoundFlutterSdk.configure(
  businessToken: 'your-token',
  enableBluetoothScanning: true,
  enablePeriodicScanning: true,
);

After (v2.2.0):

// Simpler configuration
await BearoundFlutterSdk.configure(
  businessToken: 'your-token',
  // Bluetooth metadata and periodic scanning are automatic
);

// NEW: Listen to sync lifecycle
BearoundFlutterSdk.syncLifecycleStream.listen((event) {
  if (event.isStarted) {
    print('📤 Sync started: ${event.beaconCount} beacons');
  } else if (event.isCompleted) {
    if (event.success == true) {
      print('✅ Sync success: ${event.beaconCount} beacons sent');
    } else {
      print('❌ Sync failed: ${event.error}');
    }
  }
});

// NEW: Listen to background detections
BearoundFlutterSdk.backgroundDetectionStream.listen((event) {
  print('🌙 Background: ${event.beaconCount} beacons detected');
});

Technical Details

• Improved code deduplication in native Android SDK
• Better async handling for device info collection
• iOS SDK updated with new callback structure
• All callbacks now have debug logging support

⚠️ Breaking Changes

Configurable Scan Intervals: SDK now supports separate foreground and background scan intervals with configurable retry queue.

Added

• Configurable Scan Intervals: New enums for fine-grained control over scan behavior

  • ForegroundScanInterval: Configure foreground scan intervals from 5 to 60 seconds (in 5-second increments)
  • BackgroundScanInterval: Configure background scan intervals (15s, 30s, 60s, 90s, or 120s)
  • Default: 15 seconds for foreground, 30 seconds for background

• Configurable Retry Queue: New MaxQueuedPayloads enum to control retry queue size

  • .small (50 failed batches)
  • .medium (100 failed batches) - default
  • .large (200 failed batches)
  • .xlarge (500 failed batches)
  • Replaces fixed limit with configurable options
  • Each batch can contain multiple beacons from a single sync

Changed

• Configuration API: configure() method now accepts enum parameters instead of Duration

  • foregroundScanInterval: ForegroundScanInterval = ForegroundScanInterval.seconds15
  • backgroundScanInterval: BackgroundScanInterval = BackgroundScanInterval.seconds30
  • maxQueuedPayloads: MaxQueuedPayloads = MaxQueuedPayloads.medium
  • Old syncInterval parameter removed in favor of separate foreground/background intervals

• Dynamic Interval Switching: SDK now automatically switches between foreground and background intervals based on app state (iOS only for now)

• Improved Resilience: Increased default retry queue from fixed size to 100 failed batches

• Native SDKs: Updated to version 2.1.0

  • iOS: BearoundSDK ~> 2.1.0
  • Android: com.github.Bearound:bearound-android-sdk:v2.1.0

Migration

Before (v2.0.1):

await BearoundFlutterSdk.configure(
  businessToken: 'your-business-token-here',
  syncInterval: const Duration(seconds: 30),
);

After (v2.1.0):

// Using defaults (recommended)
await BearoundFlutterSdk.configure(
  businessToken: 'your-business-token-here',
);

// Custom configuration
await BearoundFlutterSdk.configure(
  businessToken: 'your-business-token-here',
  foregroundScanInterval: ForegroundScanInterval.seconds30,
  backgroundScanInterval: BackgroundScanInterval.seconds90,
  maxQueuedPayloads: MaxQueuedPayloads.large,
);

Platform Support

• ✅ iOS: Fully supports all new features with native SDK 2.1.0
• ✅ Android: Fully supports all new features with native SDK 2.1.0

Technical Details

• Scan duration formula unchanged: scanDuration = max(5, min(syncInterval / 3, 10))
• Backoff retry logic unchanged: exponential backoff with max 60s delay
• All existing scanning and sync behaviors preserved
• Type-safe enum-based configuration for better developer experience

⚠️ Breaking Changes

Authentication Update: SDK now requires business token instead of appId for authentication.

Changed

• API: configure() now requires businessToken parameter (replaces appId)
• Auto-detection: appId automatically extracted from package/bundle identifier
• Authorization: Business token sent in Authorization header for all API requests
• Native SDKs: Updated to version 2.0.1
  • Android: com.github.Bearound:bearound-android-sdk:v2.0.1
  • iOS: BearoundSDK ~> 2.0.1

Migration

Before (v2.0.0):

await BearoundFlutterSdk.configure(
  appId: 'com.example.app',
  syncInterval: const Duration(seconds: 30),
);

After (v2.0.1):

await BearoundFlutterSdk.configure(
  businessToken: 'your-business-token-here',
  syncInterval: const Duration(seconds: 30),
);
// Note: appId is now automatically extracted from package/bundle identifier

Added

• New Flutter API aligned to the native SDK 2.0.0 (configure, startScanning, stopScanning).
• Streamed updates for beacons, sync status, scanning state, and errors.
• New beacon/metadata models matching native SDK fields.
• User properties support (setUserProperties, clearUserProperties).

Changed

• Updated Android native dependency to com.github.Bearound:bearound-android-sdk:2.0.0.
• Updated iOS native dependency to BearoundSDK ~> 2.0.0.
• Android minimum SDK is now 23; iOS minimum is 13.0.
• Plugin channel payloads updated to match v2 delegate events.

Removed

• Legacy 1.x API surface (client token initialization, backup size, legacy sync success/error events, region events).

Added

• Configurable Scan Interval: Set beacon scan frequency from 5 to 60 seconds via setSyncInterval()
  • Balance between battery consumption and detection speed
  • Available intervals: TIME_5, TIME_10, TIME_15, TIME_20 (default), TIME_25, TIME_30, TIME_35, TIME_40, TIME_45, TIME_50, TIME_55, TIME_60
• Configurable Backup Size: Set failed beacon backup list size from 5 to 50 beacons via setBackupSize()
  • Control how many failed beacon detections are stored for retry
  • Available sizes: SIZE_5 through SIZE_50, default SIZE_40
• Configuration Methods: Added getSyncInterval() and getBackupSize() to retrieve current settings
• Settings UI: Added comprehensive settings screen in example app with gear icon in app bar
  • Visual configuration of scan intervals and backup sizes
  • Usage recommendations for different scenarios (real-time tracking, battery optimization, offline-first)
  • Real-time feedback and configuration updates
• Configuration Enums: New SyncInterval and BackupSize enums for type-safe configuration
• Smart Beacon Filtering: Automatically filters invalid beacons (RSSI = 0) to improve data quality
• Improved iOS Integration: Updated to use singleton pattern with Bearound.configure() method

Changed

• Updated iOS BearoundSDK dependency to version 1.3.1 with:
  • 🎨 Modular Architecture: Complete project reorganization for better maintainability
  • 📊 Enhanced Telemetry: Comprehensive device information collection
  • 🔋 Battery Optimized: Smart location accuracy settings
  • ✅ RSSI Validation: Improved beacon filtering (-120 to -1 dBm)
  • 🧪 Full Test Coverage: Comprehensive unit test suite
• Updated Android BearoundSDK dependency to version 1.3.1 with:
  • 🔍 Smart Beacon Filtering: Automatically filters invalid beacons (RSSI = 0)
  • ⚙️ Configurable Scan Intervals: Customizable beacon scan frequency
  • 📦 Configurable Backup List Size: Control failed beacon storage
  • 🎉 Enhanced Event Listener System: BeaconListener, SyncListener, RegionListener
• iOS SDK Initialization: Changed from Bearound(clientToken:isDebugEnable:) to Bearound.configure(clientToken:isDebugEnable:) (singleton pattern)
• iOS Plugin Architecture: Implemented Task-based async initialization for reliable permission handling
• Enhanced example app with interactive configuration UI featuring:
  • Current settings display with visual indicators
  • Quick selection chips for all interval and backup size options
  • Usage recommendations for different scenarios
  • Real-time configuration updates

Performance Improvements

• iOS: Async/await pattern ensures proper initialization sequence and reliable beacon detection
• Memory Management: Removed all debug print statements from iOS plugin to reduce overhead
• Event Handling: Optimized listener callbacks to dispatch events efficiently on main thread

Technical Details

• iOS:
  • Supports sync intervals from 5-60 seconds and backup sizes from 5-50 beacons
  • Both configurable at runtime (can be changed dynamically)
  • Configuration persisted across app restarts
  • SDK now uses singleton pattern for better lifecycle management
• Android:
  • Supports sync intervals from 5-60 seconds and backup sizes from 5-50 beacons
  • Sync interval can be changed dynamically at runtime
  • Backup size must be set before initialize() on Android
  • Configuration persisted across app restarts

Configuration Recommendations

API Changes

• Added BearoundFlutterSdk.setSyncInterval(SyncInterval) - Configure scan frequency
• Added BearoundFlutterSdk.setBackupSize(BackupSize) - Configure backup list size
• Added BearoundFlutterSdk.getSyncInterval() - Get current sync interval
• Added BearoundFlutterSdk.getBackupSize() - Get current backup size

Fixed

• Critical iOS Initialization Bug: Fixed beacon detection issue where startServices() was called before permissions were granted
  • SDK now properly waits for requestPermissions() to complete using async/await pattern
  • Matches the working pattern from native iOS SDK example
  • Ensures CoreLocation and CoreBluetooth are properly authorized before starting services
  • Resolves issue where beacons were not being detected on iOS despite successful initialization
• iOS Event Listeners: Improved listener registration to ensure events are properly captured from native SDK

Breaking Changes

• None - This release is backward compatible with 1.2.x versions

Changed

• Updated iOS BearoundSDK dependency to version 1.2.0
• Updated Android BearoundSDK dependency to version 1.2.0

Changed

• iOS Native SDK Update: Updated BearoundSDK iOS dependency from 1.1.0 to 1.1.1
• iOS Permission Handling: Added automatic requestPermissions() call during SDK initialization
  • Permissions are now requested automatically when initializing the SDK on iOS
  • Improves user experience by ensuring proper permissions setup

Infrastructure

• Updated Flutter SDK version to 1.1.2
• Updated podspec version to align with SDK versioning

Fixed

• State Synchronization Bug: Fixed critical issue where app state became desynchronized with native SDK after closing and reopening the app
  • Android plugin now checks BeAround.isInitialized() before re-initializing, preventing initialization errors
  • When SDK is already initialized, plugin reuses existing instance and re-registers listeners
  • Added isInitialized() method to query SDK state from Flutter
  • Example app now implements WidgetsBindingObserver to sync UI state when app resumes
  • Background notification now stays consistent with UI state
• Native Listeners Reconnection: Fixed issue where beacon events stopped being received after reopening the app
  • Native listeners are now properly re-registered when app detects SDK running in background
  • _syncStateWithNative() calls startScan() again to restore native event flow
  • Both Flutter streams and native listeners are reconnected seamlessly

Added

• State Query Method: New BearoundFlutterSdk.isInitialized() method to check if SDK is currently running
  • Useful for restoring correct UI state when app is reopened
  • Example usage in app lifecycle management
• Lifecycle Management: Example app demonstrates proper state synchronization using WidgetsBindingObserver

Changed

• Android Initialization Logic: initialize method now handles already-initialized state gracefully
  • Logs warning when reusing existing instance
  • Re-registers event listeners to ensure Flutter receives events
  • No error thrown on re-initialization attempts

Added

• Event Listeners System: Comprehensive event listener architecture aligned with native iOS and Android SDKs
  • BeaconListener - Real-time beacon detection callbacks with event types (enter/exit/failed)
  • SyncListener - API synchronization status monitoring (success/error events)
  • RegionListener - Beacon region entry/exit notifications
• EventChannel Streams: Three dedicated EventChannels for real-time event streaming
  • beaconsStream - Stream of detected beacons with event types
  • syncStream - Stream of API sync success/error events
  • regionStream - Stream of region enter/exit events
• Enhanced Beacon Model: Added lastSeen field (timestamp in milliseconds)
• Detailed Debug Logging: Added comprehensive logging in Android plugin for easier troubleshooting
• Redesigned Example App: New tabbed interface with three sections:
  • Beacons tab: Real-time beacon list with region status
  • Sync tab: API synchronization status display
  • Logs tab: Console with timestamped event logs (max 50 entries)

Changed

• Region Events Structure: BeaconRegionEnterEvent and BeaconRegionExitEvent now use regionName instead of beacon list
• Sync Events Enhancement:
  • SyncSuccessEvent now includes message field with server response
  • SyncErrorEvent now includes optional errorCode field
• Android Permission Handling: More flexible permission logic - requires location OR bluetooth (not both)
• Android SDK Manifest: Declared all required permissions in SDK manifest for proper merge
• iOS Beacon Parsing: Implemented Mirror-based reflection to safely access internal Beacon properties
• Type Casting: Improved type safety with explicit Map<String, dynamic>.from() conversions

Fixed

• iOS UUID Conversion: Fixed UUID type casting by converting Foundation.UUID to String using .uuidString
• iOS Distance Conversion: Fixed Optional<Float> to Double conversion for distanceMeters
• iOS Major/Minor Types: Handle both String and Int types from native SDK
• Android Bluetooth Permissions: Added missing BLUETOOTH and BLUETOOTH_ADMIN permissions to SDK manifest
• Android Beacon Scanning: Removed neverForLocation flag that was blocking beacon detection
• Android Permission Inspector Errors: Resolved all permission-related warnings in beacon scanning
• Type Cast Errors: Fixed Map<Object?, Object?> to Map<String, dynamic> casting issues in event streams

Infrastructure

• Git Cleanup: Removed .idea/ directories from repository and added to .gitignore
• Android Gitignore: Updated to ignore entire .idea/ directory instead of individual files
• Root Gitignore: Added comprehensive IDE exclusions (IntelliJ IDEA, VSCode)

Documentation

• API Documentation: Added comprehensive documentation for all new stream getters
• Usage Examples: Included examples for all three listener types in code comments
• BeaconData Model: Documented all fields including new lastSeen timestamp

Changed

• Migrated iOS dependency from xcframework to official CocoaPods repository
• Updated BeAround dependency to use official CocoaPods spec
• Migrated Android dependency from local .aar files to official JitPack Maven repository
• Updated Android SDK dependency to use com.github.Bearound:bearound-android-sdk:v1.0.3
• Improved iOS and Android integration with standardized dependency management

Fixed

• Resolved iOS build issues related to framework distribution
• Resolved Android build issues related to local .aar dependencies
• Enhanced compatibility with standard CocoaPods and Maven workflows

Added

• Comprehensive pre-commit hooks configuration
• Automated code quality enforcement (format, analyze, test)
• Security checks with detect-secrets
• Conventional commit message validation
• Setup script for easy pre-commit installation

Changed

• Updated Flutter version to 3.35.2 in CI/CD pipelines
• Enhanced documentation with pre-commit hooks guide
• Improved developer workflow with quality automation

Fixed

• Removed references to unimplemented stream functionality from README
• Corrected API documentation to match actual implementation

Added

• Initial release of Bearound Flutter SDK
• Beacon scanning functionality for Android and iOS
• Permission management for location and Bluetooth
• Comprehensive unit test suite
• CI/CD pipeline with GitHub Actions
• Automatic release workflow

Features

• BearoundFlutterSdk: Main facade for SDK operations
• BeaconScanner: Core beacon scanning functionality
• PermissionService: Cross-platform permission handling
• Beacon Model: Data model for beacon information
• Method Channel: Native platform communication

Documentation

• API documentation with dart doc
• Usage examples
• Setup instructions

Testing

• Unit tests with 25 test cases
• CI pipeline validation
• Code coverage reporting