in_app_location_kit 0.1.1

Turn on GPS in-app, request location permission, fetch coordinates and address — customizable UI, storage, maps, and Riverpod helpers.

in_app_location_kit

Turn on device GPS inside the app, request runtime permission, fetch coordinates, and optionally reverse-geocode — with fully customizable UI, storage, maps, and Riverpod helpers.

---

Important: Google Maps is optional (but required for the map screen)

Feature	Location permission	Google Maps API key
InAppLocationButton, permission screen, GPS loading, bootstrap	Yes	No
InAppLocationMapScreen (map pin picker)	Yes	Yes

If you open the map picker without a Maps API key, Android/iOS can crash with:

PlatformException: API key not found.
Check that <meta-data android:name="com.google.android.geo.API_KEY" .../>

That is not a bug in this package — Google Maps must be configured in your app. See Google Maps setup below.

---

Features

• In-app GPS enable via location.requestService() (Android system dialog)
• Permission via geolocator and/or permission_handler (PermissionBackend)
• InAppLocationKit service with step stream for custom UI
• Widgets: button, permission screen, loading screen, guard, flow builder
• SharedPreferencesLocationStorage (optional Khaugalli legacy keys)
• LocationBootstrap for splash-style routing
• InAppLocationMapScreen (Google Map pin) — needs Maps API key
• FakeInAppLocationKit for tests
• Riverpod providers (package:in_app_location_kit/riverpod.dart)

---

Install

dependencies:
  in_app_location_kit: ^0.1.1

flutter pub get

---

Run the example app

Clone the repo, then choose one of these:

Option 1 — GPS / permission only (no Google Maps key)

Works for: Use current location, Permission screen, Loading screen, Run bootstrap.

git clone https://github.com/chaitanya-mhetre/in_app_location_kit.git
cd in_app_location_kit/example
flutter pub get
flutter run

Do not tap Map picker without completing Option 2.

Option 2 — Full demo including Map picker

You need a Google Cloud API key with Maps SDK for Android (and iOS if you test on iPhone).

Step 1 — Create local.properties

cd in_app_location_kit/example
cp android/local.properties.example android/local.properties

Step 2 — Edit android/local.properties

Replace the placeholder with your real key:

MAPS_API_KEY=YOUR_KEY_HERE

Step 3 — Run with the same key in the command

Replace YOUR_KEY with the exact same value as in local.properties:

flutter run --dart-define=MAPS_API_KEY=YOUR_KEY

Example:

flutter run --dart-define=MAPS_API_KEY=YOUR_KEY_HERE

Step 4 — Pick your device when prompted, then tap Map picker on the home screen.

More detail: example/README.md and doc/GOOGLE_MAPS_SETUP.md.

---

Host app setup (production)

Android — location (required for all features)

android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS — location (required for all features)

ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location for delivery and nearby results.</string>

Google Maps setup (required only for map picker)

Android — inside <application> in AndroidManifest.xml:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_GOOGLE_MAPS_API_KEY" />

iOS — in Info.plist:

<key>GMSApiKey</key>
<string>YOUR_GOOGLE_MAPS_API_KEY</string>

Dart — pass the key so the package shows a friendly screen instead of crashing:

import 'package:in_app_location_kit/maps.dart';

InAppLocationMapScreen(
  googleMapsApiKey: yourMapsKey, // empty → placeholder UI, no crash
  onConfirm: (fix) => save(fix),
);

---

Quick start (no map)

import 'package:in_app_location_kit/in_app_location_kit.dart';

InAppLocationButton(
  onLocation: (fix) => print(fix.formattedAddress),
  storage: SharedPreferencesLocationStorage(),
);

Full permission screen

InAppLocationPermissionScreen(
  onSuccess: (fix) => context.go('/home'),
  onManualEntry: () => context.go('/address-search'),
  storage: SharedPreferencesLocationStorage(),
  strings: const InAppLocationStrings(permissionTitle: 'Find food near you'),
  theme: const InAppLocationTheme(primaryColor: Colors.orange),
);

Core service only

final kit = InAppLocationKit(
  config: const InAppLocationConfig(
    gpsStabilizeDelay: Duration(seconds: 2),
    permissionBackend: PermissionBackend.auto,
    reverseGeocode: true,
  ),
);

final result = await kit.fetchCurrentLocation();
if (result is LocationFlowSuccess) {
  print(result.fix.latitude);
}

Bootstrap (splash)

final bootstrap = LocationBootstrap(
  storage: SharedPreferencesLocationStorage(),
);
final route = await bootstrap.resolve();
switch (route.action) {
  case LocationBootstrapAction.fetchGps:
    break;
  case LocationBootstrapAction.manualAddressRequired:
    break;
  case LocationBootstrapAction.useCachedAddress:
    break;
}

Riverpod

import 'package:in_app_location_kit/riverpod.dart';

ref.watch(fetchAndSaveLocationProvider);

---

Troubleshooting

App crashes on “Map picker” with API key not found

Cause: com.google.android.geo.API_KEY is missing or empty in AndroidManifest.xml.

Fix:

1. Add the <meta-data> block under <application> (see above).
2. For the example app, set MAPS_API_KEY in example/android/local.properties and run:

   flutter run --dart-define=MAPS_API_KEY=your_key
   

3. Rebuild after changing the key (flutter clean if the old build is cached).

Map picker button shows “needs API key” / dialog

Expected when you run flutter run without --dart-define=MAPS_API_KEY=.... Follow Option 2.

Location works but address is empty

Enable internet for reverse geocoding, or set reverseGeocode: false in InAppLocationConfig.

Permission denied forever

User must enable location in system App settings. Use Geolocator.openAppSettings() or the package’s settings dialog.

---

Customization

Type	Purpose
InAppLocationConfig	timeouts, accuracy, geocode, permission backend
InAppLocationStrings	all user-visible copy
InAppLocationTheme	colors, buttons, illustration, loading
SettingsDialogBuilder	replace GPS / settings dialogs
InAppLocationFlow	build UI per LocationFlowStep
addressFormatter	custom address line from Placemark

---

Contributing

Issues and PRs: github.com/chaitanya-mhetre/in_app_location_kit

License

MIT — see LICENSE.