Getting started

Contents

With the Mobile Maps SDK, you can embed interactive, highly customizable maps into your Android mobile applications. 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. You can also view sample projects and code in our public GitHub repository.

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:

Open your project in Android Studio
Open up your project-level settings.gradle file (settings.gradle.kts file in Kotlin)
If there is already a dependencyResolutionManagement block in the build.gradle file, copy the Trimble Maps Repository in there:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url "https://trimblemaps.jfrog.io/artifactory/android" }
        maven { url "https://jitpack.io" }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { setUrl("https://trimblemaps.jfrog.io/artifactory/android") }
        maven { setUrl("https://jitpack.io") }
    }
}

Open up your module-level build.gradle file
Ensure your project’s minSdkVersion is at API 14 or later
Under dependencies, add a new build rule for the latest SDK:

dependencies {
    implementation("com.trimblemaps.mapsdk:maps-android-sdk:1.3.0")
    implementation("com.trimblemaps.mapsdk:maps-sdk-services:1.4.0")
}

Complete a Gradle sync
For the java code to be run, make sure to set Theme as below in themes.xml file.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="Theme.AsyncAcctInit" parent="Theme.AppCompat" />
</resources>

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, and the Background location permission to continue it while the app is in the background. The Permissions should be added in AndroidManifest.xml under the manifests folder.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

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

import android.os.Bundle;
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import com.trimblemaps.account.LicensedFeature;
import com.trimblemaps.account.TrimbleMapsAccountManager;
import com.trimblemaps.account.models.TrimbleMapsAccount;
import com.trimblemaps.android.core.permissions.PermissionsListener;
import com.trimblemaps.android.core.permissions.PermissionsManager;
import com.trimblemaps.mapsdk.TrimbleMaps;
import com.trimblemaps.mapsdk.maps.MapView;
import com.trimblemaps.mapsdk.maps.OnMapReadyCallback;
import com.trimblemaps.mapsdk.maps.Style;
import com.trimblemaps.mapsdk.maps.TrimbleMapsMap;
import org.jetbrains.annotations.NotNull;
import java.util.List;
import kotlin.collections.ArraysKt;
import kotlin.jvm.internal.Intrinsics;

public final class Example extends AppCompatActivity {

    private final PermissionsManager permissionsManager = new PermissionsManager(null);
    private final PermissionsListener permissionsListener = new PermissionsListener() {
        @Override
        public void onExplanationNeeded(List<String> permissionsToExplain) {
        }

        @Override
        public void onPermissionResult(boolean granted) {
            if (granted && PermissionsManager.isAndroidElevenPlus() && !PermissionsManager.areLocationPermissionsGranted(Example.this)) {
                permissionsManager.requestBackgroundLocationPermissions(Example.this);
            }
        }
    };

    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.setContentView(R.layout.activity_example);

        TrimbleMapsAccount account = TrimbleMapsAccount.builder() // See next section for more info about Authentication
                .apiKey("Your-API-key-here")
                .addLicensedFeature(LicensedFeature.MAPS_SDK)
                .build();

        TrimbleMapsAccountManager.initialize(account);
        TrimbleMapsAccountManager.awaitInitialization();

        TrimbleMaps.getInstance(this.getApplicationContext());

        if ((!PermissionsManager.isAndroidElevenPlus() ||
                ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_BACKGROUND_LOCATION) != 0) &&
                ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) != 0) {
            this.permissionsManager.setListener(permissionsListener);
            this.permissionsManager.requestLocationPermissions(this);
        } else {
            // Start activity
        }
    }

    public void onRequestPermissionsResult(int requestCode, @NotNull String[] permissions, @NotNull int[] grantResults) {
        Intrinsics.checkNotNullParameter(permissions, "permissions");
        Intrinsics.checkNotNullParameter(grantResults, "grantResults");
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);

        if (PermissionsManager.isAndroidElevenPlus()) {
            if (ArraysKt.contains(permissions, android.Manifest.permission.ACCESS_FINE_LOCATION) &&
                    !PermissionsManager.areLocationPermissionsGranted(Example.this)) {
                permissionsManager.requestBackgroundLocationPermissions(Example.this);
            }
            else if (ArraysKt.contains(permissions, android.Manifest.permission.ACCESS_BACKGROUND_LOCATION)) {
                // Start activity
            }
        } else if (permissions.length != 0 && ArraysKt.contains(permissions, android.Manifest.permission.ACCESS_FINE_LOCATION)) {
            // Start activity
        }
    }

