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:

• About this Edition
• Minimum Requirements
• Supported Devices

Get the HERE SDK package:

• Register or sign in on the HERE platform portal and download the HERE SDK package: Browse to the edition of your choice and click the Get Now button. Note that the package will download in the background. Be patient, it may take a while.

Depending on your plan the HERE SDK charges based on the number of transactions per month and other parameters such as monthly active users (MAU).

More information can be found in the Commercial Terms & Conditions.

Get Your Credentials

The HERE SDK requires two strings to authenticate your app:

• ACCESS KEY ID (AccessKeyId): A unique ID for your account.
• ACCESS KEY SECRET (AccessKeySecret): A secret key, which is shown only once after creation time. Please make sure to note it down before leaving the page.

No other credentials or tokens are needed to use the HERE SDK.

Your credentials 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 a here.client.id or an APP ID is shown. These IDs are not needed by the public APIs of the HERE SDK, but they can be useful when contacting the HERE support team.

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

App credentials and project scope

When you plan to use the same credentials for multiple apps, then you also need to set a scope to differentiate your apps in our system. If you use your credentials only for a single app, then this is not needed.

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: Copy the folder heresdk.xcframework to the app's root folder. Note that this folder contains more files, including a Info.plist file and two folders (ios-arm64, ios-arm64_x86_64-simulator).
2. Add your HERE credentials (AccessKeyId and AccessKeySecret) to the AppDelegate.swift file of the project.

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

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.

Start Xcode (for this guide, we have used version 14.2) 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.
3. Add a map view by code or by adding it to a storyboard.
4. Add the code to load your first map scene.

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

Integrate the HERE SDK

On here-tech.skawa.fun 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. Note that this folder contains more files, including a Info.plist file and two folders (ios-arm64, ios-arm64_x86_64-simulator).

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..." -> "Add files...").

Set Your HERE Credentials

When using the HERE SDK, your application must be authenticated with a set of credentials.

Once you have your credentials at hand, add your set of credentials programmatically when initializing the HERE SDK (see next step).

Initialize the HERE SDK

The HERE SDK is not initialized automatically. Instead, you can freely decide at which point in time the HERE SDK should be initialized. Initialization happens synchronously on the main thread and takes around 100 ms.

Initialize the HERE SDK by executing the following method before you want to use any feature of the HERE SDK:

private func initializeHERESDK() {
    // Set your credentials for the HERE SDK.
    let accessKeyID = "YOUR_ACCESS_KEY_ID"
    let accessKeySecret = "YOUR_ACCESS_KEY_SECRET"
    let options = SDKOptions(accessKeyId: accessKeyID, accessKeySecret: accessKeySecret)
    do {
        try SDKNativeEngine.makeSharedInstance(options: options)
    } catch let engineInstantiationError {
        fatalError("Failed to initialize the HERE SDK. Cause: \(engineInstantiationError)")
    }
}

Make sure to insert correct credentials for key and secret. By calling makeSharedInstance() you initialize all what is needed to use the HERE SDK. The core class of the HERE SDK is called SDKNativeEngine. Under the hood, this instance is used by any other engine that is offered by the HERE SDK.

Make sure to call this code on the main thread.

Below we show an example how to call initializeHERESDK() in your AppDelegate's application(_ application:launchOptions:) method before accessing the MapView from your layout.

Similarly to initializeHERESDK(), you can also free resources by disposing the HERE SDK:

private func disposeHERESDK() {
    // Free HERE SDK resources before the application shuts down.
    // Usually, this should be called only on application termination.
    // Afterwards, the HERE SDK is no longer usable unless it is initialized again.
    SDKNativeEngine.sharedInstance = nil
}

Below we show an example how to call disposeHERESDK() in your AppDelegate's applicationWillTerminate(application:) method.

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.

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.

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.

Add the Map View using SwiftUI

Alternatively, use the map view together with SwiftUI.

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.

Below you can see how we create a struct that conforms to the UIViewRepresentable protocol:

struct HelloMapSwiftUIView: UIViewRepresentable {

    // Conform to UIViewRepresentable protocol.
    func makeUIView(context: Context) -> MapView {
        let mapView = MapView()        
        return mapView
    }

    // Conform to UIViewRepresentable protocol.
    func updateUIView(_ mapView: MapView, context: Context) {
        // Do something with the map view.
    }

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
    let distanceInMeters = MapMeasure(kind: .distance, value: 1000 * 10)
    camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
                  zoom: distanceInMeters)
}

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
let distanceInMeters = MapMeasure(kind: .distance, value: 1000 * 10)
camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
              zoom: distanceInMeters)

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.enableFeatures([MapFeatures.landmarks : MapFeatureModes.landmarksTextured])

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

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()
    disposeHERESDK()
}

