Skip to content

Getting Started

To start using the SDK you need to request an APP key which is used for initialization.

How to get an APP key?

Please contact us to get an APP Key.

Once you get your APP key, below we will guide you through several first steps to integrate a MapFragment into an Android application and initialize the SDK.

System Requirements

  • Android 8.0 "Oreo" (API Level 26) or higher
  • Android Studio Narwhal (2025.1.3) or above (building with earlier version might be possible, but is not tested, nor supported)
  • Minimum Gradle wrapper version 8.11.1

Device requirements:

  • Mass storage is required for persistent storage of map data. At a minimum, 100MB of free space is required to be available for map data (hugely depends on the country you want to use).
  • At least 3GB total RAM

Integrate the SDK

Info

The tutorial is suitable for SygicMapsSDK Version 30.

Add the Maven repository into your project's build.gradle file:

repositories {
    maven {
        url "https://public.repo.sygic.com/repository/maven-sygic-releases/"
    }
}

Add the following dependency into your application's build.gradle file. Note the @aar part, it is necessary to use a correct SDK version. Check the Release notes for the latest version. You can define the sygicSdkVersion variable in the ext part of your project's build.gradle file, or you can replace it directly.

dependencies {
    implementation("com.sygic.sdk:maps-android:$sygicSdkVersion@aar") {
        transitive true
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

Initialize the SDK

The first step to integrate Sygic Maps SDK is to initialize the SygicEngine.

Important

This has to happen before using any other part of the SDK.

If the initialization was successful, you will get an instance of SygicContext object, which is required to destroy the SDK if you want to do so. You can save the instance obtained from the SygicContextInitResult.Success result of SygicEngine.initialize method, or you can get the same instance anytime via the static method SygicContext.getInstance().

The recommended place to call the initialization is in theonCreate() method of your Activity. In case that the SDK was already initialized, you will get the same SygicContext instance as before. Please, bear in mind that we do not recommend doing it in the Application's onCreate() method as because of its lifecycle, Android might wake the application up in the background anytime and that would cause redundant network traffic. It is necessary to pass the JSON configuration as a string. You can either create it yourself or use the JsonConfigBuilder. You can read more here.

The clientID, license key and path configuration items are necessary for proper configuration. The license key is required for proper initialization of SDK. The license key makes it possible to initialize the SDK without internet for the first time. It also crucially diminishes the time necessary for the initialization of SDK as it is not necessary to wait for the HTTP response from the licensing server anymore.

Tip

If you would like to receive logs from the SDK in your application, pass a LogConnector object into the .initialize method just like below. Please note that you also need to register a DiagnosticsAppender to receive the logs.

import com.sygic.sdk.SygicEngine
import com.sygic.sdk.context.CoreInitException
import com.sygic.sdk.context.SygicContext
import com.sygic.sdk.diagnostics.LogConnector

// create a JsonConfigBuilder
val config = SygicEngine.JsonConfigBuilder()
// set the path to the application
val path = applicationContext.getExternalFilesDir(null).toString()
config.storageFolders().rootPath(path)
// the license key is required since SDK21
config.license("YOUR_LICENSE_KEY")
// you can set your clientId here
val appKey = "YOUR_SDK_APP_KEY"
config.authentication(appKey)
// enable the online maps directly at the start
config.mapReaderSettings().startupOnlineMapsEnabled(true)

val initRequest = SygicContextInitRequest(
    jsonConfiguration = config.build(),
    context = applicationContext,
    logConnector = object : LogConnector() {
        override fun onLogReceived(message: String, logLevel: LogLevel) {
            super.onLogReceived(message, logLevel)
            //print, save or send the log to firebase
        }
    }
)

// run in your suitable coroutine scope
scope.launch {
  val sdkInitResult = SygicEngine.initialize(initRequest)
  when (sdkInitResult) {
    is SygicContextInitResult.Success -> {
        // SDK context initialized successfully
        // you may save SygicContext instance from sdkInitResult.instance
    }
    is SygicContextInitResult.Error -> {
        // handle SDK init error with CoreInitException from sdkInitResult.error
    }
  }
}

To integrate a map into an application is to insert a MapFragment to the view layout of the application. You can do this by adding MapFragment to the layout XML as follows:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <fragment
        android:id="@+id/mapFragment"
        class="com.sygic.sdk.map.MapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"></fragment>
</LinearLayout>

Alternatively, you can add the MapFragment to your Activity in code.

val fragmentManager: FragmentManager = supportFragmentManager
val fragmentTransaction: FragmentTransaction =
    fragmentManager.beginTransaction()
val fragment = MapFragment()
fragmentTransaction.add(R.id.fragment_container, fragment)
fragmentTransaction.commit()

After adding the MapFragment to the layout, the fragment must be initialized using the getMapAsync() function. The MapFragment initialization is processed asynchronously. During initialization, the map engine is initialized to create an instance of MapView that is associated with the MapFragment.

Important

It is imperative that the SDK is initialized when requesting the MapView.

The following code illustrates the basic initialization flow when an Activity is created. The onlineManager.enableOnlineMapStreaming() call enables online maps.

Important

You should always check the result from the enableOnlineMapStreaming before doing simple operations such as calculating a route.

To ensure that the online maps are enabled during the initialization, you can add the following code to your configuration: config.mapReaderSettings().startupOnlineMapsEnabled(true), or to the appropriate field in the JSON if you use it.

To display offline maps, see Offline maps.

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.sygic.sdk.map.MapFragment
import com.sygic.sdk.map.MapView
import com.sygic.sdk.map.`object`.MapMarker
import com.sygic.sdk.map.fps.FpsConfig
import com.sygic.sdk.map.listeners.OnMapInitListener
import com.sygic.sdk.position.GeoCoordinates
import com.sygic.sdk.online.OnlineManager
import com.sygic.sdk.online.OnlineManagerProvider


class MapActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Make sure SDK is already initialized or add initialization code here ...

        // use your suitable coroutine scope
        scope.launch {
            // Every SDK Provider will wait for SDK to be initialized.
            val operationResult = OnlineManagerProvider.getInstance().enableOnlineMapStreaming()
            if (operationResult is OperationResult.Success) {
                // great, online map streaming is enabled
            }
            if (operationResult is OperationResult.Error) {
                // do something on error
            }

            //if you added the MapFragment to the XML layout, assign it like this
            val mapFragment = supportFragmentManager.findFragmentById(R.id.mapFragment) as MapFragment

            // if you used the second way, you would just call "fragment.getMapAsync()"
            val getMapResult = mapFragment.getMapAsync()
            if (getMapResult is GetMapResult.Success) {
                // now you can work with the mapView, for example set the FpsConfig, or add new objects
                val mapView = getMapResult.mapView
                mapView.setFpsLimit(FpsConfig(FpsConfig.FpsMode.PERFORMANCE, 60f))
                mapView.mapDataModel.addMapObject(MapMarker.at(GeoCoordinates(48.123, 12.345)).build())
            }
            else {
                // handle the error
            }
        }

    }
}