Getting started

With the Mobile Maps SDK, you can embed interactive, highly customizable maps into your iOS 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.

Installation

In order to use the Maps SDK, you will need to add it as a Carthage dependency to your project. To add the dependency, configure your Cartfile to download the Maps SDK:

1. Create a Cartfile with the following dependency:

# Latest release
binary "https://trimblemaps.jfrog.io/artifactory/carthage/TrimbleMaps.json" == 1.0.1
binary "https://trimblemaps.jfrog.io/artifactory/carthage/TrimbleMapsMobileEvents.json" == 1.0.0
binary "https://trimblemaps.jfrog.io/artifactory/carthage/TrimbleMapsAccounts.json" == 1.0.1

2. Run carthage bootstrap --platform iOS --use-xcframeworks
3. Open your project in Xcode.
4. Open the General tab in the project settings.
5. Add Carthage/Build/TrimbleMaps.xcframework to Frameworks, Libraries and Embedded Content, and ensure Embed & Sign is set.

Permissions

A mobile maps user will expect the SDK to continue to track their location even while a different application is visible or the device is locked. To do this, go to the Signing & Capabilities tab and click on +Capability. Under the Background Modes section, enable Location updates. (Alternatively, add the location value to the UIBackgroundModes array in the Info tab.)

Certain application features may require full-accuracy locations. The Trimble Maps SDK for iOS provides a wrapper of Apple’s Core Location APIs. It requests temporary access to full-accuracy locations when the user has opted out.

Make the following adjustments to your Info.plist file to enable these prompts and provide explanations to appear within them, including a a brief explanation of how the app will use location data for temporary access.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your precise location is used to show your location on the map.</string>

Add LocationAccuracyAuthorizationDescription as an element of the NSLocationTemporaryUsageDescriptionDictionary dictionary to give users a brief explanation of why a feature in your app requires their exact location.

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>LocationAccuracyAuthorizationDescription</key>
  <string>Please enable precise location to show your location on the map.</string>
</dict>

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
init() {
        let account = Account(apiKey: "Your-API-key-here", region: Region.worldwide)
        AccountManager.default.account = account
        AccountManager.default.delegate = AccountDelegate()
    }

    class AccountDelegate: AccountManagerDelegate {
        func stateChanged(newStatus: AccountManagerState) {
            if newStatus == .loaded {
                // Account has initialized successfully, the SDK can now be used
            }
        }
    }

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() {
    // Proceed with API calls
} else {
    // Handle the licensing failure
}

Once authentication is complete, you can start to use the SDK.

Displaying a basic map

To add a map to your application, the Maps SDK provides the TMGLMapView 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.