01 First project

Overview

This tutorial will teach the basics to create a project with the NavigationSDK in Android Studio. You will learn how to add the NavigationSDK as a project dependency, how to initialize the SDK correctly and which additional data you need to use the SDK.

NavigationSDK files

• docs (SDK documentation files)
  • javadoc (SDK Java wrapper API documentation)
• maps (prepackaged map data)
• sdcard (necessary data to run the tutorials)
• sdk (NavigationSDK library)
• tutorial (tutorial sources)
• license.key (license key for the SDK)

Attention

With your copy of the SDK you get a test license.key file. With this license.key you are able to test the SDK until a specified date. Please contact PTV if your test license.key has expired.

Create your first NavigationSDK project

Please use "com.ptvag.navigation.tutorial" as the package name to be in sync with the data directory, we later will introduce. To create our first NavigationSDK project you first have to create a new Android Project with an empty Activity. (Hint: Creating an Android Project) Set the Target-SDK version to 22 to avoid problems in later tutorials with permission requests (Android target versions > 22 will not grant permissions to any resources like GPS or network when the user not explicitly allows the permission. If you want to use a newer target version, please implement the user request in the corresponding tutorial for yourself). Then navigate to the app directory in you created project and create a directory called "libs". Copy the navigationSDK.aar to the libs directory.

Edit the Top-level Build File ('build.gradle') and add the flatDir libs entry to the repositories section so that gradle can find the NavigationSDK.aar.

allprojects {
    repositories {
        jcenter()
        flatDir {
            dirs 'libs'
        }
    }
}

Now add the navigationSDK.aar as a dependency to your app Module-level Build File. Add a compile dependency to the dependencies section.

dependencies {
    compile(name:'navigationSDK', ext:'aar')
}

Prepare the map data

Before we can use the SDK your app needs some app data on the device. To get the possible directories where android allows us to put the map data we edit the MainActivity.java

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        File dir = getExternalFilesDir(null);
        Log.v("Installation Folder", dir.getAbsolutePath());
    }
}

Run your application and have a look at the logcat output to get out data installation folder. It should be something like:

/<device dependent part>/Android/data/<yourpackage>/files

Thereby most Android systems will have created the path on the device. So we can start transfering it with the necessary data. Create three directories on the device and copy your data there.

• maps (copy your map data to here)
  The maps directory is mandatory. All used maps must be copied to this folder. Copy only the files of the map folders, the maps directory does not accept subfolders. Deleting a map file will cause the SDK to not initialize.
• addr (copy your POI data to here)
  The addr directory contains the POI data and can be left empty if POIs are not used.

• data (copy the rendering data and your license.key to here)
  This directory contains the subfolders bmp, renderer and profiles in the tutorials.

  Generally, all files besides the license.key in the data directory are optional. The SDK will still work without the rendering data, but the map will look incomplete.

  In the top level, the *.cmp files are used for all text renderings on the map. If you delete them, no street or town names will be rendered anymore. All other files in the top level directory of data can be removed, they are only used for the tutorials.

  In the bmp directory you can find all icons that are directly rendered onto the map like POI or restriction icons. If you don't need any of these icons, you can delete them. Have in mind that a blue dot will be rendered at the POI position as a fallback if POI data is present in the addr directory but icons are missing.

  In the renderer directory the map design files reside. You can remove this directory if you don't want to change the map design.

  The profiles directory contains files with predefined route options for various vehicles (see tutorial 5 for loading such a file).

Shortcut

With your SDK delivery comes a sample sdcard folder which contains all necessary data for the complete tutorial. Just replace the files inside the maps folder with your favored maps and copy the Android folder to your sdcard. You need about 4GB free space on your sdcard. For example with adb call: adb push Android /mnt/sdcard/.

Attention

With your copy of the SDK you get a test license.key file. With this license.key you are able to test the SDK until a specified date. Please contact PTV if your test license.key has expired.

Initialize the NavigationSDK

To initialize the NavigationSDK we again edit the MainActivity and add a NavigationSDK.initialize() call. Initialize needs three paths and a map name. The three paths are the maps, addr and data directories you just created. The map name is the file name without the file extension (e.g. deu).

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        File dir = getExternalFilesDir(null);

        try {
            NavigationSDK.initialize(
                new File(dir, "maps"),
                "deu",
                new File(dir, "addr"),
                new File(dir, "data")
            );
        } catch (NavigationException e) {
            e.printStackTrace();
        }
    }
}

That's it. You can now use the NavigationSDK.

Attention

If initialization throws an NavigationException with code: -53 you either forgot to copy the license.key file to your data directory or your test license.key has expired.

Improvements

To avoid reinitializing the NavigationSDK every time the MainActivity is created, you should move the initialization code to a new class maintaining the global application state. Create a new class called Application extending android.app.Application.

public class Application extends android.app.Application {
    @Override
    public void onCreate() {
        super.onCreate();

        File dir = getExternalFilesDir(null);

        try {
            NavigationSDK.initialize(
                new File(dir, "maps"),
                "deu",
                new File(dir, "addr"),
                new File(dir, "data")
            );
        } catch (NavigationException e) {
            e.printStackTrace();
        }
    }
}

Connect the new Application class in AndroidManifest.xml through setting the android:name attribute (Hint: Application class documentation).

Now the SDK will be initialized only once the application is created.

As a helper for further tutorials we also save the paths to static members to easily access these directories later.

public class Application extends android.app.Application {

    private static File basePath;
    private static File mapsPath;
    private static File addrPath;
    private static File dataPath;

    @Override
    public void onCreate() {
        super.onCreate();

        basePath = getExternalFilesDir(null);
        mapsPath = new File(basePath, "maps");
        addrPath = new File(basePath, "addr");
        dataPath = new File(basePath, "data");

        try {
            NavigationSDK.initialize(
                    mapsPath,
                    "deu",
                    addrPath,
                    dataPath
            );
        } catch (NavigationException e) {
            e.printStackTrace();
        }
    }

    public static File getBasePath() {
        return basePath;
    }

    public static File getMapsPath() {
        return mapsPath;
    }

    public static File getAddrPath() {
        return addrPath;
    }

    public static File getDataPath() {
        return dataPath;
    }