Config Plugin

Overview

expo-gaode-map provides an Expo Config Plugin that automatically configures native projects when running npx expo prebuild, eliminating the need for manual native code modifications.

Quick Start

1. Installation

npm install expo-gaode-map
# or
yarn add expo-gaode-map

2. Configure app.json

Add plugin configuration to your app.json file in the project root:

{
  "expo": {
    "name": "Your App",
    "plugins": [
      [
        "expo-gaode-map",
        {
          "iosKey": "Your iOS Gaode Map API Key",
          "androidKey": "Your Android Gaode Map API Key",
          "enableLocation": true,
          "enableBackgroundLocation": false,
          "locationDescription": "We need to access your location to provide map services"
        }
      ]
    ]
  }
}

3. Run Prebuild

npx expo prebuild

4. Run Project

# iOS
npx expo run:ios

# Android
npx expo run:android

Configuration Parameters

Parameter	Type	Required	Default	Description
iosKey	string	No	-	iOS platform Gaode Map API Key
androidKey	string	No	-	Android platform Gaode Map API Key
customMapSdkPath	string	No	-	Custom Gaode Map Android SDK path (e.g., libs/AMap_3DMap_V9.10.0_20240904.aar), for Google Play version support
enableLocation	boolean	No	true	Enable location functionality
enableBackgroundLocation	boolean	No	false	Enable background location (Android & iOS)
locationDescription	string	No	"We need to access your location to provide map services"	iOS location permission description

Google Play Version Support

If your app needs to be published on Google Play, you must use the Google Play version of the Gaode Map SDK (which complies with the 16kb Page Size requirement and removes some compliance-problematic code).

1. Download SDK

Go to the Gaode Open Platform to download the SDK containing the Google Play version (usually an .aar file).

2. Place SDK

Place the downloaded .aar file in your Expo project directory, for example in the libs/ directory.

3. Configure Plugin

Configure the customMapSdkPath parameter in app.json or app.config.js to point to your SDK file path:

{
  "expo": {
    "plugins": [
      [
        "expo-gaode-map",
        {
          "androidKey": "Your Key",
          "customMapSdkPath": "libs/AMap_3DMap_V9.10.0_20240904.aar"
        }
      ]
    ]
  }
}

4. Apply Configuration

After configuration, you need to regenerate the native project for changes to take effect:

npx expo prebuild

5. Automatic Handling

After configuration, the plugin will automatically handle the following:

• Dependency Switching: Automatically switches to use the local AAR dependency instead of fetching the SDK from the Maven repository.
• Conflict Resolution: Automatically excludes Maven dependency modules that might cause conflicts.
• Path Correction: Automatically handles Gradle build path issues.

Important Notes

• Ensure the libs directory is in the project root.
• It is recommended that filenames do not contain special characters.
• When using the Google Play version, some features may be restricted (such as offline maps), please refer to the official Gaode documentation.

Auto-Configured Content

The Config Plugin automatically configures the following:

iOS Platform

Info.plist

<!-- API Key -->
<key>AMapApiKey</key>
<string>Your API Key</string>

<!-- When In Use Location Permission (Always added) -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need to access your location to provide map services</string>

<!-- Following are added only when enableBackgroundLocation=true -->
<key>NSLocationAlwaysUsageDescription</key>
<string>We need to access your location to provide map services</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need to access your location to provide map services</string>

<!-- Background Location Mode -->
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

AppDelegate

#import <AMapFoundationKit/AMapFoundationKit.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [AMapServices sharedServices].apiKey = @"Your API Key";
  // ...
}

Android Platform

AndroidManifest.xml

Basic Permissions (Always added):

<!-- Network Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

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

Background Location Permissions (Added only when enableBackgroundLocation=true):

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

Application Configuration:

<application>
  <!-- API Key -->
  <meta-data
    android:name="com.amap.api.v2.apikey"
    android:value="Your API Key" />
    
  <!-- Foreground Service (Added only when enableBackgroundLocation=true) -->
  <service
    android:name="expo.modules.gaodemap.services.LocationForegroundService"
    android:enabled="true"
    android:exported="false"
    android:foregroundServiceType="location" />
</application>

Background Location Configuration

Enable Background Location

If your app needs to continuously access location in the background (e.g., navigation, activity tracking), you need to enable background location:

{
  "expo": {
    "plugins": [
      [
        "expo-gaode-map",
        {
          "iosKey": "Your API Key",
          "androidKey": "Your API Key",
          "enableBackgroundLocation": true
        }
      ]
    ]
  }
}

Impact of Background Location

When enableBackgroundLocation: true:

Android:

• ✅ Adds background location permission (ACCESS_BACKGROUND_LOCATION)
• ✅ Adds foreground service permissions (FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATION)
• ✅ Automatically registers LocationForegroundService
• ⚠️ Shows persistent notification when app is in background

iOS:

• ✅ Adds always location permission (NSLocationAlwaysUsageDescription)
• ✅ Enables background location mode (UIBackgroundModes)
• ⚠️ Requires justification during App Store review

Important Notes

• ⚠️ Permission Sensitivity: Background location permissions are sensitive, users may deny
• ⚠️ App Store Review: Google Play and App Store strictly review background location usage
• ⚠️ Battery Drain: Background location increases battery consumption
• ✅ Necessity Principle: Only enable when absolutely necessary

Advanced Usage

Dynamic Configuration

Use app.config.js to configure dynamically based on environment variables:

export default {
  expo: {
    name: "Your App",
    plugins: [
      [
        "expo-gaode-map",
        {
          iosKey: process.env.GAODE_IOS_API_KEY,
          androidKey: process.env.GAODE_ANDROID_API_KEY,
          enableLocation: true
        }
      ]
    ]
  }
};

Multi-Environment Configuration

const isDev = process.env.APP_ENV === 'development';

export default {
  expo: {
    plugins: [
      [
        "expo-gaode-map",
        {
          iosKey: isDev 
            ? process.env.GAODE_IOS_API_KEY_DEV 
            : process.env.GAODE_IOS_API_KEY_PROD,
          androidKey: isDev 
            ? process.env.GAODE_ANDROID_API_KEY_DEV 
            : process.env.GAODE_ANDROID_API_KEY_PROD
        }
      ]
    ]
  }
};

EAS Build Configuration

Configure environment variables in eas.json:

{
  "build": {
    "development": {
      "env": {
        "GAODE_IOS_API_KEY": "dev-ios-key",
        "GAODE_ANDROID_API_KEY": "dev-android-key"
      }
    },
    "production": {
      "env": {
        "GAODE_IOS_API_KEY": "prod-ios-key",
        "GAODE_ANDROID_API_KEY": "prod-android-key"
      }
    }
  }
}

Troubleshooting

API Key Not Working

1. Ensure API Key is correctly configured in app.json
2. Delete ios and android directories, then run npx expo prebuild again
3. Check for extra spaces or quotes in API Key

Configuration Changes Not Taking Effect

# Clean and rebuild
rm -rf ios android
npx expo prebuild

Location Permissions Not Added

Ensure enableLocation is set to true or not set (defaults to true)

Without Config Plugin

If you prefer not to use Config Plugin, you can manually configure native projects. See Initialization.

Notes

• ⚠️ API Key Security: Don't commit API Keys directly to repository, use environment variables
• 🔄 Rebuild Required: After modifying plugin configuration, you must run npx expo prebuild again
• 📱 Version Requirements: Expo SDK >= 50
• 🏗️ Native Directories: If ios and android directories already exist, prebuild will update them

Related Resources

• Expo Config Plugins Official Documentation
• Gaode Map Open Platform
• Get API Key