docs: update README and setup documentation for iOS Google Maps configuration

Author: jkasprzyk17

README.md

@@ -181,7 +181,7 @@ export default {
 | Option                     | Platform      | Description                                                                                                                                                                                                                                       |
 | -------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `googleMapsApiKey`         | iOS + Android | Shared fallback when platform-specific keys are omitted.                                                                                                                                                                                          |
-| `iosGoogleMapsApiKey`      | iOS           | Injects `GoogleMapsIosApiKey` into `Info.plist` for `provider="google"`.                                                                                                                                                                          |
+| `iosGoogleMapsApiKey`      | iOS           | Injects `GoogleMapsIosApiKey` into `Info.plist` and sets `betterMaps.iosGoogleProvider` in `Podfile.properties.json` so the Google Maps SDK is linked.                                                                                                                                                          |
 | `androidGoogleMapsApiKey`  | Android       | Injects `com.google.android.geo.API_KEY` metadata.                                                                                                                                                                                                |
 | `locationPermission`       | iOS + Android | Foreground location message. Injects `NSLocationWhenInUseUsageDescription` plus `ACCESS_FINE_LOCATION` + `ACCESS_COARSE_LOCATION`. Pass `false` or omit to skip.                                                                                  |
 | `locationAlwaysPermission` | iOS + Android | Background location message. Injects `NSLocationAlwaysAndWhenInUseUsageDescription` plus `ACCESS_BACKGROUND_LOCATION`; also supplies foreground usage strings and permissions when `locationPermission` is omitted. Pass `false` or omit to skip. |
@@ -398,7 +398,28 @@ The example app uses the config plugin. It reads `GOOGLE_MAPS_IOS_API_KEY` and `
 
 ### Bare React Native
 
-- iOS: add a `GoogleMapsIosApiKey` string to `Info.plist`.
+On iOS, `provider="google"` needs **two** host-app settings that the config plugin normally writes together:
+
+1. **Runtime API key** — `GoogleMapsIosApiKey` in `Info.plist` (read when the map mounts).
+2. **SDK linkage** — `"betterMaps.iosGoogleProvider": "true"` in `ios/Podfile.properties.json` (read by `react-native-better-maps.podspec` during `pod install` to add the `GoogleMaps` pod).
+
+In a bare workflow the plugin does not run, so configure both manually:
+
+```xml
+<!-- Info.plist -->
+<key>GoogleMapsIosApiKey</key>
+<string>YOUR_API_KEY</string>
+```
+
+```json
+// ios/Podfile.properties.json
+{
+  "betterMaps.iosGoogleProvider": "true"
+}
+```
+
+Then run `pod install` from `ios/`.
+
 - Android: add `com.google.android.geo.API_KEY` metadata to `AndroidManifest.xml`.
 
 ### Google Map ID
@@ -538,6 +559,7 @@ See [example/.env.example](example/.env.example) for the supported environment v
 | Problem                                     | Solution                                                                                                                                                       |
 | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Map is blank when using Google Maps         | Add a Google Maps API key through the Expo config plugin, `GoogleMapsIosApiKey` in `Info.plist`, or `com.google.android.geo.API_KEY` in `AndroidManifest.xml`. |
+| iOS Google Maps key set but provider errors | iOS needs both `GoogleMapsIosApiKey` in `Info.plist` **and** `"betterMaps.iosGoogleProvider": "true"` in `Podfile.properties.json`, then `pod install`. The config plugin sets both; in bare workflow or with a stale `Podfile.properties.json`, they can drift apart. |
 | New Architecture errors                     | Confirm React Native `0.78+`, New Architecture, and `react-native-nitro-modules` are installed, then rebuild the native app.                                   |
 | Provider throws before rendering            | Check the [supported platforms](#supported-platforms) table. `openstreetmap` and `mapbox` are reserved for future support but do not render yet.               |
 | Expo Go does not load native maps           | Use a development build after `expo prebuild`; native Nitro modules are not available in Expo Go.                                                              |

docs/expo-setup.md

@@ -42,7 +42,7 @@ module.exports = {
 | Option                     | Type              | Default | Description                                                                                                                                                                                                                     |
 | -------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `googleMapsApiKey`         | `string`          | —       | Shared fallback for iOS and Android when platform-specific keys are omitted.                                                                                                                                                    |
-| `iosGoogleMapsApiKey`      | `string`          | —       | Injects `GoogleMapsIosApiKey` into `Info.plist` for `provider="google"` on iOS.                                                                                                                                                 |
+| `iosGoogleMapsApiKey`      | `string`          | —       | Injects `GoogleMapsIosApiKey` into `Info.plist` and sets `betterMaps.iosGoogleProvider` in `Podfile.properties.json` so the Google Maps SDK is linked on iOS.                                                                 |
 | `androidGoogleMapsApiKey`  | `string`          | —       | Injects `com.google.android.geo.API_KEY` meta-data on Android.                                                                                                                                                                  |
 | `locationPermission`       | `string \| false` | —       | Foreground location message. Injects iOS `NSLocationWhenInUseUsageDescription` plus Android `ACCESS_FINE_LOCATION` and `ACCESS_COARSE_LOCATION`.                                                                                |
 | `locationAlwaysPermission` | `string \| false` | —       | Background location message. Injects iOS `NSLocationAlwaysAndWhenInUseUsageDescription` plus Android `ACCESS_BACKGROUND_LOCATION`; also supplies foreground usage strings and permissions when `locationPermission` is omitted. |
@@ -86,7 +86,9 @@ expo prebuild --clean
 The plugin injects:
 
 - **Android:** `com.google.android.geo.API_KEY` meta-data (when `googleMapsApiKey` or `androidGoogleMapsApiKey` is set) and location permissions (when location options are set)
-- **iOS:** `GoogleMapsIosApiKey` (when `googleMapsApiKey` or `iosGoogleMapsApiKey` is set) and location usage description strings (when location options are set)
+- **iOS:** `GoogleMapsIosApiKey` in `Info.plist` and `betterMaps.iosGoogleProvider` in `Podfile.properties.json` (when `googleMapsApiKey` or `iosGoogleMapsApiKey` is set), plus location usage description strings (when location options are set)
+
+On iOS, the API key and pod linkage are separate artifacts. The plugin keeps them in sync during prebuild. If you later remove Google Maps keys from the plugin config, re-run `expo prebuild` so `Podfile.properties.json` is updated and run `pod install` — a stale `"betterMaps.iosGoogleProvider": "true"` can leave the SDK linked after you stop providing a key. Bare React Native apps without the plugin must set both manually; see [Bare React Native](../README.md#bare-react-native) in the README.
 
 ## Run
 
@@ -111,6 +113,7 @@ The example's `prebuild` script builds the plugin (`build:plugin`) before runnin
 | Symptom                                     | Fix                                                                                                                            |
 | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | Blank Google map                            | Ensure `googleMapsApiKey` or the platform-specific Google Maps key is set, then run `expo prebuild` again.                     |
+| iOS Google Maps key present but provider fails | iOS needs `GoogleMapsIosApiKey` in `Info.plist` **and** `"betterMaps.iosGoogleProvider": "true"` in `Podfile.properties.json`, then `pod install`. Re-run prebuild after changing plugin keys so both stay aligned. |
 | Location dot not showing                    | Set `locationPermission` or `locationAlwaysPermission` in the plugin options and re-run prebuild.                              |
 | Plugin not found                            | Confirm `react-native-better-maps` is installed and listed in `plugins`.                                                        |
 | `Cannot find module './plugin/build/index'` | Run `bun run build:plugin` in the package (or `bun run build` from the repo root) before prebuild when using a workspace link. |

example/app.config.js

@@ -5,12 +5,6 @@ function readEnv(name) {
   return value == null || value.trim() === '' ? undefined : value;
 }
 
-const googleMapsApiKey = readEnv('GOOGLE_MAPS_API_KEY');
-const iosGoogleMapsApiKey =
-  readEnv('GOOGLE_MAPS_IOS_API_KEY') ?? googleMapsApiKey;
-const androidGoogleMapsApiKey =
-  readEnv('GOOGLE_MAPS_ANDROID_API_KEY') ?? googleMapsApiKey;
-
 /** @type {import('expo/config').ExpoConfig} */
 module.exports = {
   expo: {
@@ -20,8 +14,9 @@ module.exports = {
       [
         'react-native-better-maps',
         {
-          iosGoogleMapsApiKey,
-          androidGoogleMapsApiKey,
+          googleMapsApiKey: readEnv('GOOGLE_MAPS_API_KEY'),
+          iosGoogleMapsApiKey: readEnv('GOOGLE_MAPS_IOS_API_KEY'),
+          androidGoogleMapsApiKey: readEnv('GOOGLE_MAPS_ANDROID_API_KEY'),
           locationPermission:
             'Allow $(PRODUCT_NAME) to use your location for map features.',
         },

package/ios/Camera+GMSCameraPosition.swift

@@ -1,3 +1,4 @@
+#if canImport(GoogleMaps)
 import CoreLocation
 import GoogleMaps
 
@@ -24,3 +25,4 @@ extension GMSCameraPosition {
     )
   }
 }
+#endif

package/ios/GMSMapView+VisibleRegion.swift

@@ -1,3 +1,4 @@
+#if canImport(GoogleMaps)
 import GoogleMaps
 import NitroModules
 
@@ -22,3 +23,4 @@ extension CLLocationCoordinate2D {
     Coordinate(latitude: latitude, longitude: longitude)
   }
 }
+#endif

package/ios/GoogleMapOverlayController.swift

@@ -1,3 +1,4 @@
+#if canImport(GoogleMaps)
 import GoogleMaps
 import MapKit
 import UIKit
@@ -477,3 +478,4 @@ private extension Array where Element == Coordinate {
     return path
   }
 }
+#endif

package/ios/GoogleMapProviderAdapter.swift

@@ -1,3 +1,4 @@
+#if canImport(GoogleMaps)
 import CoreLocation
 import GoogleMaps
 import MapKit
@@ -585,3 +586,4 @@ extension GoogleMapProviderAdapter: GMSMapViewDelegate {
     notifyMapReadyIfNeeded()
   }
 }
+#endif

package/ios/GoogleMapsAPIKey.swift

@@ -1,4 +1,6 @@
 import Foundation
+
+#if canImport(GoogleMaps)
 import GoogleMaps
 
 enum GoogleMapsAPIKey {
@@ -20,15 +22,19 @@ enum GoogleMapsAPIKey {
     configuredKey = key
   }
 }
+#endif
 
 enum MapProviderConfigurationError: LocalizedError {
   case missingGoogleMapsIosApiKey
+  case googleMapsSdkNotLinked
   case unsupportedIOSProvider(MapProvider)
 
   var errorDescription: String? {
     switch self {
     case .missingGoogleMapsIosApiKey:
       return "react-native-better-maps: provider=\"google\" on iOS requires GoogleMapsIosApiKey in the host app Info.plist."
+    case .googleMapsSdkNotLinked:
+      return "react-native-better-maps: provider=\"google\" on iOS requires iosGoogleMapsApiKey or googleMapsApiKey in the react-native-better-maps config plugin to link the Google Maps SDK, then run pod install."
     case let .unsupportedIOSProvider(provider):
       return "Map provider \"\(provider)\" is not supported on iOS."
     }

package/ios/HybridMapView.swift

@@ -376,11 +376,17 @@ final class HybridMapView: HybridMapViewSpec {
     case .apple:
       return AppleMapProviderAdapter()
     case .google:
+#if canImport(GoogleMaps)
       do {
         return try GoogleMapProviderAdapter(googleMapId: withStateLock { self._state.googleMapId })
       } catch {
         return UnavailableMapProviderAdapter(error: error)
       }
+#else
+      return UnavailableMapProviderAdapter(
+        error: MapProviderConfigurationError.googleMapsSdkNotLinked
+      )
+#endif
     case .openstreetmap, .mapbox:
       return UnavailableMapProviderAdapter(
         error: MapProviderConfigurationError.unsupportedIOSProvider(provider)

package/ios/MapType+GMSMapViewType.swift

@@ -1,3 +1,4 @@
+#if canImport(GoogleMaps)
 import GoogleMaps
 
 extension MapType {
@@ -14,3 +15,4 @@ extension MapType {
     }
   }
 }
+#endif