Getting Started

Quick start guide to help you integrate expo-gaode-map into your Expo project.

Prerequisites

• Node.js >= 16
• Expo SDK >= 50
• React Native >= 0.73

Installation

bun add expo-gaode-map

Or using other package managers:

# Using yarn
yarn add expo-gaode-map

# Using npm
npm install expo-gaode-map

Get API Keys

1. Visit AMap Open Platform
2. Register and log in
3. Create an application
4. Get API Keys for Android and iOS platforms

Configuration

Using Config Plugin (Recommended)

Add to your app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-gaode-map",
        {
          "iosKey": "your-ios-api-key",
          "androidKey": "your-android-api-key",
          "enableLocation": true,
          "locationDescription": "We need to access your location to provide map services"
        }
      ]
    ]
  }
}

Then run prebuild:

npx expo prebuild

Manual Configuration

If you prefer manual configuration, see Initialization Guide.

Basic Usage

1. Initialize SDK

import { ExpoGaodeMapModule } from 'expo-gaode-map';

// Initialize before using any map features
ExpoGaodeMapModule.initSDK({
  androidKey: 'your-android-api-key',
  iosKey: 'your-ios-api-key',
});

2. Display Map

import { MapView } from 'expo-gaode-map';

export default function App() {
  return (
    <MapView
      style={{ flex: 1 }}
      initialCameraPosition={{
        target: { latitude: 39.9, longitude: 116.4 },
        zoom: 10,
      }}
    />
  );
}

3. Enable Location

<MapView
  style={{ flex: 1 }}
  initialCameraPosition={{
    target: { latitude: 39.9, longitude: 116.4 },
    zoom: 10,
  }}
  myLocationEnabled={true}
  followUserLocation={true}
/>

Complete Example

import React, { useEffect, useState } from 'react';
import { View, StyleSheet, Alert } from 'react-native';
import { MapView, ExpoGaodeMapModule } from 'expo-gaode-map';

export default function App() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    initializeMap();
  }, []);

  async function initializeMap() {
    try {
      // 1. Configure privacy compliance
      ExpoGaodeMapModule.updatePrivacyAgree(true);
      ExpoGaodeMapModule.updatePrivacyShow(true, true);

      // 2. Initialize SDK
      ExpoGaodeMapModule.initSDK({
        androidKey: 'your-android-api-key',
        iosKey: 'your-ios-api-key',
      });

      // 3. Request location permission
      const granted = await ExpoGaodeMapModule.requestLocationPermission();
      
      if (granted) {
        setIsReady(true);
      } else {
        Alert.alert('Location permission is required');
      }
    } catch (error) {
      console.error('Initialization error:', error);
    }
  }

  if (!isReady) {
    return <View style={styles.container} />;
  }

  return (
    <MapView
      style={styles.container}
      initialCameraPosition={{
        target: { latitude: 39.9, longitude: 116.4 },
        zoom: 10,
      }}
      myLocationEnabled={true}
      onLoad={() => console.log('Map loaded')}
    />
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Run Your App

# iOS
npx expo run:ios

# Android
npx expo run:android

Common Issues

Map Not Displaying

Check:

• ✅ API Keys are correct
• ✅ SDK is initialized before map component renders
• ✅ Network connection is available
• ✅ Package name/Bundle ID matches the one registered with API Key

Location Not Working

Check:

• ✅ Location permissions are granted
• ✅ Privacy compliance is configured
• ✅ Location services are enabled on device
• ✅ Permission descriptions are added to Info.plist (iOS)

Build Errors

Solutions:

# Clean build
cd ios && pod deintegrate && pod install && cd ..

# Or for Android
cd android && ./gradlew clean && cd ..

# Rebuild
npx expo prebuild --clean

Next Steps

• Initialization Guide - Detailed initialization and permission setup
• Config Plugin - Automatic configuration with Config Plugin
• API Documentation - Complete API reference
• Examples - More code examples

Need Help?

• GitHub Issues
• Discussions
• QQ Group: 952241387