Get Started

This guide walks you through the first steps to build apps with the HERE SDK. The HERE SDK is tailored to bring the best and freshest assets from the HERE platform to your mobile applications.

Before you begin, make sure you have read the following:

In order to start development, you need to get the HERE SDK package:

Note

Please contact us to receive access including a set of evaluation credentials. For now, the Navigate Edition is only available upon request. Note that the HERE SDK package for the Navigate Edition is only available for customers who have signed a commercial contract via the HERE platform portal. <!-- TODO For now, we hide detailed steps as it is confusing until we get self-service. Make sure you have access, then:

  1. On the platform portal browse to the Navigate Edition. Choose the iOS platform.
  2. Click the Get Now button. Note that the package will download in the background. Be patient, it may take a while.
  3. Unzip the package. It includes the iOS framework (the HERE SDK binary bundle to include in your app(s)), a set of example apps, this documentation and some more useful files. -->

Get Your Credentials

The HERE SDK for iOS requires two strings to authenticate your app:

  • ACCESS KEY ID: A unique ID for your account.
  • ACCESS KEY SECRET: A secret key, which is shown only once after creation time. Please make sure to note it down before leaving developer.here.com.

No other credentials or tokens are needed to use the HERE SDK. You can register and manage your app as described in the Identity & Access Management guide.

Note

Note that these credentials can be reused for the Lite and Explore Editions regardless of the platform - furthermore, you can use these credentials for more than one app. For example, they will work with all example apps you can find on GitHub. For the Navigate Edition you need to contact your HERE representative to generate a set of evaluation credentials.

When you obtain your credentials, also an APP ID is generated. This ID is not consumed by the HERE SDK, but it is recommended to mention it when contacting the HERE support team.

To obtain your personal ACCESS KEY ID (AccessKeyId) and ACCESS KEY SECRET (AccessKeySecret), do the following:

Note

Please contact your HERE representative to receive access including a set of evaluation credentials. For now, the Navigate Edition is only available upon request.

See also the below section Authenticating Applications to learn more details on how to set the credentials for an app.

Try the Example Apps

The easiest way to get started, is to try one of the many example projects that are available for the HERE SDK.

Choose an example of your choice, then:

  1. Add the HERE SDK framework to the app's root folder.
  2. Add your HERE credentials (AccessKeyId and AccessKeySecret) to the Info.plist file.

Now you are ready to open the Xcode project and you can instantly execute the app on your device or simulator.

Note

Did you know that almost every topic of this Developer's Guide is available as executable app?

Feel free to experiment with the code of the examples. You can also follow the below guide to get a more thorough introduction on how to develop apps with the HERE SDK.

Create a New iOS Project

As a very first step-by-step example, we will develop a "Hello Map" iOS application that shows - yes! - a map. If you want to integrate the SDK into an existing application, you can skip this step. No specific SDK code is involved here. We recommend using Xcode as the IDE. If you are new to iOS development, please follow the guides on developer.apple.com to help you get started with the first steps.

Note

The example code for "HelloMap" is available from here.

Start Xcode (for this guide, we have used version 13.0) and Create a new Xcode project:

  • For the template, it is sufficient to choose iOS => Application => Single View App.
  • Click next.
  • Provide a project name, e.g. "HelloMap" and select Swift as the language.
  • Click next and choose an appropriate directory in which to save the project.

In newly created project select a simulator or a real device (which is recommended) as run destination of your application.

For the example below, we have kept the default orientation settings. When running the existing example apps, make sure the Deployment target is set to a version you have installed - we have used iOS 12.4.

Now, build and run the current scheme and confirm that your plain project executes as expected. If all goes well, you should see a blank view without any content.

Say Hello Map!

Once we have a working iOS app, it's time to include the HERE SDK and to show a map on your simulator or device. Here's an overview of the next steps:

  1. Integrate the HERE SDK.
  2. Set required credentials in your plist file.
  3. Add a map view by code or by adding it to a storyboard.
  4. Add the code to load your first map scene.

Note

While all of the functionalities of the HERE SDK are accessible from the simulator, usage of a real device is strongly recommended. The overall performance will be better, and some features like gestures are just easier to use on a multi-touch enabled hardware. The rendering of the map view is optimized for mobile device GPUs.

Let's begin with the first step to see how we can add the HERE SDK to our project.

Integrate the HERE SDK

On developer.here.com you can find the latest release artifacts including the HERE SDK framework to include in your application (named xx.yy.zz.release_date).

Copy the heresdk.xcframework folder to your app's root folder.

In Xcode, open the General settings of the App target and add the heresdk.xcframework to the Frameworks, libraries, and embedded content section (Click "+", then "Add other..." -> "Create folder references").

