Skip to content

ios_deployment_guide.md

Latest commit

 

History

History
214 lines (168 loc) · 6.84 KB

ios_deployment_guide.md

File metadata and controls

214 lines (168 loc) · 6.84 KB

iOS Deployment Guide for LiveSpotAlert

Prerequisites

  • iOS 16.1+ (Required for Live Activities)
  • Xcode 14+
  • Apple Developer Account (Required for background location and Live Activities)
  • Physical iOS Device (Live Activities don't work on simulator)

1. Xcode Project Configuration

A. Open Project in Xcode

open ios/Runner.xcworkspace

B. Configure Target Settings

General Tab:

  • Bundle Identifier: com.livespotalert.app (or your preferred identifier)
  • Version: 1.0.0
  • Build: 1
  • Deployment Target: 16.1
  • Supported Device Families: iPhone

Signing & Capabilities Tab:

  1. Enable Automatic Signing (or configure manual signing)
  2. Add Required Capabilities:
    • ✅ Background Modes
      • Location updates
      • Background processing
      • Background fetch
    • ✅ Push Notifications (Required for Live Activities)
    • ✅ Live Activities (iOS 16.1+)
    • ✅ WidgetKit Extension (For Live Activities UI)

C. Add Entitlements File

The entitlements file has been created at ios/Runner/LiveSpotAlert.entitlements.

Link it in Xcode:

  1. Select Runner target
  2. Build Settings → Code Signing Entitlements
  3. Set path to: Runner/LiveSpotAlert.entitlements

2. Info.plist Configuration ✅

The following permissions and configurations have been added to Info.plist:

Location Permissions:

  • NSLocationAlwaysAndWhenInUseUsageDescription
  • NSLocationWhenInUseUsageDescription
  • NSLocationAlwaysUsageDescription
  • NSLocationTemporaryUsageDescriptionDictionary

Background Modes:

  • UIBackgroundModes: location, background-processing, fetch

Live Activities:

  • NSSupportsLiveActivities: true
  • MinimumOSVersion: 16.1

3. Apple Developer Console Setup

A. App ID Configuration

  1. Go to Certificates, Identifiers & Profiles
  2. Select your App ID
  3. Enable Required Services:
    • ✅ Push Notifications
    • ✅ Background Modes
    • ✅ Live Activities

B. Push Notification Certificate

  1. Create Apple Push Notification service SSL (Sandbox & Production)
  2. Download and install the certificate
  3. Update aps-environment in entitlements for production: production

C. Provisioning Profile

  1. Create provisioning profile with all required capabilities
  2. Download and install in Xcode
  3. Select the profile in project settings

4. Testing Requirements

Location Testing:

  • Always Location Permission: Required for background geofencing
  • Precise Location: Needed for accurate geofence triggering
  • Background App Refresh: Must be enabled in device settings

Live Activities Testing:

  • Physical Device: Live Activities don't work on simulator
  • iOS 16.1+: Minimum requirement
  • Focus Modes: Test with different Focus mode configurations

5. Background Location Best Practices

Battery Optimization:

// flutter_background_geolocation config (already implemented)
desiredAccuracy: high        // Only when needed
distanceFilter: 10.0        // Reduce location updates
stopTimeout: 1              // Quick stop detection

User Privacy:

  • Clear explanations in permission dialogs
  • Minimal data collection - only location for geofencing
  • User control - easy to disable/enable geofences

6. Live Activities Considerations

Content Limitations:

  • 4KB maximum data payload
  • Static images only (no animations)
  • System-controlled appearance timing
  • Limited interaction (tap to open app)

Design Guidelines:

  • Clear, concise information display
  • High contrast for readability
  • Consistent with app branding
  • Accessible text and imagery

7. Production Deployment Checklist

Before App Store Submission:

  • Test on multiple devices (different iOS versions)
  • Verify background location works correctly
  • Test Live Activities trigger properly
  • Check battery usage is reasonable
  • Test permission flows are user-friendly
  • Validate geofence accuracy in real-world scenarios
  • Test edge cases (airplane mode, low battery, etc.)

App Store Review Preparation:

  • Location Usage Justification: Clear explanation of why always-location is needed
  • Demo Video: Show geofencing and Live Activities working
  • Privacy Policy: Detail location data usage and retention
  • App Description: Clearly explain location-based features

Production Configuration:

  • Change aps-environment to production in entitlements
  • Update bundle ID for production
  • Configure production push certificates
  • Test with production provisioning profile

8. Troubleshooting Common Issues

Location Permission Issues:

Error: Location permission denied
Solution: Check Info.plist descriptions are user-friendly and descriptive

Background Location Not Working:

Error: Geofences not triggering in background
Solution: Verify "Always" location permission is granted, not just "While Using App"

Live Activities Not Appearing:

Error: Live Activities don't show up
Solution: Check iOS version (16.1+), device (not simulator), and Focus mode settings

Build Errors:

Error: Code signing issues
Solution: Ensure provisioning profile includes all required capabilities

9. Performance Monitoring

Key Metrics to Track:

  • Battery usage (should be reasonable for location app)
  • Location accuracy (geofence trigger reliability)
  • Background crashes (monitor crash reports)
  • Permission grant rates (user experience indicator)

Analytics Integration:

Consider adding analytics to track:

  • Geofence trigger success rate
  • Live Activities engagement
  • User permission choices
  • Feature usage patterns

10. User Experience Guidelines

Onboarding Flow:

  1. Explain benefits before requesting permissions
  2. Request permissions in context (when creating first geofence)
  3. Provide fallbacks if permissions denied
  4. Guide users to Settings if permissions need changing

Permission Management:

  • Easy access to permission settings
  • Clear indicators of current permission status
  • Helpful instructions for changing permissions in iOS Settings
  • Graceful degradation when permissions are limited

Next Steps

  1. Configure Xcode project with the settings above
  2. Test on physical device with real geofences
  3. Validate Live Activities work as expected
  4. Prepare for App Store submission with required documentation
  5. Monitor performance and user feedback after release

For questions or issues, refer to: