HERE Mobility - Android SDK

Version 2.0.76, August 2019

Table of contents

1. INTRODUCTION
   1. Mobility Demand
   2. Map Services
   3. Sample apps
2. PRE-REQUISITES
   1. Operating System
3. GETTING STARTED
   1. Obtaining HERE Credentials for Your App
   2. Integrating Google Play Services into Your App
   3. Adding the HERE Mobility SDK as a Dependency
   4. Enabling Multidex
   5. Setting the Java Language Version
   6. Configuring Your AndroidManifest.xml File
   7. Creating an Application Class
   8. Initializing the HERE Mobility SDK
   9. Authenticating your app
   10. Using the HERE Sandbox Platform
   11. Update gms security provider (for Android API <= 19)
4. 3rd Party dependencies
5. TUTORIAL
6. API REFERENCE

1. Introduction

The HERE Mobility SDK helps you create apps with rich and dynamic mobility functionality. The SDK accesses the HERE Mobility Marketplace, a centralized platform for managing mobility data using intelligent algorithms.

The HERE Mobility SDK contains 2 packages:

• Mobility Demand
• Map Services

You can use any combination of these packages. The only requirement is that you use the same version for all of them.

1.1. Mobility Demand

The Mobility Demand package allows your app to request and manage passenger rides anywhere in the world, supplied with the HERE Mobility Marketplace. This includes requesting ride offers, booking and canceling rides, and updating a ride’s status.

1.2. Map Services

The Map Services package provides comprehensive map capabilities, including:

• Searching for locations by address or name
• Dynamic rendering of map display
• Point-to-point route calculation

1.3. Sample Apps

Try out our sample apps:

Android

React Native

2. Pre-Requisites

2.1. Operating System

The HERE Mobility SDK version 2.0.76 supports Android version 4.1 (API level 16) or later.

Also the SDK requires androidx components.

3. Getting Started

3.1. Obtaining HERE Credentials for your App

To use the HERE Mobility SDK, you'll need App ID key and App secret key values. To get new app keys, sign up first to Here Mobility Developer Zone and then register your app using the app bundle id/package name.

3.2. Integrating Google Play Services into Your App

Set up Google Play Services in your app and add the play-services-location module as a dependency.

3.3. Adding the HERE Mobility SDK as a Dependency

In your project’s root build.gradle, add the following to your repositories section:

repositories{ 
	...
	maven{
		url "https://mobility.bintray.com/sdk"
	} 
}

In your app module’s build.gradle, add the following lines to your dependencies section (only include the modules you want):

dependencies{
	...
	implementation "com.here.mobility.sdk:demand:2.0.76"
	implementation "com.here.mobility.sdk:map:2.0.76"
}

3.4. Enabling Multidex

To use the HERE Mobility SDK, you will need to enable multidex for your app.

3.5. Setting the Java Language Version

If you’re using Java 7, add the following to the Android section of your app module’s build.gradle:

android{ 
	...
	compileOptions{ 
		sourceCompatibility JavaVersion.VERSION_1_7 
		targetCompatibility JavaVersion.VERSION_1_8 
	}
}

If you’re using Java 8, add the following to the Android section of your app module’s build.gradle:

android{ 
	...
	compileOptions{ 
		sourceCompatibility JavaVersion.VERSION_1_8 
		targetCompatibility JavaVersion.VERSION_1_8 
	}
}

3.6. Configuring Your AndroidManifest.xml File

HERE Credentials

Add the following lines to the <application> section of your AndroidManifest.xml file (inserting your actual API key in place of YOUR_API_KEY):

<meta-data android:name="com.here.mobility.sdk.API_KEY" android:value="YOUR_API_KEY"/> 

Alternately you may set the API key in code. see 3.8. below

Internet and Location Access Permissions

To allow your app to access location information and to enable HERE Mobility SDK operation, add the following permissions to your AndroidManifest.xml file:

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

Note: If your targetSdkVersion is 23 or higher, you must also ask the user for location permissions at runtime.

3.7. Creating an Application Class

If you already have an Application class, you can skip this step. Otherwise, refer to android documentation for instructions.

3.8. Initializing the HERE Mobility SDK

In your Application class’ onCreate() method, add Sdk.init(this), as follows:

public void onCreate(){
	super.onCreate();
	
	MobilitySdk.init(this);
	if (MobilitySdk.getInstance().isHereAgentProcess()){
		return;
	}
	
	// The rest of your code, if any, here
}