Note

Note that this guide is based on HERE SDK version 4.10.5.0. If your framework version is different from the version used for this guide, the steps may vary and you may need to adapt the example's source code.

Set Your HERE Credentials

When using the HERE SDK, your application must be authenticated with a set of credentials. For convenience, you can add these to the Info.plist file of your project. There are also alternative ways possible - as shown in the Key Concepts section.

Info

Tip: In the Key Concepts section you can find several ways to initialize the HERE SDK manually. Depending on your contractual details, the time of initialization may have an impact on how transactions and monthly active users (MAU) are counted.

If not already done, you need to acquire a set of credentials from your HERE representative.

Info

If you are using Xcode 13 or newer, you can create a Info.plist file by adding an entry to Project -> Targets -> Info. Once a new entry is added, a new file will be created by Xcode. Alternatively, you can edit the Info tab directly. For older Xcode versions, this file is created automatically by Xcode when creating a new project.

Once you have your credentials at hand, add a new Dictionary entry called "HERECredentials" to your Information Property List file (Info.plist). Inside "HERECredentials", add the following key/value pairs for AccessKeyId and AccessKeySecret. Alternatively, you can also open the file "as source" and add the following XML tags inside the existing <dict> element:

<key>HERECredentials</key>
<dict>
    <key>AccessKeyId</key>
    <string>YOUR_ACCESS_KEY_ID</string>
    <key>AccessKeySecret</key>
    <string>YOUR_ACCESS_KEY_SECRET</string>
</dict>

Note

The credentials are not tied to the name of your app, but to the account used to obtain the credentials. This makes it possible to use the same set of credentials for multiple apps.

Tip: Alternatively, you can set your credentials programmatically, for example, if you don't want to hardcode your credentials in the property list for security reasons.

Add the Map View

Now that we have the SDK integrated into the project and added the required credentials, we can add a new MapView instance.

Note

The map view of the Explore Edition is rendered with the HERE Rendering Engine. A special light-weighted rendering architecture that is optimized for resource-constrained devices is available as part of the Lite Edition.

There are two alternative ways to do this. We will first show how to add a MapView programmatically, then we will show how to add a MapView using a Storyboard.

Note

Note that multiple MapView instances can be created and rendered on the same screen.

Whichever method you choose, you will need to add the following module import line to your ViewController.swift file:

import heresdk

Add the Map View Programmatically

Add a map view variable by adding the following variable declaration to your ViewController class:

var mapView: MapView!

In your viewDidLoad() method, add the following code to initialize the map view:

override func viewDidLoad() {
    super.viewDidLoad()

    // Initialize MapView without a storyboard.
    mapView = MapView(frame: view.bounds)
    view.addSubview(mapView)
}

This gives the MapView the same size as the parent view and then adds it as a subview.

Add the Map View to a Storyboard

You might prefer not to initialize the MapView programmatically as shown above, but rather to build your UI from Xcode's Interface Builder using storyboards. In this case, you don't need to add the above lines to your view controller.

Instead, open your Main.storyboard and select the main view (nested under ViewController). In the Identity Inspector, under Custom Class, type MapView. For Module, type heresdk.

Now, open the Assistant editor, control-click the map view and drag it to your ViewController to create an outlet. The outlet window will pop up; for the name, type mapView and click connect. This will add the following line to your view controller:

@IBOutlet var mapView: MapView!

Now you have an IBOutlet accessible from your view controller which you can start to use. Note that this procedure does not contain any SDK specific actions. MapView behaves exactly like any other UIView.

Info

Alternatively, can I use the map view together with SwiftUI? Yes, since the map view is a UIView subclass, you can wrap the view in a SwiftUI view that conforms to the UIViewRepresentable protocol as shown in this tutorial. Note that SwiftUI requires iOS 13 or higher.

Load a Map Scene

For this first app using the HERE SDK, we want to load one of the default map styles the SDK is shipped with.

In the viewDidLoad() method of our ViewController, we add the following code to load the scene with a map scheme representing a normalDay map render style:

mapView.mapScene.loadScene(mapScheme: MapScheme.normalDay, completion: onLoadScene)

As completion handler we can optionally implement a method that notifies us if loading the scene has succeeded:

// Completion handler when loading a map scene.
private func onLoadScene(mapError: MapError?) {
    guard mapError == nil else {
        print("Error: Map scene not loaded, \(String(describing: mapError))")
        return
    }

    // Configure the map.
    let camera = mapView.camera
    camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
                  distanceInMeters: 1000 * 10)
}

Note that the completion handler is called on the main thread when loading the scene is done. MapError values other than nil will indicate what went wrong.

