HERE Mobility SDK for iOS

Version 2.0.2

1. Introduction
   1. Mobility Package
   2. Map Services Package
   3. Sample Apps
2. Pre-requisites
   1. Operating System
   2. 3rd Party Packages
3. Getting Started
   1. Obtaining HERE Credentials for Your App
   2. Adding the HERE Mobility SDK to your App
   3. Initializing the HERE Mobility SDK
   4. Requesting Location Access Permission
   5. Using the HERE Sandbox Platform
4. 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
• Map Services

You can use any combination of these packages. There is no dependency between the different packages. You will need to include the Core package (CoreKit) in your project.

1.1. Mobility Package

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

1.2. Map Services Package

The Map Services package (MapKit) 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:

iOS

React Native

---

2. Pre-requisites

2.1. Operating System

HERE Mobility SDK version 2.0.2 supports iOS version 9.0 or later.

2.2. 3rd Party Packages

• gRPC
• Tangram ES

---

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. Adding the HERE Mobility SDK to your App

We recommend adding the HERE Mobility SDK(s) to your application by using CocoaPods. CocoaPods provides a simple, versioned dependency management system that automates the tedious and error-prone aspects of manually configuring libraries and frameworks.

To set up your local CocoaPods environment and import the desired HERE Mobility SDK modules into your project:

1. Run the following shell commands:

$ sudo gem install cocoapods
$ pod init

2. In the root directory of your project, create a Podfile and add the source for the HERE Mobility SDK repository to the beginning of the file, as follows:

source 'https://github.com/HereMobilityDevelopers/Here-Mobility-SDK-iOS.git'

Also add the default CocoaPods spec repo source

source 'https://github.com/CocoaPods/Specs.git'

Add 'use_frameworks!' to Podfile as HereSDK is dynamic framework

use_frameworks!

3. Depending on the HERE Mobility SDK packages you want to use, add any or all of the following pods to the Podfile (optionally, you can specify which versions to add):

pod 'HereSDKDemandKit', '~>2.0.2'
pod 'HereSDKMapKit', '~>2.0.2'

4. Complete the installation by performing the following commands:

$ pod repo update
$ pod install

These instructions will setup your local CocoaPods environment and import the desired HERE Mobility SDK modules into your project.

3.3. Initializing the HERE Mobility SDK

The SDK's HereSDKManager uses credentials from your app's Info.plist file to initialize. If the appId is missing from the file, the SDK will fail to initialize.

3.3.1 Configuring your app's Info.plist

1. In Xcode, right-click your project's Info.plist file and select Open As -> Source Code.
2. Insert the following XML snippet into the body of your file just before the final </dict> element.

<key>HereMobilitySDKAppId</key>
<string>{your-app-id}</string>

Replace {your-app-id} with your app's ID, that you've obtained from HERE.

In your app's UIApplicationDelegate method didFinishLaunchingWithOptions: call the method to initialize and configure the HereSDK.

The following sections provide examples for how to initialize and configure the SDK in Swift and Objective-C.

Swift

import HereSDKCoreKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

	HereSDKManager.configure()

	return true
}

Objective-C

#import <HereSDKCoreKit/HereSDKCoreKit.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [HereSDKManager configure];

    return YES;
}

3.3.2 Authenticating your app

In order to make Here SDK API calls, you must first "prove" us that it's indeed 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 and all the MapKit services. The recommended procedure is to have your backend server do the following procedure when the app is activated. You will need to generate a signed hash and pass it to the SDK following these steps:

Swift

import HereSDKCoreKit

HereSDKManager.shared().authenticateApplication(HereSDKApplicationAuthenticationInfo(creationTime: date, verificationHash: verificationHash), withHandler: { error in
})

Objective-C

#import <HereSDKCoreKit/HereSDKCoreKit.h>

[[HereSDKManager sharedManager] authenticateApplication:[HereSDKApplicationAuthenticationInfo                                                           applicationAuthenticationInfoWithCreationTime:date verificationHash:verificationHash] withHandler:^(NSError * _Nullable error) {
}];

Note: For reference on how to generate a signed hash (given the secret key) please check iOS sampleApp project (function generateAppCredentials(creationTime : Date) in AuthorizationViewController).

3.3.3 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 Phone number or email verification is done in 2 steps:

3.3.3.1 Receive verification code via SMS/Email

Swift

import HereSDKCoreKit

//Phone verification
HereSDKManager.shared?.sendVerificationSMS(phoneNumber, withHandler: handler)
//Email verification
HereSDKManager.shared?.sendVerificationEmail(email, withHandler: handler)

Objective-C

#import <HereSDKCoreKit/HereSDKCoreKit.h>

//Phone verification
[HereSDKManager.sharedManager sendVerificationSMS:phoneNumber withHandler:handler];
//Email verification
[HereSDKManager.sharedManager sendVerificationEmail:email withHandler:handler];

3.3.3.2 Verify phone number/Email

Swift

import HereSDKCoreKit

//Phone verification
HereSDKManager.sharedManager?.verifyPhoneNumber(phoneNumber pinCode:verificationCode withHandler:handler)
//Email verification
HereSDKManager.sharedManager?.verifyEmail(email pinCode:verificationCode withHandler:handler)

Objective-C

#import <HereSDKCoreKit/HereSDKCoreKit.h>

//Phone verification
[HereSDKManager.sharedManager verifyPhoneNumber:phoneNumber pinCode:verificationCode withHandler:handler];
//Email verification
[HereSDKManager.sharedManager verifyEmail:phoneNumber pinCode:verificationCode withHandler:handler];

3.3.3.3 Check if user is verified

You can check whether user is verified using following API.

Swift

import HereSDKCoreKit

HereSDKManager.shared?.isVerified()

Objective-C

#import <HereSDKCoreKit/HereSDKCoreKit.h>

[[HereSDKManager.shared] isVerified];

3.4. Requesting Location Access Permission

When running the HERE Mobility SDK on iOS, it is mandatory to ask the user for location access permissions in your application flow. After displaying an explanation of why you need location access permission, display a location manager dialog to request location access.

Notes:

• Your application's Info.plist should also contain descriptions explaining location usage for the NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription keys.
• Some SDK features, such as detecting Personal Points of Interest, work better when Always access is granted.

The following sections provide examples for how to request access in Swift and Objective-C.

Swift

import CoreLocation

let locationManager: CLLocationManager = CLLocationManager()

// request location authorization for when application is active
locationManager.requestWhenInUseAuthorization()

// or for allowing location access even when application is not active
locationManager.requestAlwaysAuthorization()

Objective-C

#import <CoreLocation/CoreLocation.h>

CLLocationManager *locationManager = [CLLocationManager new];

// request location authorization for when application is active
[locationManager requestWhenInUseauthorization];

// or for allowing location access even when application is not active
[locationManager requestAlwaysAuthorization];

3.5. 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 change the platform’s state).

The HERE Mobility service directs your app’s calls to the sandbox or production environment according to the app key you provide (there is no need to use different endpoints).

---

4. API Reference

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