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:

Get Your Credentials

When using the HERE SDK, your application must be authenticated with a set of credentials. Two strings are needed:

  • 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.

Note that these credentials can be reused for more than one app. For example, they will work with all example apps you can find on GitHub.

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 (access_key_id) and ACCESS KEY SECRET (access_key_secret), do the following:

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

The below section shows how to set the credentials for an app.

Try the Example Apps

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

Choose an example of your choice, then set your credentials for the individual Android and iOS projects:

Inside the example app's folder, open /android/app/src/main/AndroidManifest.xml and set your credentials (key / secret) to:

<meta-data android:name="com.here.sdk.access_key_id" android:value="YOUR_ACCESS_KEY_ID"/>
<meta-data android:name="com.here.sdk.access_key_secret" android:value="YOUR_ACCESS_KEY_SECRET"/>

Open /ios/Runner/Info.plist and set your credentials (key / secret) to:

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

Now add the HERE SDK plugin folder:

  1. Unzip the downloaded HERE SDK for Flutter package. This folder contains various files including this documentation.
  2. Inside you will find a TAR file that contains the HERE SDK for Flutter plugin.
  3. Now unzip the TAR file and rename the folder to 'here_sdk' and place it to the plugins folder inside the example app's directory.

Finally, make sure that a device is attached or that an emulator (Android) or simulator (iOS) is running. Execute flutter run from the directory of the example on your terminal - or run the app from within your IDE.

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

Create a New Flutter Project and Show a HERE Map

As a very first step-by-step example, we will develop a "Hello Map" Flutter application that shows - yes! - a map. If you want to integrate the HERE SDK into an existing application, you can skip this step. No specific SDK code is involved here.

If you are new to Flutter, please follow the guides on flutter.dev to help you get started with the first steps.

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

You don't need any advanced Flutter or Android or iOS experience to follow this step-by-step instruction.

For this guide, we have used Android Studio version 4.0.2 and Xcode version 11.5. In addition, we have used:

  • Flutter 1.20.2
  • Dart version 2.9.1

Note: This guide does not cover changes that might be needed when you are migrating your app from a Flutter version that is older than the minium supported Flutter version 1.17.0. All example apps in this guide are compliant with the Flutter V2 plugin architecture. By default, new app projects created with Android Studio are already ready for V2 plugins when Flutter version 1.12 or higher is used.

Step 1: Create a Flutter Project

To create a new HERE SDK for Flutter project:

First, create a new Flutter project, we have called it "hello_map". Make sure you can run your new Flutter project on an Android and iOS device of your choice to make sure that your Flutter SDK is configured correctly. If it does not work, please refer to the Flutter documentation.

If you don't want to support both platforms, you can skip the steps for either iOS or Android. Note that the HERE SDK for Flutter does not support web and desktop apps.

Step 2: Integrate the HERE SDK into Your App

As soon as you have verified that everything is set up correctly, it's time to integrate the HERE SDK for Flutter.

Note that the HERE SDK is only available as a separate download. Artifactory support is not yet available.

Unzip the downloaded HERE SDK for Flutter package. This package contains various files including this documentation:

  • A license file.
  • The Developer's Guide.
  • The API Reference.
  • The Release Notes.
  • A TAR file containing the HERE SDK for Flutter plugin. The file is named like this: here_sdk-<edition>-<version>.release.tar.gz.

Unzip the TAR file, then rename the folder to here_sdk. The content of the plugin folder looks similar like below:

Screenshot: The content of the HERE SDK plugin folder.

Now create a plugins folder inside your project and copy the renamed plugin folder to this new folder. With this, the content of the plugin folder is contained in hello_map/plugins/here_sdk.

Open the pubspec.yaml file of your Flutter project and add the path from above to the dependencies section. If you are not sure where to add this, it should look as follows:

dependencies:
  flutter:
    sdk: flutter

  cupertino_icons: ^0.1.3

  # The following adds the HERE SDK for Flutter plugin folder to your application.
  here_sdk:
    path: plugins/here_sdk

Of course, if you want, you can rename the plugin folder and adjust the path.

If the path is specified correctly, you can execute flutter pub get from your terminal and the HERE SDK should appear in your project tree. For example, if you are using Android Studio, it will appear under External Libraries -> Flutter Plugins.

After you have executed flutter pub get (or clicked the respective Pub get button in Android Studio or any other IDE), a new Podfile is created for iOS. Open hello_map/ios/Podfile and set the platform to the minimum supported iOS version:

# Uncomment this line to define a global platform for your project.
platform :ios, '12.4'
Then open `hello_map/ios/Runner.xcodeproj` with Xcode and set the deployment target to the same iOS version (via Xcode: _General -> Deployment Info -> Target_). This step is needed if you want to build your app later on with `flutter build ios` from the terminal for [release](https://flutter.dev/docs/deployment/ios).

Now, adjust the minimum supported Android SDK version. Open /hello_map/android/app/build.gradle to change the minSdkVersion to:

minSdkVersion 21

Step 3: Set Your Credentials to Authenticate the HERE SDK

Finally, it's time to set the credentials for authenticating the HERE SDK.

Open /hello_map/android/app/src/main/AndroidManifest.xml and add the following meta-data tags nested under the application tag:

<application
    android:name="io.flutter.app.FlutterApplication"
    android:label="hellomap"
    android:icon="@mipmap/ic_launcher">

<meta-data android:name="com.here.sdk.access_key_id" android:value="YOUR_ACCESS_KEY_ID"/>
<meta-data android:name="com.here.sdk.access_key_secret" android:value="YOUR_ACCESS_KEY_SECRET"/>
...

Do the same for iOS, then open /hello_map/ios/Runner/Info.plist and add:

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

<key>io.flutter.embedded_views_preview</key>
<true/>

Make sure to set your own credentials (key / secret).

Note that we also added the key io.flutter.embedded_views_preview, since the HERE SDK map is natively rendered as UiKitView.

Now, all preparation work is done and you can start using the HERE SDK.

Step 4: Show a HERE Map

Let's start coding.

Below you can see how to show a HERE map view. Remove all the code from your main.dart file and replace it with the following:

import 'package:flutter/material.dart';
import 'package:here_sdk/core.dart';
import 'package:here_sdk/mapview.dart';

void main() {
  SdkContext.init(IsolateOrigin.main);
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'HERE SDK for Flutter - Hello Map!',
      home: HereMap(onMapCreated: _onMapCreated),
    );
  }

  void _onMapCreated(HereMapController hereMapController) {
    hereMapController.mapScene.loadSceneForMapScheme(MapScheme.normalDay,
        (MapError error) {
      if (error != null) {
        print('Map scene not loaded. MapError: ${error.toString()}');
        return;
      }

      const double distanceToEarthInMeters = 8000;
      hereMapController.camera.lookAtPointWithDistance(
          GeoCoordinates(52.530932, 13.384915), distanceToEarthInMeters);
    });
  }
}

The HERE SDK requires initialization of its native libraries via SdkContext, which should happen before your app widget is started. Therefore, we updated the main() function of the Flutter project.

Since the HereMap is already implemented as a stateful widget, you can set it directly as the home for your app. The private _onMapCreated callback notifies us when the HereMapController instance is created. The HereMapController allows you to interact with the map.

Before you can see any vector tiles on the map, we must load a map scheme. Here we load MapScheme.normalDay. As an exercise, try out other available map schemes.

The view onto the map can be defined via the camera object. In the example above we show a location in Berlin, Germany.

Step 5: Run Your App

Now, it's time to build and run the app. Attach a device or start an emulator or simulator and execute flutter run from the app's directory - or run the app from within your IDE. If all goes well, you should see a HERE map covering the screen.

Screenshot: Showing the app on an iOS device.

Screenshot: Showing the app on an Android device.

Note that all HERE SDK classes that contain a release() method will not be garbage collected if the instance is no longer referenced or set to null. Therefore, in case you need to clean up the memory, it is recommended to call release() on all instances that are no longer needed for the rest of the lifetime of an app.

Additional Information

Android Permissions

The HERE SDK for Flutter automatically merges all required permissions to the AndroidManifest.xml:

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

These permissions are not sensitive and are immediately granted upon installation by the system - they are always needed, as the HERE SDK needs to have a working internet connection. It is not a requirement to handle these permissions and there are no HERE SDK specific requirements on how to handle permissions.

However, be aware that a user can deny any permission after installation via the device's app settings. You can use a convenience class to notify the user upon app launch like shown here. Note that Flutter itself does not provide any mechanism to handle permissions - and the accompanying Flutter example apps do not utilize any specific Android permission handling. If no internet connection is available, most HERE SDK services will indicate this with an appropriate error message.

HERE Logo Watermark

When using the HERE SDK, it is required that the HERE logo is always visible on the map view. By default, the HERE logo is located at the bottom right corner of the map. However, you can easily customize its location to meet your app design by calling setWatermarkPosition() on your map view instance. It is recommended to change the default placement, only when it is required due to overlapping UI elements.

What's Next?

This is quick start guide is just a starting point. Take a look at our example apps on GitHub and browse through the API Reference to discover a lot more exciting features. With the next releases we plan more tutorials and example apps. Stay tuned and thank you for using the HERE SDK for Flutter!

Note

During the BETA phase this Developer's Guide is limited to the above Get Started section. Under the hood the HERE SDK for Flutter shares the same code base with the HERE SDK for iOS and the HERE SDK for Android, but offers the benefit of a single Dart based API to cover both platforms. Therefore, mostly any feature that is supported by the native HERE SDK family is also available for Flutter - and thus you can take the documentation from there as reference, until it is covered explicitly in this Developer's Guide. However, the Flutter example apps on GitHub already contain Dart snippets for some of the most relevant topics including:

  • Change map schemes.
  • Handle multiple gestures.
  • Use the camera to look at a location.
  • Get the current map viewport.
  • Add map items such as polylines and map markers.
  • Pick a map marker and read the attached meta data.
  • Use an engine to calculate a route and show it on the map.
  • Integrate private venues.
  • Start turn-by-turn navigation with voice commands.

Need Help?

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

  • 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 or API Health.
  • If you have more questions, please check stackoverflow.com/questions/tagged/here-api.
  • If you have questions about billing or your account, Contact Us.
  • If you have purchased your plan/product from a HERE reseller, contact your reseller.

results matching ""

    No results matching ""