This porting guide introduces HERE reference library for Google Maps Android API v2, which provides a replacement library project and a set of wrapper APIs that allow Android developers to easily migrate their existing Google Maps applications to use HERE Maps. Before you start porting, please make sure that you have fulfilled all the prerequisites described here.
Note: If you want to use both Google Maps and HERE Maps in the same APK file and select correct maps on runtime, check One APK guide. This applies also, if you are using other services (like AdMob) that Google Play Services library is providing.
This guide assumes that you have an existing Android application that uses the Google Maps Android API v2. You can also use the map sample that comes with Google Play Services SDK to try the instructions presented in this porting guide on a smaller code base and generally explore the functionality of HERE Maps.
The HERE reference library for Google Maps Android API v2 currently supports applications that were created using Google Maps Android API v2 Revision published on January 2014 or earlier.
Developers using later revisions of the Google Maps v2 APIs may notice some unavailable functionality.
On top of the issues arising from revision changes, there are also some known issues with the wrapper API, and the following list summarises them:
com.google.android.gms.location.LocationClient * setMockLocation and setMockMode are stubs and do nothing. * addGeofences and removeGeofences are stubs and directly call the provided listener with LocationStatusCodes.GEOFENCE_NOT_AVAILABLE.
com.google.android.gms.common.GooglePlayServicesUtil * getOpenSourceSoftwareLicenseInfo returns empty string. * isGooglePlayServicesAvailable always returns ConnectionResult.SUCCESS.
com.google.android.gms.maps.GoogleMap * animateCamera durationMs parameter doesn't do anything. * OnMarkerDragListener.onMarkerDragStart is never called.
com.google.android.gms.maps.model.Circle com.google.android.gms.maps.model.Polygon com.google.android.gms.maps.model.Polyline com.google.android.gms.maps.model.GroundOverlay com.google.android.gms.maps.model.TileOverlay * Z-index: v2 API uses floats for z-index, the HERE z-index is 16-bit integer. Therefore the range and precision are different and might cause unwanted behavior.
com.google.android.gms.maps.model.Polygon * It's possible to specify holes for the Polygon, but the holes are not drawn.
com.google.android.gms.maps.model.TileOverlay * fadeIn is not supported.
You need to make some minor modifications to the AndroidManifest.xml file of your project to enable HERE Maps. First, specify the application version compatibility by adding or editing the following tag:
<uses-sdk android:minSdkVersion="11" android:targetSdkVersion="16" />
Add the additional permissions required by HERE:
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
Within the <application></application> block of tags, add the following library:
<uses-library android:name="com.here.android" android:required="false" />
All applications using HERE API must have a valid application ID (app ID) and application token (app token). See here how to obtain these. Once you have acquired the app ID and token, insert them within the <application></application> block of tags:
<meta-data android:name="com.here.android.maps.appid" android:value="YOUR ID" /> <meta-data android:name="com.here.android.maps.apptoken" android:value="YOUR TOKEN" />
Replace the YOUR ID and YOUR TOKEN strings with the appropriate credentials for your application.
HERE Maps require OpenGL and GPU, so make sure you have OpenGL ES 2.0 usage declared in the manifest file:
<uses-feature android:glEsVersion="0x00020000" android:required="true" />
In addition, either the whole application or the activity using maps needs to have property android:hardwareAccelerated set true:
<application ... android:hardwareAccelerated="true">
<manifest ... > <uses-sdk android:minSdkVersion="11" android:targetSdkVersion="16" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" /> <!-- External storage for caching --> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <!-- My location --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <!-- Addition permissions required by HERE Maps --> <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <!-- Maps API needs OpenGL ES 2.0 --> <uses-feature android:glEsVersion="0x00020000" android:required="true" /> <application ... android:hardwareAccelerated="true"> <!-- HERE API requires this uses-library definition to work --> <uses-library android:name="com.here.android" android:required="true" /> <activity ... > ... </activity> <!-- Application ID and token. Note that the values here are just for show and will not work. You need to obtain your own personal keys for HERE Maps. --> <meta-data android:name="com.here.android.maps.appid" android:value="423897-a9a2c4d8bb4f9b2ec8e3" /> <meta-data android:name="com.here.android.maps.apptoken" android:value="HRtU5_TgBsKjQP7pbiVYIc" /> </application> </manifest>
To begin, you must first import the HERE reference library for Google Maps Android API v2 and replace the Google Play Services library project (google-play-services_lib). For more information about the Google Play Services library project, check the Android developer documentation.
Follow these steps to import the v2 Reference project library:
Check the Copy projects into workspace checkbox and click Finish (see figure 1).
In the new dialog box, select the Android tab, and ensure that the library is using "Android 4.1.2" as its build target. The Is Library checkbox should also be checked (see figure 2).
Once the reference library project has been copied to your workspace, the next step is to configure your application to reference this project:
Click on the Add... button and select the reference-v2_lib project, then click OK. You should now see "reference-v2_lib" in the library list as a reference (see figure 3).
Under the Order and Export tab, ensure that Android Private Libraries is selected (see figure 4). This ensures that the HERE JAR is packaged as part of your application.
From the Eclipse menu, click on Project. Initiate Clean and then build the project to ensure that your project is updated with the latest changes.
Checking other support libraries
If your existing application requires the Android Support Library (e.g. android-support-v4.jar), ensure that the relevant JAR file is also present in your ported project, and it is marked to be exported under Properties > Java Build Path > Order and Export (see figure 5). For instance, the Google Play Services map sample uses FragmentActivity class, which requires version 4 Android support library (android-support-v4.jar) to be linked to the project.
Your application will now use HERE Maps instead of Google Maps. There should be no need to make additional changes to the source code of your app. If you still have problems with the application after following the previous steps, make sure that:
Video: Porting to HERE Maps (Google Maps v2)
Last updated 12 August 2014
We appreciate your feedback.