Map Kit（Android）

1. Introduction

Overview

The Map SDK for Android provides a set of APIs for map development in Android. The map data covers most countries and regions outside the Chinese mainland, and supports multiple languages. Map Kit uses the WGS 84 GPS coordinate system, which can meet most map development requirements outside the Chinese mainland. You can easily add map-related functions in your Android app, including:

• Map display: Displays buildings, roads, water systems, and Points of Interest (POIs).
• Map interaction: Controls the interaction gestures and buttons on the map.
• Map drawing: Adds location markers, map layers, overlays, and various shapes.

What You Will Create

In this codelab, you can develop map-related apps, for example:

• Sports and health app: The Map SDK enables the app to display maps, locate user devices, and calculate routes.
• Social app: With the Map SDK, the app allows users to share their locations to others.
• Basic map app: The Map SDK empowers the app to display basic maps.

What You Will Learn

In this codelab, you will learn how to:

• Create an app and configure its information in AppGallery Connect.
• Obtain the demo code from Map Kit development documents on HUAWEI Developers.
• Use Android Studio to integrate the Map SDK into your app and develop map-related functions.
• Build and demonstrate a map.

2. What You Will Need

Hardware Requirements

• A computer (desktop or laptop) that runs the Windows operating system
• A Huawei phone or tablet running EMUI 5.0 or later, or a non-Huawei phone running Android 7.0 to 12

Software Requirements

• Android Studio 3.6.1 or later (You can click here to download Android Studio.)
• JDK (JDK 1.8 is recommended. You can click here and download the JDK.)

3. Integration Preparations

To integrate Map Kit, you must complete the following preparations:

• Create an app in AppGallery Connect.
• Add the app package name.
• Create an Android Studio project.
• Generate a signing certificate.
• Generate a signing certificate fingerprint.
• Configure the signing certificate fingerprint.
• Add the AppGallery Connect plug-in and the Maven repository in the project-level build.gradle file.
• Configure the signing certificate in Android Studio.

For details, please refer to Preparations for Integrating HUAWEI HMS Core.

4. Enabling Map Kit

1. - Sign in to AppGallery Connect and click My projects.
2. - Find your project from the project list and click the app for which you need to enable Map Kit on the project card.
3. - Go to Project settings > Manage APIs and enable Map Kit.

5. Setting Your Environment

Adding the AppGallery Connect Configuration File of Your App

1. Download the agconnect-services.json file of your app.
   
2. Add the agconnect-services.json file to the app's root directory of your project.
   

Adding Build Dependencies

1. Open the app-level build.gradle file of your project.
   
2. Add build dependencies in the dependencies block.

   dependencies { 
   	implementation 'com.huawei.hms:maps:{version}' 
   }
   

3. Add apply plugin: 'com.huawei.agconnect' to the file header.
   

6. Developing Map Functions

1. Declare relevant permissions in blocks at the same level as the application block in the AndroidManifest.xml file.

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

2. Add MapView to the layout file. The file path is \mapdemo\app\src\main\res\layout\activity_main.xml.

   <?xml version="1.0" encoding="utf-8"?> 
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 
       android:layout_width="match_parent" 
       android:layout_height="match_parent" 
       android:orientation="vertical"> 
   	
       <com.huawei.hms.maps.MapView  
          xmlns:map="http://schemas.android.com/apk/res-auto" 
           android:id="@+id/mapView" 
           android:layout_width="match_parent" 
           android:layout_height="match_parent" 
           map:cameraTargetLat="51" 
           map:cameraTargetLng="10" 
           map:cameraZoom="8.5" 
           map:mapType="normal" 
           map:uiCompass="true" 
           map:uiZoomControls="true" /> 
   </LinearLayout>
   

