×

One APK with HERE Maps and Google Maps

HERE reference libraries for Google Maps Android API v1 and v2 have been designed to minimize the porting effort from corresponding Google Maps versions. We also provide an option to deploy one APK, supporting both Google Maps v1/v2 and corresponding HERE reference libraries. Please note that the HERE reference libraries pre-bundled to Nokia X services SDK have been designed to require separate APK deployment for HERE reference libraries users. For those looking to deploy only one APK for maps enabled apps, we provide HERE reference libraries using an alternate namespace configuration.

Before you start implementing the application, please make sure that you have fulfilled all the prerequisites described here.

The steps for the porting are as follows:

  1. Modify the manifest file.
  2. Import the wrapper library.
  3. Create layout.
  4. Create the class for the HERE maps usage.
  5. Add codes for selecting the implementation on runtime.

Modify the Android manifest file

The one APK HERE wrapper libraries are requiring the minimum SDK to be set at minimal to 10, thus make sure the uses-sdk tag is specifying the minSdkVersion to be set to 10.

<uses-sdk android:minSdkVersion="10" />

HERE Maps API requires certain permissions to be set which are not required by Google Maps API, thus to make sure that the API works as expected, you need to make sure the following permissions are included in the manifest file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

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">

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.

Import the wrapper library

Before beginning the steps for importing the library, do ensure that the Nokia X services SDK has been successfully installed on your development environment by inspecting the <Android SDK path>/add-ons directory.

Do also note that there are separate libraries provided for Google Maps v1 and v2, and the steps for importing them are also different, thus follow either or both of the instructions depending on which API version(s) you are using with your application.

To import the Wrapper library for Google Maps v2, do the following:

  1. Import the library:
  • From Eclipse, click on File > Import...
  • On the Import dialog box, select Existing Android Code Into Workspace under the Android folder.
  • Browse to the library project located at <Android SDK path>\extras\nokia\nokia_x_services\libs\here\nokia-x-here-maps-wrapper-v2.
  • Check the Copy projects into workspace checkbox and click Finish.
  1. Make sure the library is built correctly:
  • From the Package Explorer, right click on nokia-x-here-maps-wrapper-v2, then Properties.
  • In the new dialog box, select the Android tab, and ensure that the Is Library checkbox is checked.
  1. Add the wrapper library to the application as reference library:
  • From Eclipse, right-click on your project and select Properties, then select Android tab.
  • Click on the Add... button and select the nokia-x-here-maps-wrapper-v2 project, then click OK. You should now see nokia-x-here-maps-wrapper-v2 in the library list as a reference addition to libraries you had there beforehand.

To import the Wrapper library for Google Maps v1, do the following:

  • From Eclipse, right-click on your project and select Properties, then select Java Build Path tab.
  • Under Libraries tab, use the Add External Jars.. button to import com.nokia.android.maps.sdk.jar library into the project. The file can be found under <Android SDK path>\sdk\extras\nokia\nokia_x_services\libs\here folder.
  • Under the Order and Export tab, ensure that the com.nokia.android.maps.sdk.jar library is selected. This ensures that they are packaged as part of your application.
  • Click on the OK button to close the Properties dialog.
  • 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.

Create layout(s) for the HERE maps usage

For the HERE Maps implementation you need to create any layouts that would be used in different classes in which maps APIs are used. The steps for creating the layouts are as follows:

  1. Copy original layout used with Google Maps API and paste it to same folder, when pasting do rename the layout.
  2. Change any Google maps classes used in the layout to be using the wrapper library by changing the com.google namespace to be com.nokia namespace.
  3. Change any IDs used inside the layout to be unique.
  4. Remove any unsupported parts from the layout (for example, apiKey defined for Google v1 Maps API needs to be removed from the layout used with HERE Maps API).

With layout and ID naming you should use some consisting way (for example, add "_here" after the name) to make it easier to use them with the class implementation, as well as to minimize accidental mistakes.

Create the class(es) for the HERE maps usage

  1. Copy original class implementation used with Google Maps API and paste it to same folder, when pasting do rename the class.
  2. Change any Google maps imports used in the class to be using the wrapper library by changing the com.google namespace to be com.nokia namespace.
  3. Change the layout used to be the one created in previous step.
  4. Change any IDs to be the ones used with the layout.