From MapView, you can access the Camera to set some custom map parameters like the location where you want the map centered on, and a zoom level which is specified by the camera's distance to earth:

let camera = mapView.camera
camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
              distanceInMeters: 1000 * 10)

Note

You can setup the Camera as soon as you have a MapView instance available. However, you can see the changes only taking effect after the completion handler for loading a scene has finished. In general, it is recommended to wait with map manipulations until the scene has loaded. For example, camera operations may be enqueued until the scene is loaded, while other operations simply may have no effect without a map scene.

As an exercise, you can try to replace the above map scheme with the following: .satellite. What do you get? Try out also other map schemes, like the normal night scheme.

Or experiment with one of the available map layers. For example, to enable textured 3D models of prominent landmarks, add the following line of code to your app:

mapView.mapScene.setLayerVisibility(layerName: MapScene.Layers.landmarks, visibility: VisibilityState.visible)

Lastly, it is a good practice to handle the didReceiveMemoryWarning() of your view controller. The SDK provides the handleLowMemory() method to safely clean up any unused resources when it is requested by the OS:

override func didReceiveMemoryWarning() {
    super.didReceiveMemoryWarning()
    mapView.handleLowMemory()
}

In addition, it is recommended to add the following to your AppDelegate class:

func applicationDidEnterBackground(_ application: UIApplication) {
    // Prevent GPU calls when the app runs in background.
    MapView.pause()
}

func applicationWillEnterForeground(_ application: UIApplication) {
    MapView.resume()
}

func applicationWillTerminate(_ application: UIApplication) {
    // Deinitializes map renderer and releases all of its resources.
    // All existing MapView instances will become invalid after this call.
    MapView.deinitialize()
}

This ensures that no render commands are issued when an app goes to background and it helps to free resources of the HERE Rendering Engine when the application terminates.

Now, it's time to build and run the app. If all goes well, you should see a HERE map covering the whole area of the screen. Congratulations, you have just mastered your first steps in using the HERE SDK for iOS.

Screenshot: Showing main map scheme.

Screenshot: Showing 3D landmarks.

Screenshot: Showing satellite map scheme.

Prepare your App for Distribution

The HERE SDK framework is a fat binary, built for device (arm64) and simulator (x86_64). Therefore it contains both architectures. This allows easy deployment on a simulator and on a real device.

Since the HERE SDK framework conforms to Apple's XCFramework bundle type (XCFW), it is ready to be used for the distribution of your app. As it is the practice, in Xcode you have to select a development team to sign your app, select a Generic iOS Device and select Product -> Archive.

Note

An Apple Developer Account is needed when you plan to distribute your app on a real device or share with others, for example, to publish it on Apple's App Store. Without an Apple Developer Account you can run it on an iOS simulator. Alternatively, create Xcode 'Free Provisioning' (Personal Team) profile, which can be used to try your application on a real device. Note that this profile is valid only for limited time.

Troubleshooting

When you run into trouble, please make sure to first check the minimum requirements and the supported devices.

  • I see only a blank white map: Make sure that your HERE credentials are valid and set as described in the Get Started section above. Also, make sure that your device is able to make an internet connection. With slower internet connections, it may take a while until you see the first map tiles loaded. Please also make sure that your device time is set correctly. In rare cases, a wrongly set device time can lead to authentication issues with some backend services.
  • In the logs I see "No map content will be displayed until valid config is provided.": Make sure that your code is really calling loadScene().
  • Xcode complains that MapView is not known: Make sure to integrate the HERE SDK framework as described in the Get Started section above.
  • Xcode doesn't load the module definition for heresdk: This is a Xcode SourceKit error known as rdar://42087654. Make sure to integrate the HERE SDK framework as described in the Get Started section above. Also ensure that path to your project and framework doesn't contain space symbols.
  • Xcode does not compile my project for simulators. I am using a computer with a M1 chip. You are using a HERE SDK version below 4.9.2.0. Try to use a newer HERE SDK version or run in Rosetta mode by excluding the arm64 architecture for "Any iOS Simulator SDK" in the Build Settings/Architectures/Excluded Architectures/Debug setting within Xcode. Select this option in the "TARGETS" settings. Note that this may slightly slow down the performance when running the simulator.

Need Help?

If you need assistance with this or any other HERE product, select one of the following options.

  • If you have a HERE representative, contact them when you have questions/issues.
  • If you manage your applications and accounts through developer.here.com, log into your account and check the pages on the SLA report.
  • If you have more questions, please check stackoverflow.com/questions/tagged/here-api.
  • If you have questions about billing, your account, or anything else Contact Us.
  • If you have purchased your plan/product from a HERE reseller, contact your reseller.

results matching ""

    No results matching ""