3. Add the configuration for calling MapView to the activity file. The file path is \mapdemo\app\src\main\java\com\wz\android\mapdemo\MainActivity.java.
   Java sample code:

   package com.wz.android.mapdemo; 
    
   import androidx.appcompat.app.AppCompatActivity; 
    
   import android.os.Bundle; 
   import android.util.Log; 
    
   import com.huawei.hms.maps.HuaweiMap; 
   import com.huawei.hms.maps.MapView; 
   import com.huawei.hms.maps.OnMapReadyCallback; 
    
   /** 
   * Map activity entrance class. 
   */ 
   public class MainActivity extends AppCompatActivity implements OnMapReadyCallback { 
    
       private static final String TAG = "MapViewDemoActivity"; 
       // Huawei map. 
       private HuaweiMap hMap; 
    
       private MapView mMapView; 
    
       private static final String MAPVIEW_BUNDLE_KEY = "MapViewBundleKey"; 
    
       @Override 
       protected void onCreate(Bundle savedInstanceState) { 
           super.onCreate(savedInstanceState); 
           setContentView(R.layout.activity_main); 
           // Obtain a MapView instance. 
           mMapView = findViewById(R.id.mapView); 
           Bundle mapViewBundle = null; 
           if (savedInstanceState != null) { 
               mapViewBundle = savedInstanceState.getBundle(MAPVIEW_BUNDLE_KEY); 
           } 
    
           // Please replace Your API key with the API key in  
           // agconnect-services.json. 
           MapsInitializer.setApiKey("Your API key"); 
           mMapView.onCreate(mapViewBundle); 
           // Obtain a map instance. 
           mMapView.getMapAsync(this); 
       } 
    
       @Override 
       public void onMapReady(HuaweiMap map) { 
           // Obtain a map instance from callback. 
           Log.d(TAG, "onMapReady: "); 
           hMap = map; 
       } 
   }
   

   Kotlin sample code:

   package com.huawei.mapkitsample 
    
   import android.os.Bundle 
   import android.util.Log 
   import androidx.appcompat.app.AppCompatActivity 
   import com.huawei.hms.maps.CameraUpdateFactory 
   import com.huawei.hms.maps.HuaweiMap 
   import com.huawei.hms.maps.MapView 
   import com.huawei.hms.maps.OnMapReadyCallback 
   import com.huawei.hms.maps.model.LatLng 
   import com.huawei.hms.maps.util.LogM 
    
   /** 
   * Map activity entrance class. 
    */ 
    
   class MapViewDemoActivity : AppCompatActivity(), OnMapReadyCallback { 
    
           // HUAWEI map 
           private var hMap: HuaweiMap? = null 
    
           private var mMapView: MapView? = null 
    
           companion object { 
               private const val TAG = "MapViewDemoActivity" 
               private const val MAPVIEW_BUNDLE_KEY = "MapViewBundleKey" 
           } 
    
           override fun onCreate(savedInstanceState: Bundle?) { 
               LogM.d(TAG, "onCreate:") 
               super.onCreate(savedInstanceState) 
               setContentView(R.layout.activity_mapview_demo) 
               mMapView = findViewById(R.id.mapView) 
               var mapViewBundle: Bundle? = null 
               if (savedInstanceState != null) { 
                   mapViewBundle = 
                   savedInstanceState.getBundle(MAPVIEW_BUNDLE_KEY) 
               } 
               mMapView?.apply { 
                   onCreate(mapViewBundle) 
                   getMapAsync(this@MapViewDemoActivity) 
               } 
           } 
    
           override fun onMapReady(map: HuaweiMap) { 
               Log.d(TAG, "onMapReady: ") 
               hMap = map 
           } 
   }
   

4. Add the lifecycle methods of MapView. The file path is \mapdemo\app\src\main\java\com\wz\android\mapdemo\MainActivity.java.
   Java sample code:

   @Override 
   protected void onStart() { 
       super.onStart(); 
       mMapView.onStart(); 
   } 
    
   @Override 
   protected void onStop() { 
       super.onStop(); 
       mMapView.onStop(); 
   } 
    
   @Override 
   protected void onDestroy() { 
       super.onDestroy(); 
       mMapView.onDestroy(); 
   } 
    
   @Override 
   protected void onPause() { 
       mMapView.onPause(); 
       super.onPause(); 
   } 
    
   @Override 
   protected void onResume() { 
       super.onResume(); 
       mMapView.onResume(); 
   }
   

   Kotlin sample code:

   override fun onStart() { 
       super.onStart() 
       mMapView?.onStart() 
   } 
    
   override fun onStop() { 
       super.onStop() 
       mMapView?.onStop() 
   } 
    
   override fun onDestroy() { 
       super.onDestroy() 
       mMapView?.onDestroy() 
   } 
    
   override fun onPause() { 
       mMapView?.onPause() 
       super.onPause() 
   } 
    
   override fun onResume() { 
       super.onResume() 
       mMapView?.onResume() 
   }
   

5. Verify that required permissions have been assigned. The file path is \mapdemo\app\src\main\java\com\wz\android\mapdemo\MainActivity.java.
   Java sample code:

   private static boolean hasPermissions(Context context, String... permissions) { 
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M && permissions != null) { 
           for (String permission : permissions) { 
               if (ActivityCompat.checkSelfPermission(context, permission) != PackageManager.PERMISSION_GRANTED) { 
                   return false; 
               } 
           } 
       } 
       return true; 
   }
   

   Kotlin sample code:

   private fun hasPermissions(context: Context, vararg permissions: String): Boolean { 
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { 
           for (permission in permissions) { 
               if (ActivityCompat.checkSelfPermission(context, permission) != PackageManager.PERMISSION_GRANTED) { 
                   return false 
               } 
           } 
       } 
       return true 
   }
   

Building, Loading, and Debugging the App

Open Gradle built in Android Studio and double-click installDebug to install the developed demo app.

7. Jointly Debugging and Testing the App

Open the developed app and check whether it can display a map properly.

8. Congratulations

Well done. You have successfully completed this codelab and learned how to:

• Configure the map app information in AppGallery Connect.
• Obtain the demo code from Map Kit development documents on HUAWEI Developers.
• Use Android Studio to integrate the Map SDK into your app and develop map-related functions.
• Build and demonstrate a map.

9. Reference

1. Why is result code 010001 or 010002 returned?
   • The app ID in your project is different from that in AppGallery Connect.
   • No signing certificate fingerprint is configured. You need to generate a signing certificate fingerprint and configure it in AppGallery Connect.
   • The AppGallery Connect configuration file of your app is not configured. You need to follow instructions in Adding the AppGallery Connect Configuration File of Your App to configure it.
   • The API key is not transcoded using encodeURI.
For details about other result codes, please refer to Result Codes.
2. For more information about Map Kit, please refer to Map Kit Development Guide.
3. You can click here to download the source code.