iOS SBeacon Framework Installation

Installation

iOS SBeacon Framework v1.0.8

This guide covers framework integration, dependency configuration, and required permissions.

---

Requirements

Requirement	Version
iOS	15.6+ (16.0+ recommended)
Swift	5.5+
Xcode	14.0+
Device	Physical device with BLE

---

1. Swift Package Manager

Add Package Dependency

Step 1: Open Xcode Package Manager

1. Open your project in Xcode
2. Go to File → Add Packages...
3. Enter the repository URL:

   https://github.com/scopetech/BeaconFrameworkSPM-iOS
   

4. Select version 1.0.8 (or latest)
5. Click Add Package

Step 2: Add to Target

Ensure BLEFramework is added to your app target's Frameworks, Libraries, and Embedded Content section.

Note: The package is publicly available - no authentication required.

---

2. Configure Info.plist Permissions

Add all required permission descriptions to your Info.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Bluetooth Permissions -->
    <key>NSBluetoothAlwaysUsageDescription</key>
    <string>We use Bluetooth to connect to your vehicle's SBeacon device for trip tracking and driving behavior analysis.</string>

    <key>NSBluetoothPeripheralUsageDescription</key>
    <string>We use Bluetooth to communicate with your vehicle's tracking device.</string>

    <!-- Location Permissions (if using location features) -->
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>We need location access to enhance trip tracking accuracy.</string>

    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>We need always-on location access to automatically detect trips even when the app is in the background.</string>

    <!-- ... rest of your Info.plist -->
</dict>
</plist>

---

3. Configure Background Modes

Enable background BLE communication by adding the bluetooth-central background mode:

Option A: Using Info.plist

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>location</string>  <!-- If using location features -->
</array>

Option B: Using Xcode UI

1. Select your app target
2. Go to Signing & Capabilities
3. Click + Capability and add Background Modes
4. Check the following:
   • ☑ Uses Bluetooth LE accessories
   • ☑ Location updates (if using location features)

---

Permission Explanations

Permission	Required For	Notes
NSBluetoothAlwaysUsageDescription	BLE communication with SBeacon	Required - iOS 13+
NSBluetoothPeripheralUsageDescription	BLE communication	Required - iOS 12 and earlier
NSLocationWhenInUseUsageDescription	Location-enhanced features	Optional - only if using location
NSLocationAlwaysAndWhenInUseUsageDescription	Background trip detection	Optional - only for background location

Important: Starting with iOS 13, NSBluetoothAlwaysUsageDescription is mandatory for all BLE operations. Both Bluetooth descriptions should be included for backward compatibility.

---

iOS Version-Specific Requirements

iOS 16+

• Bluetooth permissions (Always usage description)
• Background modes: bluetooth-central
• No additional Bluetooth permissions required

iOS 15.6

• Bluetooth permissions (Always usage description)
• Background modes: bluetooth-central
• Location permission only if using location features

iOS 13-14

• Bluetooth permissions (Always usage description)
• Background modes: bluetooth-central
• Users may see system prompt for Bluetooth access

iOS 12 and earlier

• Legacy Bluetooth peripheral usage description
• Background modes: bluetooth-central

---

Minimum Configuration Checklist

Before proceeding, verify you have:

• Added framework via Swift Package Manager
• Added NSBluetoothAlwaysUsageDescription to Info.plist
• Added NSBluetoothPeripheralUsageDescription to Info.plist (iOS 12 compatibility)
• Enabled bluetooth-central background mode
• Framework is set to Embed & Sign in target settings (should be automatic with SPM)
• Project builds without errors

---

Next Steps

• Initialization - Configure the framework in your app
• Beacon Scanning - Discover nearby SBeacon devices