Skip to main content

Installation

react-native-nitro-modules is required as this library relies on Nitro Modules.

yarn add react-native-google-maps-plus react-native-nitro-modules

iOS Setup (Bare RN only)​

The native iOS dependencies (GoogleMaps, GoogleMapsUtils) are integrated via Swift Package Manager automatically during pod install.

Install the pods as frameworks​

Swift packages require the pods to be installed as frameworks, so add use_frameworks! to your Podfile. React Native recommends dynamic linking, static linking also works if another dependency requires it:

platform :ios, 16.0
prepare_react_native_project!

use_frameworks! :linkage => :dynamic

React Native does not call use_frameworks! on its own, so setting the USE_FRAMEWORKS environment variable alone is not enough. The example app reads that variable to make the linkage switchable:

ENV['USE_FRAMEWORKS'] ||= 'dynamic'
use_frameworks! :linkage => ENV['USE_FRAMEWORKS'].to_sym

Configure the API key​

Add your API key to Info.plist and hand it to the SDK in your AppDelegate, before the first map or Street View is created. Reading it from Info.plist keeps the key out of your sources:

<key>MAPS_API_KEY</key>
<string>YOUR_IOS_MAPS_API_KEY</string>
import GoogleMaps

if let apiKey = Bundle.main.object(forInfoDictionaryKey: "MAPS_API_KEY") as? String {
  GMSServices.provideAPIKey(apiKey)
}

The Google Maps SDK raises an unrecoverable Objective-C exception when a map is created without a valid key. That happens inside the SDK and is not reported through onMapError, unlike on Android.

Android Setup (Bare RN only)​

android-maps-utils 7.x is built with Kotlin 2.4, so the app has to build with Kotlin 2.3.0 or newer. React Native 0.88 defaults to 2.2.0 and fails the build with an "incompatible version of Kotlin" error.

Set the version in android/build.gradle:

buildscript {
  ext {
    kotlinVersion = "2.3.0"
  }
  dependencies {
    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
  }
}

Setting ext.kotlinVersion alone is not enough. React Native resolves the Kotlin Gradle plugin through its own version catalog, so the classpath entry has to be pinned explicitly.

Expo Setup​

Add your keys via the config plugin:

{
  "expo": {
    "plugins": [
      [
        "react-native-google-maps-plus",
        {
          "googleMapsAndroidApiKey": "YOUR_ANDROID_MAPS_API_KEY",
          "googleMapsIosApiKey": "YOUR_IOS_MAPS_API_KEY"
        }
      ]
    ]
  }
}

On iOS the plugin writes the key to Info.plist and adds the GMSServices.provideAPIKey call to the AppDelegate. It also sets ios.useFrameworks to dynamic in Podfile.properties.json. Set ios.useFrameworks yourself with expo-build-properties if you need static, the plugin keeps that value.

The Kotlin requirement from the Android setup applies here as well. Expo generates the Android project, so set the version through expo-build-properties:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "kotlinVersion": "2.3.0"
          }
        }
      ]
    ]
  }
}