If you wish to set your API key in code instead of in manifest, you should call

    MobilitySdk.init(this, YOUR_API_KEY);

Instead.

3.9.1 Authenticating your app

In order to make Here SDK API calls, we must validate your app by signing your App Key with the Secret Key provided to you as part of your app registration process. You may use the Hash app level authentication to get access for : requestRideOffers, getVerticalsCoverage requests only. The recommended procedure is:

1. Hold your secret key in the backend server of your app.
2. Generate the hash in your app's backend.
3. Pass the hash to the client.

Then pass it to the SDK following these steps:

MobilitySdk.getInstance().authenticateApplication(
	ApplicationAuthInfo.create(hash, currentTimeSec));

The currentTimeSec parameter tells us when this authentication hash was created (in seconds, since Epoch) .

Below is example Android code that uses the Secret Key to generate a signed hash:

@NonNull
private static String signedHash(@NonNull String apiKey,     // Your API Key
                                    long currentTimeSec,     // The creation time of the Application auth info in seconds since epoch
                                 @NonNull String secretKey){ // Your Secret Key
	try{
		Mac mac = Mac.getInstance("HmacSHA384");
		Charset ascii = Charset.forName("US-ASCII");
		mac.init(new SecretKeySpec(secretKey.getBytes(ascii), mac.getAlgorithm()));
		
		String apiKey64 = Base64.encodeToString(apiKey.getBytes(ascii), Base64.NO_WRAP);
       String data = apiKey64 + "." + currentTimeSec;
       byte[] rawHash = mac.doFinal(data.getBytes(ascii));
		
		// Encode into a hexadecimal string
		StringBuilder hash = new StringBuilder();
		for (int i = 0; i < rawHash.length; ++i){
			hash.append(String.format("%02x", rawHash[i]));
		}
		return hash.toString();
	} catch (NoSuchAlgorithmException | InvalidKeyException e){
		throw new IllegalStateException("HmacSHA384 and US-ASCII must be supported", e);
	}
}

Note: For reference on how to generate a signed hash (given the secret key) please check Android sampleApp project (function appLogin in AuthUtils).

3.9.2 User verfication

We require a second level of authentication for booking a ride ,receiving ride updates, cancellation etc.. (all rides related demand API calls) ,verifying that the phone number or email provided by your users is valid. Access to the Maps module API doesn’t require phoneor email verification Phone number or email verification is done in 3 steps:

3.9.2.1 Check if user is verified

	boolean isUserVerified = MobilitySdk.getInstance().isUserVerified();

3.9.2.2 Receive verification code by phone number or email

Phone verification:

	ResponseFuture<Void> futureVerification = 
			MobilitySdk.getInstance().sendVerificationSms(userPhoneNumber);
	futureVerification.registerListener(phoneVerificationResponseListener);

Email verification:

ResponseFuture<Void> futureVerification = 
MobilitySdk.getInstance().sendVerificationEmail(userEmail);
futureVerification.registerListener(emailVerificationResponseListener);

3.9.2.3 Verify pin

Verify phone number pin:

	ResponseFuture<Void> verifyUserPhoneFuture = 
		MobilitySdk.getInstance().verifyUserPhoneNumber(phone, code);
        verifyUserPhoneFuture.registerListener(verifyPhoneFutureResponseListener);

Verify email pin:

ResponseFuture<Void> verifyUserEmailFuture = 
MobilitySdk.getInstance().verifyUserEmail(email, code);
verifyUserEmailFuture.registerListener(verifyEmailFutureResponseListener);

3.10. Using the HERE Sandbox Platform

You can use the HERE Mobility Sandbox platform to develop and test your app’s functionality without calling the production platform. Requests to the sandbox environment are ephemeral (do not actually affect the real world).

The HERE Mobility service directs your app’s calls to the sandbox or production environment according to the API key you provide.

3.11. Update GMS security provider (for Android API <= 19)

Here mobility SDK uses TLS 1.2.

If your app is using android API version <= 19 the TLS security provider might not be up-to-date, thus all network requests will fail.

Update the security provider using the following link: https://developer.android.com/training/articles/security-gms-provider

4. 3rd Party Packages

• gRPC
• Tangram ES

5. TUTORIAL

For Tutorial HERE Mobility Tutorial.

6. API Reference

For detailed information about HERE Mobility SDK functions, please refer to the HERE Mobility API reference.