Getting started

Contents

With the Mobile Maps SDK, you can embed interactive, highly customizable maps into your mobile applications. (Currently only supported on Android.) Our maps are built on commercial vehicle-specific data from Trimble MAPS, which allows you to plan and visualize safe, legal, and efficient routes for all types of vehicles, around the world. With features ranging from traffic data to weather alerts and road conditions, our Maps SDK is ideal for any application that demands maps for work.

To gain access to the SDK, please contact our Sales team for more information.

This guide is intended to get you on your way to incorporating Trimble’s mapping library into your mobile project. It covers the key concepts needed to install, display, and customize maps.

mobile maps screenshot

Installation

In order to use the Maps SDK, you will need to add it as a dependency to your project. The library can be accessed from a Maven repository. To add the dependency, configure your build to download the Maps SDK:

  1. Open your project in Android Studio
  2. Open up your project-level build.gradle file
  3. Declare the Trimble MAPS repository in the repositories block:
allprojects {
    repositories {
        maven { url "https://trimblemaps.jfrog.io/artifactory/android" }
    }
}
  1. Open up your module-level build.gradle file
  2. Ensure your project’s minSdkVersion is at API 14 or higher
  3. Under dependencies, add a new build rule for the latest SDK:
dependencies {
    implementation 'com.trimblemaps.mapsdk:maps-android-sdk:0.9.27'
    implementation 'com.trimblemaps.mapsdk:maps-sdk-services:0.11.10'
}
  1. Complete a Gradle sync

Permissions

You can use the Manifest merge feature to reduce the need to include any SDK requirements in your application’s manifest file. You’ll need to add either the Fine or Coarse location permission to your manifest if you plan to display a user’s location on the map or get the user’s location information.

The user’s location permission should be checked during runtime using the PermissionsManager.

PermissionsManager permissionsManager;

if (PermissionsManager.areLocationPermissionsGranted(this)) {
    // Permission sensitive logic called here, such as activating the Maps SDK's LocationComponent to show the device's location
} else {
    permissionsManager = new PermissionsManager(this);
    permissionsManager.requestLocationPermissions(this);
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    permissionsManager.onRequestPermissionsResult(requestCode, permissions, grantResults);
}

Authentication

In order to use the APIs and SDK, you will need to authenticate your API key first. If you do not have an API key, you can request one. Authentication must be done prior to attempting to render a MapView or using the APIs. An example can be found below:

// Authorize the api key for the session.
// .apiKey() requires your Trimble Maps API key
TrimbleMapsAccount trimbleMapsAccount = TrimbleMapsAccount.builder()
        .apiKey("Your-API-key-here")
        .build();

// Initialize the session
TrimbleMapsAccountManager.initialize(trimbleMapsAccount);
TrimbleMapsAccountManager.awaitInitialization();

Once authentication is complete, you can start to use the SDK. To see authentication in conjunction with displaying a map, see Displaying a basic map.

Displaying a basic map

To add a map to your application, the Maps SDK provides the MapView class. This provides out-of-the-box capability to display a map with street names, road information etc. Additionally, the map can be styled, moved, rotated etc.

Interaction with the map itself is done through the TrimbleMapsMap object. This can be retrieved using the getMapAsync() method on the MapView.

For a full example, please see the Basic Map example code.

Last updated October 29, 2021.