Also with the class naming you should use some consisting way (for example, add "_here" after the name) to minimize accidental mistakes.

Add code for selecting the implementation on runtime

The last part of the porting would be to add the selection logic for selecting the implementation to be used on runtime, based on which API is available in the current running environment. The recommended way to achieve this would be to simply check whether the HERE Maps library is present in the environment. If it is, then use the HERE implementation, and if it is not, then go with the original implementation.

The actual full implementation of the logic would depend on the implementation to be ported, thus the code here is shown as an example to illustrate the usage in one scenario.

Let's assume that there is MapsFragment.java and MainActivity.java. In MainActivity.java we can use the following code:

    private static final String HERE_LIBRARY = "com.here.android";

    private boolean hasHere() {
        String[] systemSharedLibraryNames = getPackageManager().getSystemSharedLibraryNames();
        
        for (String library : systemSharedLibraryNames) {
            if (HERE_LIBRARY.equals(library)) {
                return true;
            }
        }

        return false;
    }

    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        Fragment fragment = null;
        
        if (hasHere()) {
            fragment = new MapsFragmentHere();
        }
        else {
            fragment = new MapsFragmentGoogle();
        }
        
        getSupportFragmentManager().beginTransaction().add(R.id.map, fragment).commit();
    }

Note: The same approach can be used with activities, if fragments are not used.

Sample applications

Sample apps called "Maps V1 One APK" and "Maps V2 One APK" are available in GitHub. These apps demonstrate a single APK that uses the Google Maps, as well as the HERE reference libraries.

To build and run the sample application with Google Maps v2 (Maps V2 One APK), follow these steps:

  1. Import the sample application into Eclipse by clicking File > Import, then selecting Existing Android Code into Workspace.
  2. Modify manifest and change HERE app_id and app_token values to valid keys.
  3. Modify manifest and add Google Maps Android API v2 keys. (Needed only when trying the sample in a device with Google Maps.)
  4. In the same manner, import the Google Play Services library into Eclipse. (See the Android Developers website for more details on the Google Play Services library project.)
  5. Still in the same manner, import the Google Play Services reference library into Eclipse. (See the Android Developers website for more details on the Google Play Services library project.)
  6. Right-click on the sample project, select Android Tools > Add Support Library.
  7. Right-click on the sample project, open the Properties dialog, and select the Android option from the left column. Ensure that the Google Play Services library and HERE reference library is added to the project as a Project Library.
  8. From the same Properties dialog, ensure that the project build target is set to Google APIs.
  9. Next, select the Java Build Path option from the left column. Select the Libraries tab and use the Add External JARs button to add com.here.android.sdk.jar into the project.
  10. Click on the Order and Export tab and make sure that com.here.android.sdk.jar is deselected.
  11. Click OK to close the Properties dialog. Select Run > Run from the menu to run the project.

Video: One APK solution with both HERE Maps and Google Maps v2

The media player is loading...

To build and run the sample application with Google Maps v1 (Maps V1 One APK), follow these steps:

  1. Import the sample application into Eclipse by clicking File > Import, then selecting Existing Android Code into Workspace.
  2. Modify manifest and change HERE app_id and app_token values to valid keys.
  3. Modify strings.xml under res/values and add valid Google Maps Android API v1 key. (Needed only when trying the sample in device with Google Maps. In this case app needs to be signed with a valid certificate linked with the API key.)
  4. Right-click on the sample project, select Android Tools > Add Support Library.
  5. Right-click on the sample project, open the Properties dialog, and select the Android option from the left column. Ensure that the project build target is set to Google APIs.
  6. Next, select the Java Build Path option from the left column. Select the Libraries tab and use the Add External JARs button to add com.nokia.android.maps.jar into the project. com.nokia.android.maps.jar can be found from the submodule nokia-x-here-maps-wrapper-v1 (make sure you update your submodules after cloning the nokia-x-here-maps-samples repository). Click on the Order and Export tab and make sure that com.nokia.android.maps.jar is selected.
  7. Click OK to close the Properties dialog. Select Run > Run from the menu to run the project.

Video: One APK solution with both HERE Maps and Google Maps v1

The media player is loading...


Last updated 12 August 2014

Back to top

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×