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 5.0 "Lollipop" (API Level 21) or higher
  • Android Studio Electric Eel (2022.1.1) or above (building with earlier version might be possible, but is not tested, nor supported)
  • Mass storage is required for persistent storage of map data. At a minimum, 50MB of free space is required to be available for map data

Integrate the SDK

Info

The tutorial is suitable for SDK Version 21.

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 1.8
        targetCompatibility 1.8
    }
}

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 onInstance callback, 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, which is available since version 17. 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)

SygicEngine.initialize(
    applicationContext,
    null,
    object : LogConnector() {
        override fun onLogReceived(message: String?, logLevel: Int) {
            super.onLogReceived(message, logLevel)
            //print, save or send the log to firebase
        }
    },
    config.build(),
    object : SygicEngine.OnInitCallback {
        override fun onError(exception: CoreInitException) {
            // handle any errors
        }

        override fun onInstance(context: SygicContext) {
            // your code
        }
    })

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 wait for the success callback from the MapStreamingListener 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 ...

        // Every SDK Provider will wait for SDK to be initialized. 
        // You can also use asynchronous version of getInstance method to not block UI thread
        OnlineManagerProvider.getInstance().get().enableOnlineMapStreaming(object: OnlineManager.MapStreamingListener {
            override fun onSuccess() {
                // great, online map streaming is enabled
            }

            override fun onError(p0: OnlineManager.MapStreamingError?) {
                // 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(...)"

        mapFragment?.getMapAsync(object : OnMapInitListener{
            override fun onMapInitializationInterrupted() {
                // handle the error
            }

            override fun onMapReady(mapView: MapView) {
                // now you can work with the mapView, for example set the FpsConfig, or add new objects
                mapView.fpsLimit = FpsConfig(FpsConfig.FpsMode.PERFORMANCE, 60f)
                mapView.mapDataModel.addMapObject(MapMarker.at(GeoCoordinates(48.123, 12.345)).build())
            }
        })

    }
}