Calling MapView.deinitialize() ensures to free resources of the HERE Rendering Engine when the application terminates. It is also recommended to set the shared instance of the SDKNativeEngine to nil, so it is no longer retained - here we can use the disposeHERESDK() method - as shown above.

Optionally, MapView.pause() and MapView.resume() can be used for use cases where an app wants to stop GPU calls to save energy consumption for invisible map views in an active app, for example, when switching between tabbed map view instances or when a scrollable view holds multiple map view instances. If MapView.pause() and MapView.resume() are called for such cases, one needs to also call pause() and resume() when the app switches between foreground and background in the following event handler functions:

func applicationWillResignActive(_ application: UIApplication) {
    MapView.pause()
}

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

Lastly, it is a good practice to handle the didReceiveMemoryWarning() of your view controller. The HERE 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()
}

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.

Prepare your App for Distribution

The HERE SDK framework (heresdk.xcframework) is not a fat binary, but it contains set of frameworks for several architectures - built for device (arm64) and simulator (x86_64). Therefore it contains multiple architectures. This allows easy deployment on a simulator and on a real device. It also contains debug symbols (dSYM) to symbolicate crashes in Xcode. Find more deatils on how to use the dSYM files to symbolicate crashes here.

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. To build an IPA (iOS App Store Package) file in Xcode, follow below steps:

1. Before building an IPA, make sure you have the appropriate distribution certificate and provisioning profile for your app. You can obtain these from the Apple Developer portal. Install the distribution certificate in your keychain, and download the provisioning profile to your computer.
2. Open your project in Xcode: Open your app's .xcodeproj or .xcworkspace file in Xcode.
3. In the top left corner of the Xcode window, select the active scheme dropdown menu (next to the play and stop buttons). Choose the target device or simulator for which you want to build the IPA.
4. Select your project in the Project Navigator (the left sidebar) and navigate to the "Signing & Capabilities" tab. Under the "Signing" section, select your development team and ensure the "Automatically manage signing" checkbox is enabled. Xcode will select the appropriate provisioning profile for you.
5. Click on your project in the Project Navigator, and then click on "Edit Scheme" in the top menu. In the Scheme editor, select the "Run" action and set the "Build Configuration" dropdown to "Release." Click "Close" to save your changes.
6. To build an IPA, you need to archive the project. In Xcode's top menu, click on "Product" and then choose "Clean Build Folder" to clean the project. Next, click on "Product" again and choose "Archive" to create an archive of your project.
7. Once the archiving process is complete, the "Organizer" window will appear. Select your archive in the left column, and then click the "Distribute App" button on the right side. Choose "App Store Connect" as the distribution method, and click "Next." Choose "Upload" or "Export" depending on whether you want to upload the IPA directly to App Store Connect or save it to your computer.

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.

The binary size of an exported app (ie. resulting IPA) for a target device will occupy less space. Note that you can also manually remove files that are not required. However, please keep in mind that the IPA still contains all architectures - unless you explicitly excluded them when archiving: The actual size on the device will occupy much less space and Apple will ensure that only the required architectures are included. Thus, also the actual download size from the App Store will be much smaller. See also this Xcode guide. Therefore, we recommend to keep the HERE SDK framework as it is when the app is deployed through the App Store - since all size optimization happens automatically as part of the deployment process.

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.
• I see no map and/or my HERE SDK calls do nothing: If you see the following log message "These credentials do not authorize access" then your credentials are not valid. Make sure you use a working set of credentials. Credentials from the 3.x editions are not compatible. Credentials from the Explore Edition are not compatible with the Navigate Edition.
• When I build for iOS release, the build fails: If you see in the logs that -embed-bitcode is executed, make sure to explicitely disable bitcode optimization. Apple deprecated bitcode and the HERE SDK no longer supports it. Add ENABLE_BITCODE = NO; to your debug / release Xcode build settings.
• Archive option is grayed out or disabled in Xcode: The most common reason for the "Archive" option being disabled is having a simulator selected as the active scheme. Make sure you have a physical device or the "Generic iOS Device" option selected in the active scheme dropdown menu. Another reason could be wrong workspace setting. Click on the workspace in the Project Navigator, then click on "Edit Scheme." Under the "Build" tab, ensure that the "Archive" checkbox is selected for your target.

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 here-tech.skawa.fun, log into your account and check the pages on the SLA report.
• Join our Slack Workspace.
• If you have more questions, you can also try to look for answers on 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.