5-minute setup
Setting up navigation with our SDK is simple and quick. If you meet the prerequisites, it should take you no more than 5 minutes.
Create a completely new project and let's begin.
Prerequisites
Access to SDK artifacts
Access Required
To obtain a GitLab account, SDK artifacts, the Maven repository URL, an API key, and access to the demo application repository, you must contact us first.
This SDK is distributed through a private GitLab repository. To complete the setup, you will need:
- Our organization's GitLab account.
- Personal Access Token (PAT): A GitLab PAT with the
read_apiscope.- You can generate one in your GitLab User Settings -> Access Tokens.
- You are encouraged to generate multiple tokens as needed for different purposes.
- To enhance security and manageability, we strongly recommend generating a distinct PAT for each specific environment where you use the token (e.g., a dedicated token for local development, and a separate one for CI pipelines).
- Store these tokens securely and treat them like passwords.
- API key - The Navigation SDK requires an API key to function properly. You must provide a valid API key from your service provider to use the features of the library.
Installation
In your GRADLE_USER_HOME directory, create a file gradle.properties with the following content:
Replace YOUR_ACCESS_TOKEN with your GitLab Personal Access Token (PAT)
Add a repositories section to your build.gradle or settings.gradle file:
dependencyResolutionManagement {
repositories {
maven {
url = uri("REPOSITORY_URL")
name = "GitLab"
credentials(HttpHeaderCredentials::class) {
name = "Private-Token"
value = providers.gradleProperty("navigationSdkPackageRepositoryToken").getOrElse("")
}
authentication {
create("header", HttpHeaderAuthentication::class)
}
}
}
}
Replace REPOSITORY_URL with the proper repository URL. You can obtain this URL by contacting us (as mentioned in the Access Required section above)
Add Dependency
Replace $navigation_sdk_version with the latest version from Releases page
Sync your Gradle project, and it should now download the specified artifact from the GitLab Package Registry.
See the documentation for further details.
Add the API key to your app
One common way to supply the API key is to add it to your gradle.properties file (which should not be committed to version control):
Replace YOUR_API_KEY with your API key
Then, you can read it in your app's build.gradle file like this:
val apiKey: String? = properties["navSdkApiKey"] as? String
android {
buildFeatures {
buildConfig = true
}
...
defaultConfig {
...
buildConfigField("String", "NAV_SDK_API_KEY", "\"$apiKey\"")
}
}
Security notice
Make sure not to hard-code your API key directly into your source code or commit it to version control. Always keep your API key secure and avoid exposing it in public repositories or logs. Consider using backend proxies or encrypted secrets management for additional protection if needed.
Location permission
The SDK requires location permission to function. Add the following to the AndroidManifest.xml file:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
Request permission in the main activity.
Example:
private val askPermission = registerForActivityResult(
ActivityResultContracts.RequestPermission()
) { granted ->
if (granted) //permission granted
}
override fun onCreate(savedInstanceState: Bundle?) {
...
askPermission.launch(Manifest.permission.ACCESS_FINE_LOCATION)
...
}
Important Note
The code contains the minimum permission handling necessary for the example to work. For a production deployment, expand this mechanism based on the workflow for requesting permissions in the official Android documentation.
Initialize SDK and start navigation
To start navigation, you need to initialize the SDK, start listening for positions, and start navigation.
Example:
private fun startSDKNavigation(latitude: Double, longitude: Double) {
val initParams = InitParams.Builder(
context = this.applicationContext,
apiKey = BuildConfig.NAV_SDK_API_KEY
).build()
// init SDK
NavigationApi.init(initParams)
lifecycleScope.launch {
// waiting for proper SDK and navigation state (Initialized / NotStarted)
NavigationApi.awaitSdkAndNavigationState(SdkState.Initialized, NavigationState.NotStarted) {
NavigationApi.startLocationTracking()//start listening for position via SDK
NavigationApi.navigate(NavigationParams.Builder(Waypoint(GeoPoint(latitude, longitude))).build())//start navigation to point
NavigationApi.startNavigationActivity(this@MainActivity, true)//starting navigation activity
}
}
}
Monitor errors
Additionally, monitor errors to diagnose and fix problems (set correct API key, turn on GPS/network, etc.)
Example:
// monitor active errors
lifecycleScope.launch {
NavigationApi.errorsState.collect { errors: Errors ->
Log.d("MyApp", "active errors size: ${errors.activeErrors.size}")
errors.activeErrors.forEach {
Log.d("MyApp", "error: $it")
}
}
}
Full code
The code below is sufficient to start navigation (with all available data and sound) to a specific point.
Respect SDK / Navigation lifecycles
Remember to respect SDK / Navigation lifecycles in your app / activity (it depends on manifest configuration etc.) - see details in User Guide:
- Stop current navigation before starting a new one.
- Dispose SDK before initializing it again (or check if SDK is already initialized).
The code below presents only a simple scenario to launch navigation at first activity creation.
class MainActivity : ComponentActivity() {
private val askPermission = registerForActivityResult(
ActivityResultContracts.RequestPermission()
) { granted ->
if (granted) startSDKNavigation(latitude = 52.428893, longitude = 16.942849)//example location
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent {
SDK_QuickSetup_Theme {}
}
askPermission.launch(Manifest.permission.ACCESS_FINE_LOCATION)
}
private fun startSDKNavigation(latitude: Double, longitude: Double) {
val initParams = InitParams.Builder(
context = this.applicationContext,
apiKey = BuildConfig.NAV_SDK_API_KEY
).build()
// init SDK
NavigationApi.init(initParams)
lifecycleScope.launch {
// waiting for proper SDK and navigation state (Initialized / NotStarted)
NavigationApi.awaitSdkAndNavigationState(SdkState.Initialized, NavigationState.NotStarted) {
NavigationApi.startLocationTracking()//start listening for position via SDK
NavigationApi.navigate(NavigationParams.Builder(Waypoint(GeoPoint(latitude, longitude))).build())//start navigation to point
NavigationApi.startNavigationActivity(this@MainActivity, true)//starting navigation activity
}
}
// monitor active errors
lifecycleScope.launch {
NavigationApi.errorsState.collect { errors: Errors ->
Log.d("MyApp", "active errors size: ${errors.activeErrors.size}")
errors.activeErrors.forEach {
Log.d("MyApp", "error: $it")
}
}
}
}
}