import android.app.Activity
import android.os.Bundle
import androidx.core.content.ContextCompat
import com.trimblemaps.account.LicensedFeature
import com.trimblemaps.account.TrimbleMapsAccountManager
import com.trimblemaps.account.models.TrimbleMapsAccount
import com.trimblemaps.android.core.permissions.PermissionsListener
import com.trimblemaps.android.core.permissions.PermissionsManager
import com.trimblemaps.mapsdk.TrimbleMaps
import com.trimblemaps.mapsdk.maps.MapView
import com.trimblemaps.mapsdk.maps.OnMapReadyCallback
import com.trimblemaps.mapsdk.maps.Style
class Example : AppCompatActivity() {
    private val permissionsManager = PermissionsManager(null)
    private val permissionsListener = object: PermissionsListener {
        override fun onExplanationNeeded(permissionsToExplain: MutableList<String>?) {
        }

        override fun onPermissionResult(granted: Boolean) {
            if(granted && PermissionsManager.isAndroidElevenPlus() &&
                !PermissionsManager.areLocationPermissionsGranted(this@Example)) {
                permissionsManager.requestBackgroundLocationPermissions(this@Example)
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_example)

        val account = TrimbleMapsAccount.builder() // See next section for more info about Authentication
            .apiKey("Your-API-key-here")
            .addLicensedFeature(LicensedFeature.MAPS_SDK)
            .build()

        TrimbleMapsAccountManager.initialize(account)
        TrimbleMapsAccountManager.awaitInitialization()

        TrimbleMaps.getInstance(applicationContext)

        if ((PermissionsManager.isAndroidElevenPlus() && ContextCompat.checkSelfPermission(this,
                android.Manifest.permission.ACCESS_BACKGROUND_LOCATION
            ) == 0)
            || ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) == 0) {
            // Start activity
        }
        else {
            permissionsManager.listener = permissionsListener
            permissionsManager.requestLocationPermissions(this)
        }
    }

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
        permissionsManager.onRequestPermissionsResult(requestCode, permissions, grantResults)

        if(PermissionsManager.isAndroidElevenPlus()) {
            if(permissions.isNotEmpty() && permissions.contains(android.Manifest.permission.ACCESS_BACKGROUND_LOCATION)) {
                // Start activity
            }
        } else if (permissions.isNotEmpty() && permissions.contains(android.Manifest.permission.ACCESS_FINE_LOCATION)) {
            // Start activity
        }
    }
}

Android provides a guide to requesting permissions from users as well as details on location access.

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")
        .addLicensedFeature(LicensedFeature.MAPS_SDK)
        .build();

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

// Authorize the API key for the session.
// .apiKey() requires your Trimble Maps API key
val trimbleMapsAccount = TrimbleMapsAccount.builder()
	.apiKey(getString("Your-API-key-here"))
	.addLicensedFeature(LicensedFeature.MAPS_SDK)
	.build()

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

When integrating with our services, it is important to account for potential licensing failures that may occur due to various reasons. To ensure reliable operation and avoid unnecessary API calls that may fail due to licensing issues, we recommend implementing a safety check in your integration.

if (TrimbleMapsAccountManager.isLicensedForMaps(context)) {
    // Proceed with API calls
} else {
    // Handle the licensing failure
}

if (TrimbleMapsAccountManager.isLicensedForMaps(context)) {
    // Proceed with API calls
} else {
    // Handle the licensing failure
}

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.

Asynchronous account initialization (optional)

Authentication can also be performed asynchronously with the use of a callback listener (onAccountInitializationCallback) that handles the account status changes. When the account status changes to LOADED, the main thread is used to initialize the TrimbleMaps instance, set the content view, and set up the MapView. The MapView then asynchronously loads the map and applies a style when the map is ready.

