Permissions & auth

Contents

Permissions

In order for the SDK to function and for users to get the navigation experience, certain permissions are required prior to use. Location permissions are required for the routing itself, whereas access to the storage system is needed for caching the map data to the device. Permissions should be added in AndroidManifest.xml under the manifests folder.

You will need to request the following permissions prior to using the SDK:

<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 static com.trimblemaps.navigation.base.internal.extensions.ContextEx.inferDeviceLocale;
import static com.trimblemaps.navigation.base.internal.extensions.LocaleEx.getUnitTypeForLocale;
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
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.api.geocoding.v1.models.TrimbleMapsLocation;
import com.trimblemaps.geojson.Point;
import com.trimblemaps.mapsdk.TrimbleMaps;
import com.trimblemaps.mapsdk.camera.CameraPosition;
import com.trimblemaps.mapsdk.geometry.LatLng;
import com.trimblemaps.navigation.core.TrimbleMapsNavigationProvider;
import com.trimblemaps.navigation.core.TrimbleMapsTrip;
import com.trimblemaps.navigation.core.TrimbleMapsTripProvider;
import com.trimblemaps.navigation.core.trip.model.TripStop;
import com.trimblemaps.navigation.ui.NavigationView;
import com.trimblemaps.navigation.ui.NavigationViewOptions;
import com.trimblemaps.navigation.ui.OnNavigationReadyCallback;
import com.trimblemaps.navigation.ui.listeners.NavigationListener;
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.NAVIGATION_SDK)
                .addLicensedFeature(LicensedFeature.MAPS_SDK)
                .companyId("YOUR-COMPANY-ID-HERE")
                .assetId("YOUR-ASSET-ID-HERE")
                .build();

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

        TrimbleMaps.getInstance(this.getApplicationContext());

        if ((!PermissionsManager.isAndroidElevenPlus() ||
                ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_BACKGROUND_LOCATION) != 0) &&
                ContextCompat.checkSelfPermission(this, 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, Manifest.permission.ACCESS_FINE_LOCATION) &&
                    !PermissionsManager.areLocationPermissionsGranted(Example.this)) {
                permissionsManager.requestBackgroundLocationPermissions(Example.this);
            }
            else if (ArraysKt.contains(permissions, Manifest.permission.ACCESS_BACKGROUND_LOCATION)) {
                // Start activity
            }
        } else if (permissions.length != 0 && ArraysKt.contains(permissions, Manifest.permission.ACCESS_FINE_LOCATION)) {
            // Start activity
        }
    }

import android.os.Bundle
import android.view.View
import androidx.appcompat.app.AppCompatActivity
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.api.geocoding.v1.models.TrimbleMapsLocation
import com.trimblemaps.geojson.Point
import com.trimblemaps.mapsdk.TrimbleMaps
import com.trimblemaps.mapsdk.camera.CameraPosition
import com.trimblemaps.mapsdk.geometry.LatLng
import com.trimblemaps.navigation.base.internal.extensions.LocaleEx.getUnitTypeForLocale
import com.trimblemaps.navigation.base.internal.extensions.inferDeviceLocale
import com.trimblemaps.navigation.core.TrimbleMapsNavigationProvider
import com.trimblemaps.navigation.core.TrimbleMapsTripProvider
import com.trimblemaps.navigation.core.trip.model.TripStop
import com.trimblemaps.navigation.ui.NavigationView
import com.trimblemaps.navigation.ui.NavigationViewOptions
import com.trimblemaps.navigation.ui.OnNavigationReadyCallback
import com.trimblemaps.navigation.ui.listeners.NavigationListener

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.NAVIGATION_SDK)
            .addLicensedFeature(LicensedFeature.MAPS_SDK)
            .companyId("YOUR-COMPANY-ID-HERE")
            .assetId("YOUR-ASSET-ID-HERE")
            .build()


        TrimbleMapsAccountManager.initialize(account)
        TrimbleMapsAccountManager.awaitInitialization()

        TrimbleMaps.getInstance(applicationContext)

        if ((PermissionsManager.isAndroidElevenPlus() && ContextCompat.checkSelfPermission(this,
                Manifest.permission.ACCESS_BACKGROUND_LOCATION
            ) == 0)
            || ContextCompat.checkSelfPermission(this, 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(Manifest.permission.ACCESS_BACKGROUND_LOCATION)) {
                // Start activity
            }
        } else if (permissions.isNotEmpty() && permissions.contains(Manifest.permission.ACCESS_FINE_LOCATION)) {
            // Start activity
        }
    }
}

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

Authentication

Authentication is done by providing your API key, Company ID and Asset ID to the authentication module. You can also just license particular features for use with the current session.

Authentication needs to be done prior to invoking the CoPilot Native Nav SDK.

TrimbleMapsAccount account = TrimbleMapsAccount.builder()
            	.apiKey("YOUR-API-KEY-HERE")
            	.addLicensedFeature(LicensedFeature.NAVIGATION_SDK)
            	.addLicensedFeature(LicensedFeature.MAPS_SDK)
            	.companyId("YOUR-COMPANY-ID-HERE")
            	.assetId("YOUR-ASSET-ID-HERE")
            	.build();

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

TrimbleMaps.getInstance(this);

val account: TrimbleMapsAccount.builder()
    .apiKey("YOUR-API-KEY-HERE")
    .addLicensedFeature(LicensedFeature.NAVIGATION_SDK)
    .addLicensedFeature(LicensedFeature.MAPS_SDK)
    .companyId("YOUR-COMPANY-ID-HERE")
    .assetId("YOUR-ASSET-ID-HERE")
    .build()


TrimbleMapsAccountManager.initialize(account)
TrimbleMapsAccountManager.awaitInitialization()


TrimbleMaps.getInstance(this)

Behind the scenes this will authenticate the current device/app/user for navigation, as well as connect to our web tools, such as Account Manager.

Pay particular attention to the last line of the code above, which needs to be called after authentication has completed.

TrimbleMaps.getInstance(this);

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
}

With this complete, the CoPilot Native Nav SDK is ready to be used. Now, let’s navigate.

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION

INTERACTIVE MAPS

Permissions & auth

Permissions

Authentication