private final TrimbleMapsAccountManager.AccountInitializationListener onAccountInitializationCallback =
	new TrimbleMapsAccountManager.AccountInitializationListener() {
		@Override
		public void onAccountStatusChanged(AccountStatus accountStatus) {
			if (accountStatus == AccountStatus.LOADED) {
				runOnUiThread(new Runnable() {
					@Override
					public void run() {
						TrimbleMaps.getInstance(getApplicationContext());
						setContentView(R.layout.activity_sample_basic_map);
						mapView = findViewById(R.id.mapView);
						mapView.getMapAsync(trimbleMapsMap -> {
							trimbleMapsMap.setStyle(Style.MOBILE_DAY);
						});
					}
				});
			}
		}

		@Override
		public void onAccountStatusFailed(AccountStatus accountStatus, String s) {
			// Handle failure case
		}

		@Override
		public void onLicensingError(List<LicensedFeature> licensedFeatures) {
			// Handle error case
		}
	};

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TrimbleMapsAccount trimbleMapsAccount = TrimbleMapsAccount.builder()
		.apiKey("YOUR API KEY")
		.addLicensedFeature(LicensedFeature.MAPS_SDK)
		.build();
    AccountInitializationOptions accountInitializationOptions = AccountInitializationOptions.builder()
		.callback(onAccountInitializationCallback)
		.build();
    TrimbleMapsAccountManager.initialize(trimbleMapsAccount, accountInitializationOptions);
}

private val onAccountInitializationCallback = object : TrimbleMapsAccountManager.AccountInitializationListener {
    override fun onAccountStatusChanged(accountStatus: AccountStatus) {
        if (accountStatus == AccountStatus.LOADED) {
            runOnUiThread {
                TrimbleMaps.getInstance(applicationContext)
                setContentView(R.layout.activity_sample_basic_map)
                mapView = findViewById(R.id.mapView)
                mapView.getMapAsync { trimbleMapsMap ->
                    trimbleMapsMap.setStyle(Style.MOBILE_DAY)
                }
            }
        }
    }

    override fun onAccountStatusFailed(accountStatus: AccountStatus, s: String) {
        // Handle failure case
    }

    override fun onLicensingError(licensedFeatures: List<LicensedFeature>) {
        // Handle error case
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val trimbleMapsAccount = TrimbleMapsAccount.builder()
        .apiKey("YOUR API KEY")
        .addLicensedFeature(LicensedFeature.MAPS_SDK)
        .build()
    val accountInitializationOptions = AccountInitializationOptions.builder()
        .callback(onAccountInitializationCallback)
        .build()
    TrimbleMapsAccountManager.initialize(trimbleMapsAccount, accountInitializationOptions)
}

A full example of asynchronous account initialization can be found here

Connecting to a proxy server (optional)

Prior to initializing the session, you can create a connection to a proxy server and pass it into the initialize function. The code below demonstrates how to set up a proxy.

InetSocketAddress proxySocket;
        try {
            proxySocket = new InetSocketAddress(InetAddress.getByName("your.proxy.com"), 1234);
        } catch (UnknownHostException e) {
            throw new RuntimeException(e);
        }
        Proxy proxy = new Proxy(Proxy.Type.HTTP, proxySocket);
        AccountInitializationOptions options = AccountInitializationOptions.builder()
                .proxy(proxy)
                .build();
        TrimbleMapsAccountManager.initialize(account, options);

val proxySocket: InetSocketAddress
proxySocket = try {
   InetSocketAddress(InetAddress.getByName("your.proxy.com"), 1234)
} catch (e: UnknownHostException) {
   throw RuntimeException(e)
}
val proxy = Proxy(Proxy.Type.HTTP, proxySocket)
val options: AccountInitializationOptions = AccountInitializationOptions.builder()
   .proxy(proxy)
   .build()
TrimbleMapsAccountManager.initialize(account, options)

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.

Android activity lifecycle methods

Android activity lifecycle methods should be implemented to ensure the app adheres to Android’s lifecycle. See below:

/**
 * Activity Overrides
 */

@Override
public void onLowMemory() {
	super.onLowMemory();
	mapView.onLowMemory();
}

@Override
public void onStart() {
	super.onStart();
	mapView.onStart();
}

@Override
public void onResume() {
	super.onResume();
	mapView.onResume();
}

@Override
public void onStop() {
	super.onStop();
	mapView.onStop();
}

@Override
public void onPause() {
	super.onPause();
	mapView.onPause();
}

@Override
public void onDestroy() {
	super.onDestroy();
	mapView.onDestroy();
}

override fun onLowMemory() {
    super.onLowMemory()
    mapView.onLowMemory()
}


public override fun onStart() {
    super.onStart()
    mapView.onStart()
}


public override fun onResume() {
    super.onResume()
    mapView.onResume()
}


public override fun onStop() {
    super.onStop()
    mapView.onStop()
}


public override fun onPause() {
    super.onPause()
    mapView.onPause()
}


public override fun onDestroy() {
    super.onDestroy()
    mapView.onDestroy()
}

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION